Groupes de contacts¶

Un groupe peut contenir des correspondants de type contact, user ou entity. Il appartient à son créateur et peut être partagé avec des entités.

Les administrateurs disposant de admin_contacts voient tous les groupes hors mode profil. Les autres utilisateurs voient leurs groupes et ceux partagés avec leurs entités. La modification ou la suppression d’un groupe est réservée à son propriétaire ou à un administrateur.

Structure d’un groupe¶

Valeur	Type	Description
`id`	integer	Identifiant du groupe
`label`	string	Libellé
`description`	string	Description
`owner`	integer	Identifiant du propriétaire
`labelledOwner`	string	Nom affiché du propriétaire
`entities`	array	Identifiants des entités de partage
`nbCorrespondents`	integer	Nombre de correspondants
`canUpdateCorrespondents`	boolean	Autorisation d’ajouter ou retirer des correspondants

Lister les groupes¶

Route¶

GET /rest/contactsGroups

Query string¶

Valeur	Type	Obligatoire	Description
`profile`	boolean	Non	Si renseigné, applique le périmètre du profil même à un administrateur

Retour¶

Code HTTP	Type	Description
`200`	object	Liste dans `contactsGroups`

{
  "contactsGroups": [
    {
      "id": 3,
      "label": "Partenaires",
      "description": "Partenaires externes",
      "owner": 21,
      "labelledOwner": "Bernard BLIER",
      "entities": [1, 2],
      "nbCorrespondents": 12,
      "canUpdateCorrespondents": true
    }
  ]
}

Créer un groupe¶

Route¶

POST /rest/contactsGroups

Body¶

Valeur	Type	Obligatoire	Description
`label`	string	Oui	Libellé du groupe
`description`	string	Oui	Description du groupe
`entities`	array	Non	Identifiants des entités de partage

Sans admin_contacts, les entités doivent appartenir au périmètre de l’utilisateur. Le propriétaire est automatiquement l’utilisateur connecté.

{
  "label": "Partenaires",
  "description": "Partenaires externes",
  "entities": [1, 2]
}

Retour¶

Code HTTP	Description	Exemple
`200`	Groupe créé	`{"id":3}`
`400`	Body invalide ou entité hors périmètre	`{"errors":"Body label is empty or not a string"}`

Fusionner des groupes¶

Route¶

PUT /rest/contactsGroups/merge

Le propriétaire peut fusionner ses propres groupes. Un utilisateur disposant de admin_contacts peut fusionner tout groupe existant.

Body¶

Valeur	Type	Obligatoire	Description
`label`	string	Oui	Libellé du nouveau groupe
`description`	string	Oui	Description du nouveau groupe
`contactsGroups`	array	Oui	Identifiants des groupes sources

{
  "label": "Tous les partenaires",
  "description": "Regroupement des partenaires",
  "contactsGroups": [3, 4]
}

Les partages d’entités et les correspondants sont réunis sans doublon. Les groupes sources sont ensuite supprimés.

Retour¶

Code HTTP	Description
`200`	Identifiant du nouveau groupe dans `id`
`400`	Body invalide
`403`	Groupe inexistant ou hors périmètre de modification

Consulter un groupe¶

Route¶

GET /rest/contactsGroups/{id}

Paramètres¶

Valeur	Emplacement	Type	Obligatoire	Description
`id`	URL	integer	Oui	Identifiant du groupe
`profile`	Query string	boolean	Non	Applique le périmètre du profil pour l’arbre des entités

Retour¶

Code HTTP	Description
`200`	Groupe dans `contactsGroup` et arbre des entités dans `entities`
`403`	Groupe inexistant ou hors périmètre

Chaque nœud de entities contient notamment id, entity_id, entity_label, parent, text, icon et un objet state avec opened, disabled et éventuellement selected.

Modifier un groupe¶

Route¶

PUT /rest/contactsGroups/{id}

Le body contient label, description et éventuellement entities, comme lors de la création.

Retour¶

Code HTTP	Description
`204`	Groupe modifié, sans contenu
`400`	Body invalide ou entité hors périmètre
`403`	Groupe inexistant ou hors périmètre de modification

