Business Central API devient critique quand l’ERP doit absorber des commandes digitales, exposer des articles, synchroniser des clients, remonter des factures ou alimenter une BI sans perdre la logique comptable. Le piège consiste à traiter Business Central comme une base à écrire, alors que chaque company, item, customer, sales order ou invoice porte des validations métier.
La page intégrateur Microsoft Business Central API cadre les projets de middleware ERP, e-commerce, marketplace, portail B2B, reporting, webhooks, extensions et run.
La douleur arrive lorsqu’une commande web existe côté client mais pas dans l’ERP, qu’un item est retrouvé dans la mauvaise company ou qu’une facture part avec une dimension manquante. Le coût caché combine ressaisie ADV, correction comptable, stock incohérent et enquête entre plusieurs identifiants. Un code HTTP réussi ne prouve aucun de ces effets métier.
Le vrai enjeu est de construire une chaîne de preuve entre canal, middleware et Business Central. Notre accompagnement en intégration API définit sources de vérité, contrats, files, monitoring et rollback avant le go-live. Chaque traitement doit pouvoir être retrouvé par company, external ID et corrélation.
En réalité, exposer davantage de champs AL peut fragiliser le service si leur sens ou leur compatibilité n’est pas gouverné. Si une commande n’obtient pas son identifiant ERP dans le délai convenu ou si un document financier ne se rapproche pas, alors le pilote s’arrête. Le retry relit l’état courant ; il ne recrée jamais l’objet pour masquer l’incertitude.
Le bon découpage anti-cannibalisation
Les objets, endpoints et arbitrages préparent un besoin d’audit, de middleware, de reprise de connecteur ou de flux e-commerce, marketplace, BI et portail B2B. Le projet commence lorsque ces capacités doivent respecter des seuils et des responsabilités partagés.
Positionner le projet Business Central API
L’intention “Business Central API” cherche rarement une définition. Elle cherche comment brancher l’ERP Microsoft au reste du SI sans casser les règles de vente, stock, facturation ou reporting. L’owner doit donc rester la page Business Central, avec le blog en soutien pour expliquer les choix techniques.
Le contenu support doit parler aux CTO, DSI, responsables e-commerce, finance et ADV. Il doit montrer ce que l’on peut faire avec les APIs, mais surtout ce qu’il faut refuser : écriture directe sans validation, replay global, webhook non corrélé ou extension AL exposée sans contrat stable.
Sources officielles Microsoft Learn
Partir des capacités documentées et de l’environnement réel
Microsoft Learn confirme que Business Central API v2.0 sert à créer des Connect apps via REST pour échanger des données entre Business Central et une solution tierce. Les endpoints v2.0 reposent sur les companies et exposent des ressources comme customers, items, sales orders, sales invoices, purchase invoices ou subscriptions selon le périmètre.
Les docs Microsoft indiquent aussi que les APIs doivent être activées selon l’environnement, que le nom d’environnement entre dans l’URI, et que les webhooks passent par des subscriptions sur /api/v2.0/subscriptions. Les notifications demandent une logique de handshake, de ressource surveillée et de client state.
Point important pour les extensions : Microsoft précise que l’extension directe des APIs standard avec des champs additionnels n’est pas possible. Si le besoin exige des champs propres, il faut créer une API personnalisée, souvent via une API page en AL, versionnée, webhook-supported et OData v4 enabled.
Sources vérifiées : Business Central API v2.0, endpoints Business Central, webhooks subscriptions et API page type.
Companies, customers, items et sales orders
Donner une autorité et une clé stable à chaque objet
La première décision consiste à cadrer la company. Un même tenant peut porter plusieurs companies, environnements ou règles de droits. Une intégration qui ne journalise pas company, environnement, application, compte technique et version d’API rend les incidents très difficiles à expliquer.
Les customers et items doivent ensuite être traités comme des référentiels gouvernés. Un client e-commerce ne devient pas automatiquement un customer exploitable en ERP, et un item ne se limite pas à un SKU visible. Les adresses, dimensions, unités, catégories, variantes, prix, taxes et conditions commerciales doivent être validés avant écriture.
Les sales orders portent le risque opérationnel le plus visible. Une commande web ou marketplace doit être normalisée, enrichie, contrôlée puis créée dans Business Central avec une clé de corrélation. Le middleware doit conserver lignes, taxes, remises, transport, paiement, statut, erreurs et décision de replay.
Les invoices et credit memos méritent un seuil plus strict. Quand un document financier existe, la reprise ne doit plus rejouer tout le flux. Elle doit isoler la ligne, corriger la règle, documenter le motif et conserver la preuve que le document final raconte la même histoire que la commande.
API pages, OData et extensions AL
Exposer un modèle stable plutôt que la structure interne
Business Central ne se résume pas aux endpoints standard. Les OData web services, API pages et extensions AL peuvent exposer des données ou comportements spécifiques. C’est puissant, mais cela doit être traité comme un contrat d’intégration, pas comme une porte ouverte vers le modèle interne.
Une API page personnalisée doit préciser publisher, group, version, entity name, entity set name, source table, droits, webhooks attendus, champs exposés et règles de validation. Sans cette fiche, l’intégration devient dépendante d’un détail AL que le support ne saura pas relire.
La bonne pratique consiste à garder une couche middleware stable entre Business Central et les canaux. Le site e-commerce, la marketplace ou la BI n’ont pas besoin de connaître toutes les subtilités AL. Ils ont besoin d’un contrat fiable : créer commande, lire stock, publier statut, récupérer facture, signaler anomalie.
Webhooks, files et reprise ERP
Relire l’objet avant de propager la notification
Les webhooks Business Central servent à être notifié lorsqu’une entité change. Ils ne remplacent pas la réconciliation. Un événement peut arriver tard, être rejoué ou ne pas contenir toute la donnée utile au métier. Il doit donc entrer dans une file corrélée avant toute écriture aval.
Une subscription doit garder ressource surveillée, notification URL, clientState, company, environnement, statut, dernière notification et propriétaire. Si la notification concerne un customer, un item ou une invoice, le middleware doit relire l’objet avant de décider une action métier.
Le run doit séparer polling de secours, webhook, batch BI, écriture commande et reprise finance. Une seule file rend le code simple, mais elle peut bloquer un flux critique derrière un enrichissement analytique. Le bon design donne priorité aux commandes et documents financiers, puis aux mises à jour de référentiel, puis au reporting.
Si un événement ne peut pas être rapproché en moins de quinze minutes avec son objet Business Central et sa source externe, il doit passer en quarantaine. La reprise doit être bornée : rejouer une commande, une ligne, un item, une facture ou une notification, jamais tout le lot sans preuve.
Pour qui industrialiser Business Central API
Le projet convient aux entreprises qui connectent Business Central à un e-commerce, une marketplace, un portail B2B, un WMS ou une plateforme de reporting. Il devient prioritaire lorsque la même commande ou le même article traverse plusieurs canaux et que les équipes doivent garantir une cohérence de prix, de stock, de dimension analytique et de document financier.
Le premier lot utile associe une company, un canal et un parcours complet : client résolu, articles reconnus, sales order créée, expédition suivie et facture rapprochée. Cette limite permet de mesurer les rejets et de tester la reprise sans mélanger les règles de plusieurs entités juridiques. Elle donne aussi à la finance un échantillon qu’elle peut réellement vérifier.
Il faut différer si les companies ne sont pas cartographiées, si les external IDs sont réutilisés ou si personne ne décide des dimensions obligatoires. Une API ne corrige pas ces ambiguïtés. Le cadrage commence par les référentiels et les responsabilités ; une extraction BI ponctuelle peut suffire tant que l’entreprise n’a pas besoin de mutation, de temps proche du réel ou de garantie opérationnelle.
Cadrer authentification, companies et contrats
Limiter l’application à ses companies et capacités
Le compte applicatif reçoit uniquement les droits nécessaires aux ressources et companies du flux. La configuration sépare tenant, environnement, company ID, base URL et version d’API. Ces valeurs sont validées au démarrage et journalisées sans secret. Une requête dirigée vers une company inattendue est refusée avant toute mutation, même si le credential Microsoft pourrait techniquement l’autoriser.
La rotation du secret ou du certificat est testée avec chevauchement contrôlé, puis l’ancien accès est révoqué. Le monitoring distingue expiration, consentement absent, permission insuffisante et quota. Le support connaît le propriétaire de l’application Entra, le périmètre autorisé et la procédure de renouvellement ; il ne découvre pas ces éléments pendant une interruption de commandes.
Versionner le mapping et les API pages personnalisées
Le contrat de données associe chaque champ externe à une ressource, un type, une règle de nullité et une autorité. Pour une API page AL, publisher, group, version, entity set et champs exposés forment une interface publique. Toute nouvelle propriété est compatible par défaut ; tout changement de sens, de type ou d’obligation suit une migration explicite avec les consommateurs identifiés.
Une fixture de référence couvre client, item, unité, dimension et sales order. Elle est jouée contre la sandbox et l’environnement de recette après chaque évolution AL. La sortie est comparée au schéma attendu, y compris les enums et les erreurs. Si une extension modifie un comportement standard, le déploiement reste bloqué tant que le rollback et la compatibilité du middleware ne sont pas démontrés.
Créer une sales order sans doublon
Résoudre les référentiels avant l’écriture
L’entrée porte external order ID, company, customer, adresse, devise, lignes, taxes, remises et dimensions. Le middleware résout d’abord customer et items par des clés stables, puis valide unités, statut de blocage et règles commerciales. Un élément ambigu place le dossier en quarantaine avec le champ fautif ; le service ne crée pas une commande partielle que l’ADV devra compléter silencieusement.
La sortie de résolution contient les identifiants Business Central, la version du mapping et la liste des contrôles. Cette preuve est conservée avec l’entrée normalisée. Elle permet de distinguer un rejet dû au catalogue d’une validation ERP et de rejouer le même dossier après correction du référentiel sans changer son identité externe.
Appliquer idempotence, retry et compensation
La clé d’idempotence combine company, canal et external order ID. Avant le POST, le service relit sa table de corrélation ; après un timeout, il recherche l’objet par la référence prévue avant toute nouvelle création. L’entrée, la sortie, le statut, la dépendance et la tentative alimentent la journalisation. Deux appels concurrents sont sérialisés sur la même clé.
Si la sales order existe mais qu’une ligne échoue ensuite, le runbook décide correction, blocage ou compensation selon l’état ERP. Le rollback n’efface jamais un document comptable engagé. Une file conserve les effets encore attendus, avec seuil, owner et prochaine action. Le support peut reprendre une ligne ou une commande précise plutôt qu’un lot complet.
Rapprocher commandes, stocks et factures
Comparer les états métier, pas seulement les comptes
Le rapprochement quotidien associe external order ID, sales order ID, statut, lignes, quantités, expédition et facture. Une commande absente est distinguée d’une commande encore dans le délai normal. Les écarts portent un motif : référentiel, validation, dépendance, événement manquant ou traitement en retard. Chaque motif mène à un owner et à une reprise bornée.
Pour le stock, l’équipe compare date de valeur, emplacement, unité et quantité vendable plutôt qu’un nombre global. Un écart sur un item prioritaire peut suspendre la publication externe sans modifier le stock Business Central. Le système conserve la dernière valeur sûre et ouvre une enquête avec l’identifiant du mouvement attendu.
Prouver la continuité financière
La finance vérifie que montant HT, taxe, remise, transport, devise et total racontent la même histoire entre canal, sales order et invoice. Les avoirs et annulations restent liés au document initial. Une facture manquante ou un total divergent passe en quarantaine avant clôture ; l’intégration ne corrige pas automatiquement une écriture dont la cause n’est pas comprise.
Les indicateurs suivent commandes sans facture au-delà du délai, montants non rapprochés, credit memos orphelins et corrections manuelles. Le coût caché devient visible avant la clôture mensuelle. Si le volume d’écarts augmente alors que les appels restent verts, le pilote est réduit : la réussite technique ne compense pas une divergence comptable.
Erreurs fréquentes et reprise Business Central
Jouer les contradictions du SI
La campagne de recette crée un item bloqué, un customer ambigu, une dimension manquante, une commande déjà connue et une facture engagée avant annulation. Elle coupe Business Central après l’écriture pour provoquer un timeout incertain, livre deux fois la même notification et laisse expirer une subscription. Chaque scénario attend un état métier, une trace et une action, pas seulement un code HTTP.
Le retry relit systématiquement Business Central et la corrélation locale. Une erreur de validation ne repart pas automatiquement ; une indisponibilité transitoire applique un backoff ; un conflit fonctionnel rejoint la quarantaine. Le test réussit lorsqu’aucune commande ni facture n’est dupliquée et que le rollback respecte les documents déjà engagés.
Faire exécuter le runbook par le support
Une personne extérieure au développement reçoit une référence client et doit retrouver company, environnement, objet Business Central, dernière étape et erreur normalisée. Elle renouvelle une subscription, rejoue une projection ou transmet le dossier au bon owner sans accès direct en base. Le temps nécessaire devient une métrique de préparation au go-live.
Le monitoring distingue files de commandes, référentiels, webhooks et finance. Chaque alerte porte seuil, âge du plus ancien dossier et responsabilité. Un signal faible apparaît lorsque les retries augmentent sur une company ou qu’un même item revient plusieurs fois. Traiter cette dérive avant le blocage protège l’ADV et la clôture comptable.
Cas concret : la commande externe WEB-2468 cible la company française, mais une ligne utilise l’unité de vente de la company belge. Le contrat refuse la ligne avant création, conserve les deux identifiants et indique le mapping fautif. Après correction, le rejeu garde la même clé et produit une unique sales order avec ses dimensions attendues.
Autre exemple : Business Central crée la commande puis la connexion expire avant la réponse. Le worker relit la corrélation et l’external document number, retrouve l’objet et publie sa sortie au lieu de refaire le POST. La recette vérifie ensuite qu’un seul document atteint la facturation et que le support peut expliquer les deux tentatives.
Décision de sortie et plan d’action
- À faire d’abord : cartographier companies, environnements, comptes techniques, permissions, endpoints v2.0, OData et API pages.
- À valider ensuite : nommer la source de vérité pour customers, items, sales orders, invoices, inventory et dimensions.
- À mesurer : clients ambigus, items introuvables, commandes rejetées, factures engagées et webhooks non corrélés.
- À tester : tracer company ID, object ID, external ID, corrélation, payload réduit, statut normalisé et reprise.
- À différer : toute nouvelle company tant que le premier parcours ne respecte pas les seuils de sortie.
Pour élargir le contexte, API Microsoft Dynamics couvre l’écosystème ERP Microsoft, tandis que la réconciliation API aide à traiter les écarts entre source et cible.
Le feu vert exige que chaque commande du pilote possède un identifiant Business Central ou une quarantaine attribuée, qu’aucun retry ne crée de doublon et que les factures de l’échantillon soient rapprochées. Si l’un de ces seuils échoue, alors le périmètre reste sur une company et un canal. En revanche, il peut grandir lorsque le support reprend seul les cas testés.
Le dossier de sortie contient mapping versionné, matrice de droits, contrats d’API pages, résultats de recette, rapprochement financier et procédures de rollback. Il liste aussi les extensions différées. Cette frontière donne aux métiers une vision honnête de ce qui est garanti et évite qu’un nouveau canal contourne les contrôles du premier.
Conclusion : rendre le flux ERP explicable
Business Central API devient fiable lorsque company, référentiels, commande et document financier restent reliés par des identifiants et des contrats versionnés. Le middleware ne remplace pas l’ERP : il orchestre les dépendances, conserve les preuves et empêche qu’un timeout ou un webhook dupliqué produise un second effet.
La priorité est de prouver un parcours complet sur un périmètre borné. Authentification limitée, résolution des items, idempotence, rapprochement et reprise par le support doivent fonctionner avant l’ajout de nouvelles companies ou API pages. Cette discipline protège ventes, stock et comptabilité pendant l’évolution du SI.
Pour cadrer ce parcours avec les équipes e-commerce, ERP, ADV et finance, notre accompagnement en intégration API transforme Business Central en composant observable et réversible, sans exposer sa complexité à chaque canal.
