Vous avez un projet d’intégration API et vous voulez un accompagnement sur mesure, de la stratégie au run ? Découvrez notre offre d’intégration API sur mesure.
Au-delà du choix d’un protocole, d’un SDK ou d’un outil, le vrai sujet reste toujours le même: qualité du mapping, idempotence des traitements, gestion des erreurs, observabilité, coût de maintenance et lisibilité du run côté métier. C’est à ce niveau que se joue la robustesse réelle d’une intégration API.
Si vous cherchez un cadrage plus large sur la conception, le delivery et l’exploitation de vos flux, découvrez aussi notre expertise en intégration API pour structurer un socle durable, pilotable et utile en production.
Dolibarr est très apprécié pour sa simplicité, mais les intégrations deviennent vite délicates quand les flux se multiplient (e-commerce, facturation, stock multi-dépôts, CRM). Sans cadre technique, les appels API se dispersent dans le code et la maintenance devient fragile.
Nous avons donc construit un SDK Dolibarr sous Symfony pour centraliser auth, mapping, gestion d’erreurs, résilience et observabilité. L’objectif est de livrer plus vite sans perdre la maîtrise des flux en production.
Pour la vision globale: Intégration API.
L’API REST Dolibarr couvre les besoins courants (tiers, produits, commandes, factures), mais les projets réels exposent rapidement des sujets sensibles: statuts documentaires, arrondis, droits API, référentiels incomplets et cohérence inter-modules.
Le SDK sert à encapsuler ces contraintes avec des conventions homogènes et des validations métier explicites, afin d’éviter les bricolages ponctuels qui cassent lors des évolutions.
Le SDK est organisé en couches: `DolibarrAuthProvider`, `DolibarrHttpClient`, `DolibarrDomainAdapters`, `DolibarrErrorMapper`, `DolibarrTelemetry`. Symfony orchestre DI, configuration et policies techniques transverses.
Les adapters principaux sont: `ThirdPartyAdapter`, `ProductAdapter`, `OrderAdapter`, `InvoiceAdapter`, `StockAdapter`. Chaque adapter expose des méthodes métier stables, indépendantes des détails HTTP.
Exemples illustratifs à adapter selon l’instance Dolibarr.
{
"ref_ext": "CLI-009120",
"name": "ACME Services",
"email": "contact@acme.fr",
"phone": "+33 3 20 10 20 30",
"address": "12 rue des Forges",
"zip": "59000",
"town": "Lille",
"country_id": 1,
"client": 1
}Le SDK applique normalisation, vérification de doublon et mapping statuts client/prospect.
{
"socid": 1248,
"date": "2026-02-19",
"ref_client": "WEB-2026-003492",
"lines": [
{
"fk_product": 991,
"qty": 3,
"subprice": 89.00,
"tva_tx": 20
}
]
}Après création, la commande est relue pour valider totaux recalculés, statuts et références internes.
Dans les flux réels, il faut aussi synchroniser les disponibilités stock par dépôt, les réservations partielles et les remises commerciales propres à chaque canal. Le SDK conserve donc une clé de lot et un état de reprise pour éviter qu’un `POST` rejoué ne recrée une commande déjà acceptée dans Dolibarr.
{
"socid": 1248,
"type": 0,
"date": "2026-02-19",
"ref_client": "FAC-WEB-2026-003492",
"lines": [
{
"fk_product": 991,
"qty": 3,
"subprice": 89.00,
"tva_tx": 20
}
]
}Les contrôles incluent TVA, arrondis HT/TTC et cohérence avec le document source.
Cas concret: une facture issue d’une commande web peut être créée correctement, puis échouer au moment de la mise à jour du stock ou du statut de livraison. Le SDK doit alors rejouer uniquement la branche en échec, en s’appuyant sur `ref_ext` et les identifiants métier pour éviter les doublons documentaires.
Lorsque l’API Dolibarr renvoie une erreur de schéma sur une ligne produit, il faut isoler la ligne fautive, corriger le couple `fk_product`/`qty`/`tva_tx`, puis relancer le lot. C’est particulièrement utile sur des imports multi-canaux où une seule ligne mal formée ne doit jamais bloquer tout le document.
Séquence type: 1. validation/enrichissement du payload, 2. upsert référentiels, 3. création commande, 4. création/validation facture selon workflow, 5. synchronisation stock/statut, 6. relecture avant ack final.
Chaque étape est rejouable isolément pour limiter les duplications en cas d’incident partiel.
Cette séparation par brique est ce qui rend Dolibarr exploitable en production. Un article peut être créé dans le catalogue, une commande réservée dans un dépôt donné, une facture publiée avec son échéance et, plus tard seulement, un avoir ou un paiement peut venir corriger le solde. Le SDK doit conserver des identifiants stables à chaque étape afin qu’un événement rejoué ne recrée pas un document déjà validé.
Sur les volumes réels, on voit rarement un seul flux. Le plus souvent, le site e-commerce pousse les commandes, le WMS pousse les confirmations d’expédition et le service comptable pousse les règlements. Sans découpage métier, ces écritures se télescopent. Le connecteur Dolibarr doit donc distinguer les objets `article`, `commande`, `facture`, `avoir`, `paiement` et `stock`, puis les traiter avec des stratégies de reprise différentes selon leur criticité.
Dolibarr integration matrix
- article -> ref_ext, price, vat, unit, stockable flag
- commande -> customer, lines, source channel, warehouse
- facture -> invoice number, due date, posted state
- avoir -> original invoice, reason, partial amount
- paiement -> amount, method, matched invoice
- stock -> depot, reserved qty, physical qtyLes appels critiques utilisent retries bornés, timeout par opération et clés d’idempotence sur écritures sensibles. Les erreurs sont normalisées pour orienter automatiquement la bonne stratégie de reprise.
Nous regardons aussi le délai entre création de document et validation comptable, le taux d’écart stock attendu versus stock publié, ainsi que le nombre de reprises manuelles. Ce sont ces KPI qui disent si Dolibarr reste un dépôt de données ou devient un vrai moteur d’exécution.
Nous distinguons clairement erreurs techniques transitoires, erreurs de contrat payload et erreurs métier bloquantes.
En production, un retry utile n’a de sens que s’il est borné et accompagné d’un journal de reprise par lot. Si une commande ou une facture reste bloquée, on doit pouvoir répondre: quelle ligne, quel statut, quel dépôt, quel `correlation_id` et quelle correction métier ont été appliqués.
Cas concret: une boutique en ligne peut pousser ses commandes vers Dolibarr toutes les cinq minutes, avec des réservations de stock par entrepôt et des lignes promotionnelles différentes selon le canal. Le SDK doit normaliser les payloads, identifier la source (`web`, `marketplace`, `retail`), puis écrire le document dans un batch isolé pour que la panne d’un canal n’empoisonne pas les autres. Si une ligne de commande est refusée, la bonne réponse est souvent de déplacer cette ligne en DLQ avec le motif exact plutôt que de bloquer la journée.
Le point de vigilance le plus fréquent reste la ligne produit. Un `fk_product` incorrect, un taux de TVA incohérent ou une quantité supérieure au stock disponible doit être vu comme une erreur de contrat ou de référentiel, pas comme un incident technique. Le SDK doit alors exposer le champ en cause, conserver le `ref_ext` du document et permettre un replay ligne par ligne plutôt qu’un redémarrage global.
Les équipes de support ont aussi besoin de savoir si la facture est déjà publiée, si la commande a été réservée dans le bon dépôt et si le paiement a bien été lettré. Le middleware doit donc publier des statuts lisibles par objet, sinon on se retrouve avec un succès HTTP mais un dossier commercial encore incomplet. Sur Dolibarr, cette nuance fait la différence entre un flux maîtrisé et une file d’attente qui grossit sans que personne ne sache où se situe le blocage.
Sur les corrections de stock, l’arbitrage métier est souvent plus important que la technique: faut-il relancer un mouvement de remise à disposition, créer un avoir, ou attendre la validation logistique? Le SDK doit exposer ces choix avec des statuts lisibles par l’ADV et le support, de manière à ce qu’un opérateur comprenne en un coup d’œil si la facture est en attente, si la livraison est partielle ou si la ligne doit être corrigée avant replay.
Un autre cas concret est celui des retours partiels. Une commande peut être livrée sur deux dépôts, puis un article peut revenir endommagé. Le bon enchaînement n’est pas de refaire la facture, mais de créer un avoir lié, de remettre à jour le stock sur le bon dépôt et de conserver le solde ouvert sur le paiement. C’est précisément cette chaîne documentée qui évite les corrections manuelles dans l’outil de gestion.
Exemple de décision run:
- HTTP 5xx sur création commande -> retry borné
- ligne produit inconnue -> DLQ avec `fk_product` en cause
- stock insuffisant -> quarantaine métier
- facture acceptée mais statut livraison manquant -> replay ciblé uniquement sur la branche statutaireCette logique devient encore plus importante quand plusieurs entrepôts ou plusieurs canaux d’acquisition alimentent le même Dolibarr. Le middleware doit pouvoir dire si un incident touche le référentiel produit, la commande ou seulement la synchronisation de stock, puis calculer un replay minimal pour ne pas rouvrir une facture déjà saine. C’est ce niveau de finesse qui transforme un simple connecteur en véritable composant d’orchestration.
En production, cela se voit très vite sur les retours marchandise et les expéditions partielles. Une commande peut être livrée en plusieurs vagues, puis corrigée par un avoir parce qu’un article manque ou qu’une rupture a été constatée après coup. Le SDK doit alors conserver la relation entre la commande, la facture, l’avoir et le mouvement de stock associé, afin que le replay ne modifie jamais les documents déjà validés.
Le bon design consiste à faire remonter un état lisible par objet: article synchronisé, commande prête, facture publiée, stock confirmé, paiement lettré, avoir émis. Chaque état doit être observable et chaque bascule doit être corrélée. Si le statut de livraison manque mais que la facture est saine, on rejoue seulement la branche logistique; si le produit n’existe pas, on garde la facture en attente et on envoie la ligne fautive en DLQ. Le run devient alors une séquence pilotée, pas une loterie de retries.
Dolibarr object chain
- article -> product catalog + vat + unit
- commande -> order + lines + reservation
- facture -> invoice + due date + posted state
- avoir -> credit note + original invoice
- paiement -> settlement + open balance
- stock -> warehouse delta + partial deliveryUn bon connecteur Dolibarr doit aussi rendre les lots lisibles. Nous gardons donc la page de batch, la source (`web`, `marketplace`, `retail`), la clé d’idempotence et le `correlation_id` pour savoir si l’incident touche un seul document ou un ensemble d’écritures. Quand un batch mélange plusieurs entités, cette métadonnée devient indispensable pour rejouer seulement la bonne page.
Les cas les plus fréquents en production concernent les différences de contrat: un article existe mais la TVA n’est pas la bonne, une commande passe mais le stock du dépôt ne suit pas, une facture est publiée mais l’avoir doit attendre une validation support. Le SDK doit classer ces situations comme des rejets métiers lisibles, pas comme des pannes techniques anonymes.
Côté SLA, on surveille aussi le délai entre commande validée et facture publiée, le taux de lignes envoyées en DLQ, le nombre de retries et le taux de replay par objet. Avec ces quatre métriques, on sait si Dolibarr sert encore de simple dépôt de données ou s’il joue réellement son rôle de moteur d’exécution pour l’ADV, la logistique et la comptabilité.
Dolibarr replay policy
- payload versioned by channel
- idempotency key on commande and facture
- DLQ for schema mismatch or unknown product
- retry only for transient HTTP 5xx
- stock correction isolated from invoice replay
- avoir linked to original facture, never duplicatedDans un projet Dolibarr dense, il faut aussi penser au niveau lot: une même commande peut contenir des articles en stock, des articles à préparer et des articles à livrer plus tard. Le SDK doit donc garder le détail par ligne et par dépôt pour savoir si l’on rejoue une facture, une réservation ou un simple ajustement de quantité. Cette granularité évite de corriger un document commercial alors que le vrai problème se situe dans le mouvement physique.
L’autre point clé est la cohérence de taxe. Si un produit arrive avec une `tva_tx` inattendue ou un `fk_product` absent, il ne faut pas répéter le batch en espérant que le problème disparaisse. On place la ligne en quarantaine, on corrige le référentiel article puis on rejoue seulement la ligne ou la page concernée. La même logique vaut pour un paiement mal lettré ou un avoir lié au mauvais document.
Les équipes support gagnent aussi beaucoup à disposer d’un état lisible par objet: article synchronisé, commande réservée, facture publiée, avoir créé, paiement rapproché, stock confirmé. Avec cette lecture, on sait immédiatement si le flux attend une correction métier ou une simple reprise technique. Le middleware cesse alors d’être un point noir et devient un outil de diagnostic.
Dolibarr operator map
- article -> catalog record + tax + stockable flag
- commande -> lines + warehouse + source channel
- facture -> posted state + due date + total TTC
- avoir -> source invoice + correction reason
- paiement -> matched invoice + residual balance
-- stock -> depot + quantity delta + lot if neededSur le plan purement API, nous gardons aussi un vocabulaire d’exploitation explicite: `webhook` pour les notifications temps réel, `queue` pour les reprises différées, `batch` pour les imports volumineux et `rate limit` pour éviter de saturer Dolibarr pendant les pics de commande. Le `token` d’accès et, le cas échéant, le flux d’`oauth` sont gérés dans la couche d’auth pour ne pas polluer les adapters métier.
Cette séparation améliore aussi le `mapping`. Un `payload` de commande ne doit pas ressembler à un payload de facture, et un replay ne doit jamais perdre sa clé d’`idempotence`. Si un `webhook` ou un import batch arrive en double, le SDK compare d’abord l’état de la facture, la quantité de stock et le `correlation_id` avant d’écrire. C’est cette logique qui évite les doublons et réduit la pression sur le support lors des reprises.
Dolibarr ops note
- webhook duplicate -> compare idempotency + correlation_id
- queue backlog -> split batch by channel and depot
- rate limit -> backoff instead of retry storm
- oauth/token refresh -> auth layer only
- mapping error -> DLQ line with product and tax detailsCet enchaînement d’objets est très proche de ce que les équipes voient au quotidien: un article est créé dans le catalogue, une commande part en préparation, la facture est publiée, un avoir corrige un retour et le paiement vient finalement solder le reste. Si un événement arrive en double ou dans le mauvais ordre, le middleware doit être capable de dire si l’action est réellement à rejouer ou s’il faut simplement ignorer la notification parce que le document est déjà à jour. Cette nuance est ce qui maintient Dolibarr exploitable quand la volumétrie monte.
Côté support, les champs les plus utiles sont le numéro de document, le motif de blocage, le stock concerné et l’état du lettrage. Avec ces quatre informations, on sait tout de suite si l’on est face à un problème de catalogue, de livraison, de comptabilité ou de paiement. Le middleware doit donc produire un journal de reprise qui permette de répondre à la question simple mais critique: quel objet est valide, quel objet est en attente et quel objet a besoin d’une correction métier avant replay.
Pour les lots planifiés, nous gardons aussi le détail de la page traitée, du dépôt concerné et de la source d’origine. Cela permet de distinguer un bug de mapping d’un simple décalage de timing entre le front-office et l’ERP. Sans ce niveau de granularité, un retry risque de remettre en mouvement des documents déjà sains alors qu’il suffirait souvent de corriger une seule ligne de stock ou une taxe.
Dolibarr support chain
- article created -> catalog ready
- commande -> reservation or partial delivery
- facture -> posted state + due date
- avoir -> correction for return / dispute
- paiement -> settlement and residual balanceLe SDK est couvert par tests unitaires (mappers/validators), tests d’intégration API (nominaux + dégradés), puis non-régression sur scénarios critiques (annulation, avoir partiel, reprise post-timeout).
Référence: Tests API, stratégie et bonnes pratiques.
Postman nous sert à qualifier rapidement les endpoints, partager des collections de tests et rejouer les cas de recette. Les mocks permettent de simuler les erreurs et états limites sans dépendre d’un environnement Dolibarr complet.
Guide utile: Postman pour industrialiser vos tests API.
Chaque flux est corrélé via trace id, journalisé (endpoint, durée, statut, retry_count), puis monitoré sur latence, taux d’échec, backlog et délai de reprise.
Voir aussi: Observabilité et runbooks API.
Vue d’ensemble du panel: Découvrir le guide des SDK API ERP Dawap.
SDK API ERP Microsoft Dynamics 365
Sur Dolibarr, la vraie difficulté n’est pas d’appeler l’API, mais de tenir une cohérence durable entre données commerciales, facturation et stock quand les volumes montent et que les règles métier évoluent.
Le cadrage initial doit couvrir quatre axes: 1. périmètre métier priorisé, 2. contrat API versionné, 3. stratégie de validation nominaux + dégradés, 4. modèle d’exploitation (monitoring, alerting, runbooks). C’est ce qui garantit une intégration robuste et maintenable.
Un cadrage efficace sur Dolibarr précise aussi quelle source fait foi pour le stock et la tarification. Si le site e-commerce et l’ERP n’appliquent pas la même règle de taxe, le flux doit être arrêté avant la publication de facture, sinon le support passera son temps à corriger des écarts de centimes ou de dépôt. Le SDK sert justement à faire remonter ces divergences au bon moment, avec le bon niveau de détail.
Besoin d’un accompagnement sur mesure pour cadrer, construire ou fiabiliser vos flux ? Découvrez notre offre d’intégration API sur mesure.
Articles complémentaires à lire ensuite : pour prolonger ce sujet, comparez aussi notre guide complet d’intégration API, notre article sur l’architecture sync, async et event et notre guide sur les tests API en production.
Nous accompagnons les équipes produit et techniques dans la conception, l’intégration et l’industrialisation d’APIs. Notre mission : construire des architectures robustes, sécurisées et évolutives, alignées sur vos enjeux métier et votre croissance.
Vous préférez échanger ? Planifier un rendez-vous
Les flux Odoo exigent une lecture fine de JSON-RPC, des modèles métier et des règles de transition documentaires. Ce guide détaille comment Dawap structure un SDK Symfony pour synchroniser clients, commandes, factures et stocks avec idempotence, retries maîtrisés et traçabilité run.
SAP implique des contraintes élevées sur la volumétrie, la cohérence des données et la robustesse des workflows critiques. Nous y détaillons notre SDK Symfony pour orchestrer les flux logistiques et financiers avec contrôle d’état strict, résilience réseau et supervision orientée production.
Dynamics 365 nécessite des échanges API REST sécurisés et cohérents sur plusieurs domaines métier simultanément. Ce guide explique notre SDK Symfony pour synchroniser ventes, clients, stocks et finance, tout en conservant une observabilité fine et une gestion d’incidents pilotable.
Les projets Divalto demandent de concilier contraintes terrain, flux commerciaux et exigences logistiques. L’article présente notre SDK Symfony avec mappings versionnés, stratégie de retry adaptée et normalisation des échanges pour stabiliser les opérations au quotidien.
Nous accompagnons les équipes produit et techniques dans la conception, l’intégration et l’industrialisation d’APIs. Notre mission : construire des architectures robustes, sécurisées et évolutives, alignées sur vos enjeux métier et votre croissance.
Vous préférez échanger ? Planifier un rendez-vous