Principes fondamentaux du modèle métier
Le modèle Ormuz représente les acteurs, documents, décisions et mouvements financiers nécessaires pour orchestrer un parcours B2B. Ses objets publics restent indépendants des providers et des systèmes techniques qui alimentent la plateforme.
Un modèle orienté résultats métier
Chaque objet répond à une question métier précise. Une company représente une entreprise ; une checkout_session porte une tentative de checkout ; un psp_payment décrit un paiement côté acheteur ; un payment représente un encaissement reçu côté marchand ; une payment_allocation explique comment ce mouvement est affecté aux documents métier.
Cette séparation évite de faire porter plusieurs significations à un même objet. Elle permet également de changer de provider ou de système source sans modifier la logique métier des process.
Quand une notion mérite-t-elle un objet ?
Une notion devient généralement un objet public lorsqu'elle possède une identité, un cycle de vie, des relations, des événements ou une utilité directe dans les process. Une information purement descriptive reste un champ de l'objet qui la porte.
| Critère | Exemple |
|---|---|
| Le process doit manipuler la notion directement | onboarding_case, invoice |
| La plateforme fait évoluer son état | checkout_session, dispute |
| La notion produit des événements métier | psp_payment, payment |
| Elle porte une relation ou une preuve durable | contact_role, compliance_check |
| Elle résulte d'un calcul réutilisable | receivable, credit_exposure |
À l'inverse, une adresse, une devise, une référence de commande ou un montant ne deviennent pas des objets autonomes sans besoin métier propre. Ils restent des propriétés structurées ou scalaires.
Une identité publique et un type explicite
Les ressources persistantes exposent un id préfixé et un champ object. Le préfixe facilite la lecture et empêche de confondre des identifiants de types différents, par exemple cmp_* pour une company, inv_* pour une facture ou cs_* pour une session de checkout.
| Champ | Garantie |
|---|---|
id | Identifiant stable à conserver dans les intégrations. |
object | Type fonctionnel de la ressource retournée. |
merchant_id | Périmètre marchand auquel l'objet appartient. |
created_at, updated_at | Repères temporels exposés lorsque le contrat de l'objet les prévoit. |
Les champs de relation comme company_id, invoice_id ou checkout_session_idcontiennent les identifiants des objets liés.
Périmètre marchand et source de vérité
Un objet métier appartient à un marchand. Les relations entre objets doivent rester dans ce même périmètre, sauf contrat public indiquant explicitement le contraire. Cette règle évite qu'un process ou une intégration relie accidentellement des données de marchands différents.
L'autorité ne se décide pas une fois pour tout l'objet. Elle peut varier selon le champ et selon la phase de son cycle de vie. Une facture peut par exemple porter une référence et des montants contrôlés par le système comptable une fois émise, tout en conservant un settlement_status calculé par Ormuz à partir des paiements et de leurs imputations.
Lorsqu'un système externe tente de synchroniser un champ dont Ormuz est source de vérité, il ne peut pas l'écraser silencieusement. Si la valeur diverge, l'opération échoue afin que le processus traite explicitement le conflit. À l'inverse, un champ dont le rôle externe est autoritaire est mis à jour depuis cette source.
| Référence | Usage |
|---|---|
id Ormuz | Identifier et relier la ressource dans les APIs, événements et process Ormuz. |
source_reference | Conserver l'identifiant métier de la source de vérité, par exemple un ID ERP, CRM ou e-commerce. |
| Référence provider | Identifier l'objet dans un service technique externe sans remplacer la référence métier. |
source_reference si ce provider n'est pas la source de vérité métier de l'objet.paid dans Ormuz alors que l'ERP ne l'a pas encore reflété. Chaque valeur reste vraie sur son propre plan d'autorité.Des relations explicites et des objets utilisables
Les relations importantes sont portées par des champs publics explicites. Une facture peut référencer sa company ; un paiement PSP peut référencer une session de checkout ; une commande peut être reliée aux factures qu'elle a produites.
Dans les requêtes API, ces relations sont généralement exprimées avec des IDs. Dans un process, un node qui déclare produire une company, une invoice ou un contactdoit retourner un objet complet et directement réutilisable, pas une simple enveloppe contenant son ID.
| Forme | Utilisation |
|---|---|
company_id: "cmp_*" | Créer, filtrer ou relier une ressource via l'API. |
company: platform.company | Transmettre un objet typé entre deux nodes. |
| Relation dédiée | Porter une sémantique propre, par exemple le rôle d'un contact dans une company. |
Une relation métier riche ne doit pas être réduite à un champ libre. Par exemple, contact_role porte le type de rôle, son niveau de certification, sa validité et ses pouvoirs éventuels.
Les statuts décrivent un cycle de vie précis
Un statut doit répondre à une question fonctionnelle unique. Lorsqu'un objet porte plusieurs dimensions, elles sont séparées. Une session de checkout distingue par exemple la fin du parcours avec status du résultat financier avec payment_status.
Les transitions importantes produisent des événements métier. Un événement canonique affirme qu'un état existe réellement dans Ormuz : invoice.issued, checkout_session.completed ou onboarding_case.rejected. Un signal reçu d'un provider décrit d'abord ce qui s'est passé chez ce provider et ne vaut pas automatiquement mutation d'un objet Ormuz.
Un brouillon prépare une création, il n'est pas encore une ressource
Un brouillon est une proposition de création d'un objet plateforme. Il suit le contrat de l'objet cible, mais ne possède pas d'ID. Il peut provenir d'un formulaire, d'un import, d'un calcul ou de l'adaptation d'un objet provider.
{
"id": "cmp_abc123",
"object": "company",
"merchant_id": "mer_abc123",
"legal_name": "ACME France SAS",
"trade_name": "ACME France",
"display_name": "ACME France",
"registration_number": "123456789",
"registration_country": "FR",
"source_reference": "CRM-1042"
}{
"object": "company",
"legal_name": "ACME France SAS",
"registration_number": "123456789",
"registration_country": "FR",
"is_buyer": true,
"is_supplier": false,
"source_reference": "CRM-1042"
}| Objet persistant | Brouillon de création |
|---|---|
| Possède un ID. | Ne possède pas d'ID. |
| Peut être référencé durablement. | Reste une proposition tant qu'il n'est pas soumis. |
| Suit son cycle de vie et produit ses événements. | Suit autant que possible le contrat de création de la cible. |
| Peut être mis à jour par les opérations prévues par son contrat. | Est réservé à la création, pas à la modification d'un objet existant. |
Lorsqu'un brouillon vient d'un provider, il peut porter une provenance _source permettant de relier la proposition au provider, à son objet et à l'événement d'origine. Les données métier restent dans les champs métier du brouillon.
Garanties de modélisation
- Utiliser les identifiants fournis par Ormuz pour référencer les objets dans les intégrations.
- Donner à chaque objet une responsabilité métier clairement délimitée.
- Définir la source de vérité de chaque donnée partagée entre systèmes.
- Conserver les références métier externes sans les confondre avec les IDs providers.
- Exprimer les relations structurantes avec des champs ou objets typés explicites.
- Retourner des objets complets lorsqu'un node promet un objet plateforme en sortie.
- Séparer les axes de statut lorsqu'ils répondent à des questions différentes.
- Faire produire les événements canoniques par une mutation métier réellement établie.
- Utiliser les brouillons uniquement pour préparer la création de nouveaux objets.
- Préserver la provenance et l'idempotence lors des imports et intégrations providers.