Groupe d’entreprises (company_group)
Un company_group est un regroupement logique de companies. Il permet d'appliquer des politiques communes — limite de crédit partagée, règle de conformité, segment tarifaire — à un ensemble d’entreprises sans dupliquer la configuration sur chaque company.
Rôle
Le groupe n'a pas de sémantique métier figée : c'est un conteneur nommé dont l'usage est défini par vos processus. Exemples courants :
- Grands comptes — companies bénéficiant d'une limite de crédit élevée ou de conditions de paiement étendues.
- Partenaires stratégiques — fournisseurs éligibles à des programmes de financement prioritaires.
- Liste de surveillance — companies faisant l'objet d'un contrôle de conformité renforcé.
- Segment tarifaire — acheteurs auxquels s'appliquent des conditions commerciales spécifiques.
La relation est de type plusieurs-à-plusieurs : une company peut appartenir à plusieurs groupes, et un groupe peut contenir un nombre illimité de companies.
Identifiant et structure
Chaque groupe porte un identifiant stable préfixé par cgp_. Sa structure est intentionnellement minimaliste — les données métier vivent sur les companies et les processus, pas sur le groupe lui-même.
{
"object": "company_group",
"id": "cgp_7fa1b2c3d4e5f6a7",
"name": "Grands comptes FR",
"description": "Acheteurs bénéficiant d'une limite de crédit supérieure à 500 k€",
"source_reference": "SEGMENT-GC-FR",
"metadata": {},
"created_at": "2026-01-08T09:00:00.000Z",
"updated_at": "2026-01-08T09:00:00.000Z"
}Champs
| Champ | Type | Requis | Description |
|---|---|---|---|
id | string | oui | Identifiant du groupe (préfixe cgp_). |
object | string | oui | Toujours "company_group". |
merchant_id | string | oui | Marchand propriétaire du groupe. |
name | string | oui | Nom libre du groupe. |
description | string | non | Description optionnelle. |
source_reference | string | non | Référence dans votre système. |
metadata | object | non | Map plate de scalaires `string | number | boolean`, selon la convention metadata de l’API. |
created_at | datetime | oui | Date de création. |
updated_at | datetime | oui | Date de dernière mise à jour. |
Gestion des membres
Les appartenances se gèrent depuis les deux extrémités de la relation, selon le sens le plus pratique dans votre contexte.
Depuis le groupe
| Endpoint | Effet |
|---|---|
GET /v1/company-groups/:id/companies | Liste paginée des companies membres (résumé : id, display_name, suspended). |
POST /v1/company-groups/:id/company-links | Remplace atomiquement la liste complète des membres. Envoie { "company_ids": ["cmp_…", …] }. Les companies absentes de la liste sont retirées ; les nouvelles sont ajoutées. |
DELETE /v1/company-groups/:id/company-links/:company_id | Retire une company du groupe sans toucher aux autres. |
Depuis la company
| Endpoint | Effet |
|---|---|
GET /v1/companies/:id/company-groups | Liste des groupes auxquels la company appartient. |
POST /v1/companies/:id/company-group-links | Remplace atomiquement l'ensemble des groupes de la company. Envoie { "company_group_ids": ["cgp_…", …] }. |
DELETE /v1/companies/:id/company-group-links/:company_group_id | Retire la company d'un groupe sans toucher aux autres. |
Les deux opérations de remplacement (company-links) sont atomiques et différentielles : seuls les changements effectifs déclenchent des événements. Ajouter une company déjà membre ou retirer une company absente est silencieux.
POST /v1/company-groups/cgp_7fa1/company-links
{
"company_ids": ["cmp_3a8f", "cmp_4b9e", "cmp_5c0f"]
}Chaque changement par rapport à l’état précédent émet un événement company.assigned_to_group ou company.removed_from_group.
Pour filtrer la liste des companies par groupe lors d'un appel à GET /v1/companies, utilisez le paramètre group_id :
GET /v1/companies?group_id=cgp_7fa1
Suppression
Un groupe ne peut être supprimé que s'il ne contient plus aucune company. Toute tentative de suppression avec des membres retourne une erreur 409 :
DELETE /v1/company-groups/cgp_7fa1 409 Conflict
{
"error": {
"message": "Cannot delete a group that still has companies assigned to it"
}
}Pour supprimer un groupe non vide, videz-le d'abord via POST /v1/company-groups/:id/company-links avec { "company_ids": [] }, puis supprimez-le.
Dans les processus
Le node check_company_group_membership vérifie si une company appartient à un groupe donné et route le processus en conséquence :
| Node | Rôle | Entrées / sorties clés |
|---|---|---|
check_company_group_membership | Vérifie l'appartenance d'une company à un groupe et route en conséquence | Accepte : company, company_group_id · Route in_group / not_in_group · Produit : is_member |
Ce node est typiquement utilisé pour appliquer des règles différenciées selon le segment d'une company : approbation automatique pour les membres d'un groupe de confiance, vérification renforcée pour les companies sous surveillance, conditions de crédit spéciales pour les grands comptes.
Événements
Le groupe émet ses propres événements de cycle de vie, et chaque changement d'appartenance produit un événement sur la company concernée.
| Événement | Déclencheur |
|---|---|
company_group.created | Le groupe vient d'être créé. |
company_group.updated | Le groupe a été mis à jour (nom, description…). |
company_group.deleted | Le groupe a été supprimé. |
company.assigned_to_group | Une company a été ajoutée au groupe. |
company.removed_from_group | Une company a été retirée du groupe. |
Les événements d'appartenance (company.assigned_to_group et company.removed_from_group) ont le payload suivant :
{
"company_id": "cmp_3a8f…",
"company_group_id": "cgp_7fa1…"
}Lors d'un remplacement atomique portant sur plusieurs companies, un événement distinct est émis par changement effectif — pas un seul événement groupé.