Modes d'intégration
Ormuz peut s'intégrer à une application, un ERP, un CMS e-commerce, un provider financier ou un outil comptable. Le bon mode dépend du système source, du niveau de contrôle technique, de la latence attendue et de la place de l'intégration dans le parcours métier.
Une intégration ne se résume pas à un appel API
Un même cas d'usage peut mobiliser plusieurs surfaces : une API pour créer un objet, un webhook pour signaler un changement, un node pour prendre une décision dans un process et une interface embarquée pour faire intervenir un utilisateur.
Quel que soit le canal, Ormuz ramène les échanges vers des contrats stables : objets métier, événements, configurations de providers et processus. Les détails propres au système tiers restent ainsi isolés de la logique métier du marchand.
Patterns d'intégration courants
Ces patterns ne constituent pas une liste fermée de capacités Ormuz. Une extension donnée peut en exposer plusieurs, ou seulement un sous-ensemble ; sa page d’intégration reste la source de vérité sur ce qui est effectivement disponible.
API directe
Votre application appelle directement l'API Ormuz pour créer, consulter ou mettre à jour des objets métier. Elle reçoit ensuite les webhooks Ormuz pour suivre leurs changements d'état.
- À privilégier pour
- Application sur mesure ou équipe technique autonome.
- Responsabilité
- L'équipe qui intègre Ormuz pilote la logique, l'idempotence et le suivi des identifiants.
Plugin
Un module installé dans un outil tiers adapte ses objets au modèle Ormuz et encapsule les appels API, les webhooks et les correspondances d'identifiants.
- À privilégier pour
- CMS e-commerce, ERP ou back-office disposant d’un système d’extensions.
- Responsabilité
- L'éditeur du plugin maintient sa compatibilité avec l'outil hôte et Ormuz.
Extension Ormuz
Vous configurez une extension dans Ormuz, puis ses capacités déclarées peuvent exposer des objets externes, événements, nodes ou interactions provider.
- À privilégier pour
- Service ou système disponible dans le catalogue d’extensions Ormuz.
- Responsabilité
- La page de l’extension précise ses capacités, son statut de disponibilité et les choix qui restent à la charge du marchand.
Node de process
Une capacité tierce devient une étape composable d'un processus : lire une donnée, déclencher une action, enrichir un objet ou produire une décision.
- À privilégier pour
- Action provider qui participe directement à une décision ou à un parcours métier.
- Responsabilité
- Le concepteur du process choisit quand exécuter le node et comment traiter ses résultats ou erreurs.
Webhook tiers entrant
Un système externe pousse un événement vers Ormuz. Le signal est authentifié et peut déclencher un process sans prétendre qu'un objet métier Ormuz a déjà changé.
- À privilégier pour
- Provider capable de notifier rapidement et de façon fiable ses changements.
- Responsabilité
- Le provider émet le signal ; le process Ormuz décide de ses conséquences métier.
Synchronisation planifiée
Ormuz interroge périodiquement une API ou une source de données pour détecter les créations et modifications survenues depuis la dernière synchronisation.
- À privilégier pour
- ERP, outil comptable ou système ne proposant pas de webhook exploitable.
- Responsabilité
- Le périmètre, la fréquence et la source de vérité doivent être définis explicitement.
Échange de fichiers
Les données sont importées ou exportées sous forme de fichiers structurés, par exemple CSV, XML, SEPA ou dépôt SFTP.
- À privilégier pour
- Systèmes anciens, échanges comptables, traitements batch ou partenaires financiers.
- Responsabilité
- Chaque échange doit avoir un format versionné et un rapport d'acceptation ou de rejet.
Parcours utilisateur redirigé ou embarqué
Une interface Ormuz ou provider est ouverte depuis un outil tiers au moyen d'une redirection, d'une URL d’accès temporaire ou d'un composant embarqué lorsque l’intégration le prévoit.
- À privilégier pour
- Onboarding, collecte de documents, validation, paiement ou autre action humaine.
- Responsabilité
- Le système hôte fournit le contexte et récupère l'état final par API ou webhook.
Choisir le mode principal
| Situation | Mode recommandé |
|---|---|
| Vous contrôlez une application sur mesure | API directe |
| Vous utilisez un outil extensible comme un CMS ou un ERP | Plugin |
| Le service est disponible dans le catalogue Ormuz | Extension Ormuz |
| Une action tierce fait partie d'un processus | Node de process |
| Le tiers sait pousser ses changements | Webhook entrant |
| Le tiers ne propose pas de webhook fiable | Synchronisation planifiée |
| Le tiers ne propose pas d'API exploitable | Échange de fichiers |
| Une personne doit agir dans le parcours | Expérience embarquée |
Les modes se combinent
Le tableau précédent aide à choisir un point d'entrée, pas une architecture exclusive. Une intégration e-commerce peut utiliser un plugin pour créer une session, une expérience embarquée pour le checkout et un webhook pour mettre à jour la commande. Une extension Ormuz peut, elle, exposer plusieurs nodes utilisables dans des processus différents.
Identifier la source de vérité
Précisez quel système fait autorité pour le client, la facture, le paiement et chaque statut partagé.
Choisir le déclencheur
Action utilisateur, appel API, événement tiers, planification ou dépôt de fichier.
Définir la conséquence métier
Un process explicite porte les décisions, les créations d'objets et les actions à exécuter.
Du signal provider à l'événement métier
Un webhook entrant décrit d'abord ce qui s'est produit chez le provider. Par exemple, extension.stripe.payment_intent.succeeded constitue un signal Stripe authentifié. Il ne signifie pas encore qu'un paiement Ormuz a été créé ou qu'une facture est payée.
Un process déclenché par ce signal applique les règles du marchand, rapproche les objets concernés et exécute les mutations métier nécessaires. Les événements canoniques, comme payment.received ou invoice.paid, décrivent ensuite un état réellement établi dans Ormuz.
Points à vérifier par contrat
| Principe | Attente |
|---|---|
| Idempotence | Vérifiez la clé ou le mécanisme prévu pour rejouer l’opération sans dupliquer un effet. |
| Identifiants explicites | Définissez comment l’objet externe est corrélé à son contexte ou à son objet Ormuz. |
| Traçabilité | Conservez les identités nécessaires pour relier un échange à l’objet, au provider ou au processus concerné. |
| Erreurs actionnables | Le contrat doit distinguer les erreurs permanentes des situations pouvant être retentées. |
| Sécurité | Appliquez les mécanismes prévus par le canal : authentification, signature, permissions et protection des données. |
| Rejeu | Documentez si le canal autorise un replay, un retry ou uniquement une nouvelle opération métier. |
| Évolution | Vérifiez quelles companies sont stabilisées par Ormuz et lesquelles restent spécifiques au provider ou au système hôte. |