Entreprise (company)

Rôle

Une company peut d’abord représenter l’identité propre du marchand. Dans ce cas,is_self vaut true en lecture seule. Elle peut aussi qualifier un partenaire commercial sur deux dimensions orthogonales : is_buyer et is_supplier. Ces indicateurs sont indépendants — une même entité peut être marchand, acheteur et fournisseur selon les besoins du modèle.

• Acheteur (is_buyer: true) — la company reçoit des factures, effectue des paiements et peut bénéficier d'une limite de crédit.
• Fournisseur (is_supplier: true) — la company émet des factures, reçoit des paiements et peut faire l'objet d'un financement.

La qualification peut être posée à la création ou modifiée ultérieurement via le node set_company_type. Elle oriente les processus aval : les nodes de facturation, de crédit ou de réconciliation l'utilisent pour valider leurs entrées.

Identifiant et structure

Chaque company porte un identifiant stable préfixé par cmp_. Cet identifiant est stable dans le temps et utilisable sans appel API supplémentaire pour identifier le type de l'objet.

{
  "object": "company",
  "id": "cmp_3a8f1d9c2b4e7f6a",
  "legal_name": "Dupont Industries SAS",
  "trade_name": "Dupont Industries",
  "display_name": "Dupont Industries",
  "legal_form": "SAS",
  "registration_number": "123456789",
  "registration_country": "FR",
  "tax_identifier": "FR12345678901",
  "registered_address": {
    "line1": "12 rue de la Paix",
    "city": "Paris",
    "postal_code": "75001",
    "country": "FR"
  },
  "incorporation_date": "2018-03-15",
  "share_capital": 1000000,
  "currency": "EUR",
  "is_self": false,
  "suspended": false,
  "suspended_at": null,
  "suspension_reason": null,
  "is_buyer": true,
  "is_supplier": false,
  "source_reference": "CLIENT-00842",
  "metadata": {},
  "created_at": "2026-01-10T09:00:00.000Z",
  "updated_at": "2026-06-15T14:32:00.000Z"
}

Champs

Suspension

Une company peut être suspendue manuellement via POST /v1/companies/:id/suspend, qui accepte un reason optionnel. La suspension positionne suspended: true, horodate suspended_at et enregistre suspension_reason. Elle émet l'événement company.suspended que vos processus peuvent écouter.

La suspension est levée via POST /v1/companies/:id/reactivate, qui remet suspended à false et émet company.reactivated.

Suspendre une company ne suspend pas ses contacts. Le blocage d'une personne physique se pilote au niveau du contact, avec son propre suspended.

Relations

La company est le point d'ancrage de la plupart des objets commerciaux et financiers de la plateforme.

Les contacts d'une company peuvent être résolus par rôle et niveau de certification à une date donnée via GET /v1/companies/:id/contacts/resolve. Ce point d'accès est utile pour identifier le bon interlocuteur (représentant légal, autorisateur de paiement…) dans un processus. Les rôles de contact sont documentés dans la page Rôle de contact.

Créance et dette

La plateforme calcule deux indicateurs financiers en temps réel pour chaque company :

• Receivable (GET /v1/companies/:id/receivable) — montant total dû par la company en tant qu'acheteur, calculé sur les factures émises et non encore intégralement réglées.
• Payable (GET /v1/companies/:id/payable) — montant total dû à la company en tant que fournisseur.

GET /v1/companies/cmp_3a8f/receivable

{
  "object": "receivable",
  "buyer_id": "cmp_3a8f1d9c2b4e7f6a",
  "currency": "EUR",
  "balance_excluding_tax": 120000,
  "balance_including_tax": 144000,
  "balance_due_excluding_tax": 40000,
  "balance_due_including_tax": 48000,
  "oldest_due_date": "2026-05-01",
  "latest_due_date": "2026-07-31",
  "computed_at": "2026-06-17T10:00:00.000Z"
}

Ces valeurs sont calculées dynamiquement à partir des factures et paiements courants. Le node calculate_receivable expose ce calcul dans les processus d'orchestration.

Dans les processus

Plusieurs nodes du catalogue opèrent directement sur les companies. Les nodes aval (facturation, crédit, paiement) acceptent systématiquement une company en entrée pour rattacher leurs objets à la bonne entreprise.

Le node search_company effectue une recherche par identité métier — source_reference, registration_number, tax_identifier ou legal_name + pays — et route selon que la company existe déjà ou non. Ce pattern est central dans les processus d'onboarding pour éviter les doublons.

GET /v1/companies/search
  ?registration_number=123456789
  &country=FR

{
  "object": "company_search_result",
  "company": {
    "id": "cmp_3a8f",
    "registration_number": "123456789",
    "registration_country": "FR"
  },
  "matched_by": "registration_number"
}

Événements

Chaque transition significative émet un événement livré via webhook. L'objet company complet est inclus dans le payload — aucun appel API supplémentaire n'est nécessaire pour récupérer l'état courant.

La configuration des webhooks et la liste complète des événements sont documentées dans Recevoir des webhooks et le catalogue des événements.