L’API Business Central est devenue, sans bruit, l’une des API REST les plus propres de la stack enterprise Microsoft. En 2026, c’est elle qui sous-tend la plupart des intégrations BC modernes. Pourtant, la documentation est soit trop superficielle (le quick start Microsoft) soit trop profonde (le source AL). Cet article est le terrain médian pratique que nous aurions aimé trouver quand nous nous y mettions.
Nous couvrirons l’authentification, la structure des endpoints, les patterns de requête, les APIs custom, les webhooks, le rate limiting et les patterns d’intégration que nous utilisons chaque semaine en production.
Les deux variantes de l’API Business Central
BC expose deux surfaces d’API. Savoir laquelle utiliser compte.
L’API standard (v2.0) est l’API REST OData officiellement supportée par Microsoft. Elle couvre la plupart des entités BC (clients, fournisseurs, articles, factures, écritures de journal) et est stable entre versions BC. Utilisez-la pour les intégrations de production.
Le pattern API custom permet aux développeurs d’exposer leurs propres pages AL comme endpoints REST. Utilisez-le quand vous devez exposer une logique métier que l’API standard ne couvre pas. Attention : votre API custom est votre responsabilité à versionner et documenter.
Authentification : OAuth 2.0, pas de raccourci
L’authentification de l’API BC est OAuth 2.0 avec Microsoft Entra (anciennement Azure AD). Deux flows comptent.
Client credentials flow : intégration serveur-à-serveur sans contexte utilisateur. Enregistrez une app Entra, donnez le consentement admin pour BC, utilisez client_id et client_secret pour obtenir un token. C’est le bon pattern pour les intégrations backend.
Authorization code flow : intégration avec contexte utilisateur où les actions sont réalisées pour le compte d’un utilisateur spécifique. Utilisez-le pour les apps utilisateur qui ont besoin d’un accès délégué.
Gardez les tokens côté serveur. N’embarquez jamais de client secret dans du code côté client. Tournez les secrets régulièrement. Utilisez l’authentification par certificat pour les scénarios haute sécurité.
Structure des endpoints et découverte
Le pattern d’URL de base est : https://api.businesscentral.dynamics.com/v2.0/{tenant-id}/{environment}/api/v2.0/companies({company-id})/{entity}
Découvrez les entités disponibles en appelant l’endpoint racine sans entité spécifique. La réponse est une metadata OData décrivant toutes les collections disponibles.
La plupart des requêtes suivent la syntaxe OData standard : $filter, $select, $top, $skip, $expand, $orderby. Combinez-les pour récupérer exactement ce dont vous avez besoin sans aller-retour.
Pagination et limites de débit
L’API BC retourne des résultats paginés. La taille de page par défaut est 20 000 enregistrements, mais en pratique vous devez respecter le @odata.nextLink dans la réponse et ne pas coder en dur les tailles de page.
Les rate limits s’appliquent par tenant : 600 requêtes par minute par environnement en 2026. Les intégrations lourdes doivent implémenter un backoff exponentiel sur les réponses 429. La protection burst est réelle et se déclenche en secondes.
Quand vous tirez de grandes quantités de données (plus de 100 000 enregistrements), utilisez les changefeeds ou les extracts planifiés plutôt que des appels synchrones.
Écrire des données : POST, PATCH et idempotence
Écrire des données via l’API BC a des subtilités.
POST crée une nouvelle entité. La réponse inclut le nouvel ID et l’ETag. Stockez les deux pour les mises à jour futures.
PATCH met à jour une entité existante. L’entête If-Match avec l’ETag le plus récent empêche les pertes de mise à jour. Si vous sautez les ETags, vous écrasez silencieusement les modifications concurrentes.
Idempotence : BC ne dédoublonne pas nativement les requêtes POST. Si vous re-tentez une création après timeout, vous pouvez vous retrouver avec des doublons. Utilisez une clé métier unique (par exemple votre numéro de commande externe) et un GET rapide avant POST pour vérifier.
Opérations batch : BC supporte l’endpoint OData $batch pour plusieurs opérations en une requête. Utilisez-le pour les créations et mises à jour en lot. Limites (typiquement 100 opérations par batch).
APIs custom : quand et comment
L’API standard couvre la plupart des besoins mais pas tous. Manques fréquents : actions de posting (par exemple valider un journal, libérer une commande), logique métier qui couvre plusieurs entités, valeurs calculées non exposées par les pages standard.
Pour construire une API custom, créez une page AL de type API, fixez les propriétés APIPublisher, APIGroup, APIVersion et EntityName, et exposez les champs dont vous avez besoin. Microsoft a une documentation claire sur le jeu de propriétés.
Versionnez vos APIs custom dès le jour un. Utilisez le versioning sémantique dans la propriété APIVersion. Maintenez les breaking changes seulement dans des versions majeures. Documentez vos APIs custom avec OpenAPI ou similaire pour que les intégrateurs sachent à quoi s’attendre.
Webhooks pour notification de changement
Faire du polling sur l’API pour les changements est le mauvais pattern à l’échelle. BC supporte les webhooks via le modèle d’abonnements Microsoft Graph.
Enregistrez un abonnement en spécifiant l’entité, les types de changement et l’URL de notification. BC poste des notifications sur votre URL quand des changements correspondants surviennent. Les abonnements expirent (typiquement 3 jours) et doivent être renouvelés programmatiquement.
Les webhooks sont en livraison at-least-once. Construisez votre handler idempotent. La notification inclut l’ID de l’entité modifiée mais pas le payload complet, donc vous faites encore un GET pour récupérer le dernier état.
Patterns d’intégration que nous utilisons chaque semaine
Cinq patterns d’intégration que nous appliquons dans les environnements BC en production.
Pattern un : middleware léger. Utilisez Power Automate ou Azure Logic Apps pour les workflows à faible volume (moins de 10 000 événements par jour). Plus rapide à construire, plus facile à maintenir.
Pattern deux : middleware lourd. Utilisez un service d’intégration dédié (Azure Function, .NET custom, MuleSoft) pour les flux haut volume, mission-critique. Plus de résilience, observabilité, contrôle des retries.
Pattern trois : event-driven. Webhooks plus une queue (Service Bus, Storage Queue). Le bon pattern pour l’intégration asynchrone avec les systèmes downstream.
Pattern quatre : ETL planifié. Pour les gros mouvements de données (BI, data lake), utilisez Azure Data Factory avec le connecteur BC. Réduit la charge API et donne du chargement incrémental.
Pattern cinq : passerelle API customer-facing. Exposez un sous-ensemble curé des données BC via votre propre passerelle API avec rate limiting, authentification et observabilité. N’exposez jamais l’API BC directement à des applications client.
Erreurs courantes que nous voyons
Erreur un : tenant IDs codés en dur. Le tenant ID est spécifique à l’environnement. Le coder en dur casse à chaque promotion d’environnement.
Erreur deux : opérations bulk synchrones. Tirer 200 000 enregistrements en un GET, timeout, retry, timeout. Utilisez les changefeeds.
Erreur trois : ignorer les rate limits. Construire des intégrations qui marchent en dev avec 10 enregistrements et explosent en prod avec 100 000.
Erreur quatre : pas d’idempotence. Re-tenter POST sur timeout, créer des factures en double.
Erreur cinq : pas de monitoring. Construire une intégration et ne jamais l’instrumenter. Le premier échec dont vous entendrez parler vient de la finance trois mois plus tard.
L’approche Asio Services : intégrations API-first
Nous construisons chaque intégration BC avec l’hypothèse qu’un autre système aura besoin des mêmes données demain. Ça veut dire : authentification claire, APIs custom versionnées, observabilité dès le jour un, et documentation qui survit au développeur qui l’a écrite.
Si vous concevez une architecture d’intégration BC, ou auditez une architecture existante, nous pouvons vous aider à choisir les bons patterns et éviter les erreurs courantes.
→ Réservez un appel découverte gratuit avec Asio Services. Nous revisiterons votre architecture d’intégration et recommanderons où simplifier.