Supprimer un groupe¶

Route¶

DELETE /rest/contactsGroups/{id}

La suppression efface également toutes les associations aux correspondants.

Retour¶

Code HTTP	Description
`204`	Groupe supprimé, sans contenu
`403`	Groupe inexistant ou hors périmètre de modification

Dupliquer un groupe¶

Route¶

POST /rest/contactsGroups/{id}/duplicate

Le groupe dupliqué appartient à l’utilisateur connecté, n’est partagé avec aucune entité et reprend tous les correspondants. Son libellé reçoit un suffixe numérique.

Retour¶

Code HTTP	Description	Exemple
`200`	Copie créée	`{"id":8}`
`403`	Groupe inexistant ou hors périmètre

Lister les correspondants d’un groupe¶

Route¶

GET /rest/contactsGroups/{id}/correspondents

Query string¶

Valeur	Type	Obligatoire	Valeur par défaut	Description
`offset`	integer	Non	`0`	Décalage de pagination
`limit`	integer	Non	`250`	Nombre de correspondants retournés
`search`	string	Non		Recherche sur le nom et l’adresse
`types[]`	array	Non		Types à retourner : `contact`, `user`, `entity`
`order`	string	Non		`asc` ou `desc`
`orderBy`	string	Non	`name`	`name` ou `type`
`contactM2mMode`	boolean	Non	`false`	Ne retourne que les contacts Maarch2Maarch disponibles

Retour¶

{
  "correspondents": [
    {"id":21,"type":"contact","name":"Clark Kent","email":"clark@example.org"}
  ],
  "count": 1,
  "allCorrespondents": [{"id":21,"type":"contact"}]
}

Code HTTP	Description
`200`	Liste paginée, nombre filtré et liste minimale complète
`403`	Groupe inexistant ou hors périmètre

Ajouter des correspondants¶

Route¶

POST /rest/contactsGroups/{id}/correspondents

Body¶

{
  "correspondents": [
    {"id":21,"type":"contact"},
    {"id":7,"type":"user"},
    {"id":2,"type":"entity"}
  ]
}

correspondents est un tableau non vide. Chaque élément contient un id entier et un type parmi contact, user et entity. Les associations déjà présentes sont ignorées.

Le propriétaire ou un administrateur peut modifier la liste. Le privilège add_correspondent_in_shared_groups_on_profile autorise aussi l’opération sur un groupe visible dans le périmètre partagé.

Retour¶

Code HTTP	Description
`204`	Correspondants ajoutés, sans contenu
`400`	Tableau absent ou invalide
`403`	Groupe hors périmètre

Retirer des correspondants¶

Route¶

DELETE /rest/contactsGroups/{id}/correspondents

Le body et les règles de droits sont identiques à ceux de l’ajout.

Retour¶

Code HTTP	Description
`204`	Correspondants retirés, sans contenu
`400`	Tableau absent ou invalide
`403`	Groupe hors périmètre

Lister les entités utilisables pour le partage¶

Route¶

GET /rest/contactsGroupsEntities

Query string¶

Valeur	Type	Obligatoire	Description
`profile`	boolean	Non	Applique le périmètre du profil même à un administrateur

Retour¶

Code HTTP	Type	Description
`200`	object	Arbre des entités actives dans `entities`

Les entités hors périmètre sont présentes mais portent state.disabled: true.

Rechercher les groupes d’un correspondant¶

Route¶

GET /rest/contactsGroupsCorrespondents

Query string¶

Valeur	Type	Obligatoire	Description
`correspondentId`	integer	Oui	Identifiant du correspondant
`correspondentType`	string	Oui	Type du correspondant : `contact`, `user` ou `entity`
`profile`	boolean	Non	Applique le périmètre du profil même à un administrateur

Retour¶

{
  "contactsGroups": [
    {"id":3,"label":"Partenaires","canUpdateCorrespondents":true}
  ]
}

Code HTTP	Description
`200`	Groupes visibles contenant le correspondant
`400`	Identifiant ou type absent ou invalide