Correspondances d’objets
Une intégration manipule ses propres objets chez le fournisseur : une commande Mondu, un client Stripe, un dossier de vérification Sumsub. Une correspondance relie durablement l'un de ces objets à l'objet Ormuz qu'il représente. C'est ce lien qui rend possible la réconciliation, l'idempotence des opérations et l'exposition directe de vos objets métier dans les événements entrants.
Ce qu’est une correspondance
Une correspondance associe, pour une configuration d'intégration donnée, un objet du fournisseur à un objet Ormuz :
Une correspondance relie un objet du fournisseur à l’objet Ormuz qu’il représente, dans le périmètre de la configuration qui l’a créée.
Ce n'est pas un objet métier : c'est une donnée technique de correspondance, propre à la configuration qui l'a créée. Deux configurations distinctes de la même intégration ne partagent pas leurs correspondances, et une intégration ne voit jamais celles d'une autre.
Correspondance vs lien d’objet
Une correspondance d’objet et un lien d’objet répondent à deux questions différentes. La correspondance affirme l’identité technique entre un objet provider et l’objet Ormuz qu’il représente ; elle sert à la corrélation, à l’idempotence et à la résolution d’événements entrants.
Un lien d’objet est au contraire une relation explicite créée par un processus entre deux objets qui restent distincts. Il peut relier deux objets plateforme, un objet plateforme à un objet d’extension, ou deux objets d’extension. Le lien porte une clé métier choisie par le processus et ne signifie jamais que les deux extrémités représentent la même ressource.
| Correspondance | Lien d’objet | |
|---|---|---|
| Question | « quel objet Ormuz représente cet objet provider ? » | « quels objets ont été explicitement reliés ? » |
| Sémantique | Identité/corrélation technique | Relation métier ou opérationnelle |
| Création | Par l’intégration lorsqu’elle détient déjà légitimement la cible, ou par API | Par un node Core ou l’API Object Links |
| Utilisation | Résolution exacte et idempotence | Navigation explicite dans un processus |
Les liens d’objet ne sont jamais inférés à partir des correspondances. Si votre processus a besoin d’une relation fonctionnelle entre deux objets, il doit la créer explicitement.
Comment une correspondance est établie
La règle est unique et sans exception : une correspondance ne crée jamais un accès nouveau, elle fige un accès déjà détenu. Une intégration ne peut donc enregistrer une correspondance que vers un objet qu'elle détenait légitimement à cet instant, c'est-à-dire :
- un objet que le processus lui a transmis en entrée du node ;
- un objet qu'elle vient de lire dans cette exécution grâce à une permission que vous avez accordée ;
- un objet qu'elle vient de créer par la voie normale, à partir d'une proposition d'objet soumise dans le processus ;
- un objet déjà ciblé par une correspondance existante de la même configuration.
Sans cette règle, une intégration pourrait s'ouvrir un accès de proche en proche : enregistrer une correspondance vers un objet simplement aperçu dans un contenu reçu, s'en servir pour le lire, y découvrir d'autres identifiants, et recommencer. La plateforme refuse donc toute correspondance dont la cible n'était pas déjà légitimement accessible.
Il en découle qu'un webhook entrant ou une synchronisation périodique ne peut créer aucune correspondance : s'exécutant hors de tout processus, une telle surface ne détient aucun objet métier. En particulier, une référence externe transmise par le fournisseur n'est jamais interprétée comme un identifiant Ormuz pour créer un lien.
Les correspondances sont donc établies par les nodes de vos processus, au moment où ils créent l'objet chez le fournisseur, et peuvent également être créées explicitement par API.
Ce qu’une correspondance permet de relire
Une fois établie, une correspondance autorise la relecture de sa cible exacte, dans les deux sens.
- Depuis l'identifiant externe — le cas courant. À la réception d'un événement concernant la commande
a5f3…, l'intégration obtient votre commande Ormuz complète, et l'expose comme entrée typée du processus déclenché. - Depuis l'identifiant Ormuz — utile quand le fournisseur ne renvoie que la référence que vous lui aviez transmise, par exemple la liste des factures réglées dans un versement. Cette résolution inverse n'aboutit que si une correspondance de la configuration cible déjà exactement cet objet ; à défaut, rien n'est résolu.
Dans les deux cas, l'objet retourné est le contrat public complet, identique à celui de l'API REST. Aucune permission supplémentaire n'est requise : l'intégration ne choisit pas librement une ressource, elle demande la cible déjà attachée à l'un de ses propres objets.
Ce qu’une correspondance n’autorise pas
- aucune écriture — modifier l'objet exige une permission d'écriture accordée à un node, dans un processus ;
- aucune recherche ni listing — seule la cible exacte est atteignable ;
- aucun objet lié — une correspondance vers un contact n'ouvre pas l'accès à l’entreprise correspondant ;
- aucun autre type — si le type attendu ne correspond pas à celui de la correspondance, la résolution est refusée ;
- aucune autre configuration ni aucun autre marchand — la portée est strictement celle de la configuration qui a créé la correspondance.
Unicité et conflits
Pour une configuration donnée, un objet externe ne peut désigner qu'un seul objet Ormuz. Réenregistrer la même correspondance est sans effet : l'opération est idempotente et retourne la correspondance existante.
Tenter de faire pointer un objet externe déjà associé vers une autre cible échoue explicitement, avec le code extension_object_mapping_conflict. Un conflit n'est jamais résolu par écrasement silencieux : la divergence remonte pour être arbitrée. L'inverse est en revanche permis — plusieurs objets externes peuvent désigner le même objet Ormuz.
La cible est vérifiée à la création : le type doit être un objet adressable, l'objet doit exister et appartenir au bon périmètre.
Durée de vie
Une correspondance survit au consentement qui a permis de la créer. Retirer le node du processus, ou révoquer la permission qui avait servi à lire l'objet, ne supprime pas la correspondance : elle continue d'autoriser la relecture de sa cible exacte.
C'est délibéré — une correspondance qui expirerait rendrait impossible la réconciliation ultérieure, qui est sa raison d'être — et cela reste borné : lecture seule, objet exact, configuration exacte. L'API publique n'expose pas aujourd'hui de suppression individuelle d'une correspondance. La suppression de la configuration d'intégration met également fin aux correspondances de ce périmètre.
Consulter et créer par API
Les correspondances d'une configuration d'intégration sont consultables et filtrables par type et identifiant, de chaque côté du lien.
GET /v1/extension-configs/exc_123/mappings?external_object_type=order GET /v1/extension-configs/exc_123/mappings?ormuz_object_type=order&ormuz_object_id=ord_123
Chaque correspondance a la forme suivante.
| Champ | Description |
|---|---|
id | Identifiant de la correspondance. |
external_object_type | Type d'objet dans le système externe, tel que l'extension le nomme (order, buyer…). |
external_object_id | Identifiant de l'objet dans le système externe. |
ormuz_object_type | Type d'objet métier Ormuz ciblé (order, company, invoice…). |
ormuz_object_id | Identifiant de l'objet Ormuz ciblé. |
metadata | Informations techniques libres attachées au lien. |
Une correspondance peut être créée explicitement, par exemple pour rattacher un objet créé avant l'installation de l'intégration :
POST /v1/extension-configs/exc_123/mappings
{
"external_object_type": "order",
"external_object_id": "a5f3",
"ormuz_object_type": "order",
"ormuz_object_id": "ord_123"
}Ces opérations relèvent de vos propres droits d'administration et ne sont pas une voie ouverte aux intégrations elles-mêmes. Voir Accès aux données par les intégrations pour le modèle complet.