Integration modes
Ormuz can integrate with an application, ERP, e-commerce CMS, financial provider, or accounting tool. The right mode depends on source system, desired technical control, expected latency, and the integration's role in the business journey.
An integration is more than an API call
One use case may involve several surfaces: API to create an object, webhook to signal a change, node to make a process decision, and embedded interface for user participation.
Whatever the channel, Ormuz brings exchanges back to stable contracts: business objects, events, provider configurations, and processes. Third-party details remain isolated from merchant business logic.
First decide who should own the integration and which system is authoritative for each piece of data. The technical channel comes afterward.
Common integration patterns
These patterns are not a closed list of Ormuz capabilities. A given extension may expose several or only a subset; its integration page remains the source of truth for what is actually available.
API directe
Your application calls the Ormuz API directly to create, retrieve, or update business objects. It then receives Ormuz webhooks to track state changes.
- Prefer for
- Custom application or autonomous technical team.
- Responsibility
- The integrating team owns logic, idempotency, and identifier tracking.
Plugin
A module installed in a third-party tool adapts its objects to the Ormuz model and encapsulates API calls, webhooks, and identifier mappings.
- Prefer for
- E-commerce CMS, ERP, or back office with an extension system.
- Responsibility
- The plugin publisher maintains compatibility with both the host tool and Ormuz.
Extension Ormuz
You configure an extension in Ormuz; its declared capabilities may expose external objects, events, nodes, or provider interactions.
- Prefer for
- Service or system available in the Ormuz extension catalog.
- Responsibility
- The extension page specifies its capabilities, availability status, and choices that remain the merchant's responsibility.
Process node
A third-party capability becomes a composable process step: read data, trigger an action, enrich an object, or produce a decision.
- Prefer for
- Provider action participating directly in a business decision or journey.
- Responsibility
- The process designer chooses when to execute the node and how to handle its results or errors.
Inbound third-party webhook
An external system pushes an event to Ormuz. The signal is authenticated and may trigger a process without claiming that an Ormuz business object has already changed.
- Prefer for
- Provider capable of quickly and reliably notifying changes.
- Responsibility
- The provider emits the signal; the Ormuz process decides its business consequences.
Scheduled synchronization
Ormuz periodically queries an API or data source to detect creations and changes since the last synchronization.
- Prefer for
- ERP, accounting tool, or system without a usable webhook.
- Responsibility
- Scope, frequency, and source of truth must be explicitly defined.
File exchange
Data is imported or exported as structured files, for example CSV, XML, SEPA, or SFTP deposits.
- Prefer for
- Legacy systems, accounting exchanges, batch processing, or financial partners.
- Responsibility
- Every exchange must have a versioned format and an acceptance/rejection report.
Redirected or embedded User Journey
An Ormuz or provider interface is opened from a third-party tool through a redirect, temporary access URL, or embedded component when the integration supports it.
- Prefer for
- Onboarding, document collection, validation, payment, or another human action.
- Responsibility
- The host system provides context and retrieves final state through API or webhook.
Choose the primary mode
| Situation | Recommended mode |
|---|---|
| You control a custom application | Direct API |
| You use an extensible tool such as a CMS or ERP | Plugin |
| The service is available in the Ormuz catalog | Extension Ormuz |
| A third-party action is part of a process | Process node |
| The third party can push its changes | Inbound webhook |
| The third party does not provide a reliable webhook | Scheduled synchronization |
| The third party does not expose a usable API | File exchange |
| A person must act in the journey | Embedded experience |
Modes can be combined
The table above helps choose an entry point, not an exclusive architecture. An e-commerce integration may use a plugin to create a session, an embedded experience for checkout, and a webhook to update the order. An Ormuz extension may expose several nodes used in different processes.
Identify the source of truth
Specify which system is authoritative for customer, invoice, payment, and each shared status.
Choose the trigger
User action, API call, third-party event, schedule, or file deposit.
Define the business consequence
An explicit process carries decisions, object creation, and actions to execute.
From provider signal to business event
An inbound webhook first describes what happened at the provider. For example,
extension.stripe.payment_intent.succeeded is an authenticated Stripe signal. It does not yet mean an Ormuz payment was created or an invoice paid.
A process triggered by this signal applies merchant rules, reconciles the relevant objects, and performs required business mutations. Canonical events such as payment.received or
invoice.paid then describe a state genuinely established in Ormuz.
A provider event triggers a business decision; it does not implicitly modify Ormuz objects.
Things to verify per contract
| Principe | Wait |
|---|---|
| Idempotence | Check the key or mechanism intended to replay the operation without duplicating an effect. |
| Identifiants explicites | Define how the external object is correlated to its context or Ormuz object. |
| Traceability | Preserve identities needed to link an exchange to the object, provider, or process concerned. |
| Erreurs actionnables | The contract must distinguish permanent errors from situations that can be retried. |
| Security | Apply mechanisms intended by the channel: authentication, signature, permissions, and data protection. |
| Rejeu | Document whether the channel permits replay, retry, or only a new business operation. |
| Evolution | Check which companies are stabilized by Ormuz and which remain specific to the provider or host system. |