Guide d'intégration Microsoft Dynamics 365 Business Central
1. Introduction
Hyperfox est une plateforme d'automatisation du traitement des commandes B2B qui utilise l'IA pour transformer des commandes reçues par e-mail sous forme non structurée en données structurées, prêtes pour l'ERP. Ce guide décrit comment Hyperfox s'intègre à Microsoft Dynamics 365 Business Central (BC) pour livrer des commandes vente validées.
Indépendamment de la création des commandes, Hyperfox maintient sa propre intégration native avec Business Central pour la récupération de données (lecture des clients, des articles et des autres données de base). Cette intégration par défaut utilise l'authentification de base HTTP et fonctionne indépendamment de la méthode de création de commandes retenue.
1.1 Terminologie
| Terme | Définition |
|---|---|
| BC | Microsoft Dynamics 365 Business Central (Online ou On-Premises) |
| Connector | Le Hyperfox Connector — un service middleware développé et hébergé par Hyperfox, qui crée des commandes vente dans Business Central via l'API BC |
| API v2.0 | L'API REST standard exposée par Business Central pour des entités telles que les clients, les articles et les commandes vente |
| Entra ID | Microsoft Entra ID (anciennement Azure Active Directory), la plateforme d'identité utilisée pour l'authentification |
| Extension AL | Un package de code personnalisé écrit dans le langage AL de Microsoft, installé dans un environnement Business Central pour en étendre les fonctionnalités |
| Point de terminaison personnalisé | Une page API BC créée via une extension AL (par ex. HFOX_SalesOrders au lieu de la page standard salesOrders) |
2. Méthodes d'intégration
Il existe deux méthodes pour créer des commandes vente dans Business Central depuis Hyperfox. Les deux méthodes reçoivent la même charge utile de webhook (voir la section 7 pour la spécification complète).
| Point de terminaison BC personnalisé (recommandé) | Hyperfox Connector | |
|---|---|---|
| Création de commande | BC traite le webhook en interne | Le Connector crée la commande via des appels à l'API BC |
| Résolution des clients/articles | Gérée dans BC (recherches natives) | Le Connector interroge l'API BC pour résoudre les identifiants |
| Logique métier et validation | Accès complet aux règles de validation de BC | Limitée à ce que l'API BC expose |
| Champs personnalisés | Oui — l'extension contrôle le mappage | Uniquement avec des pages API BC personnalisées |
| Partenaire BC requis | Oui (pour développer l'extension AL) | Non |
| Dépendance au middleware | Aucune | Oui — le Connector doit être disponible |
:::tip Recommandation Le point de terminaison BC personnalisé est l'approche à privilégier, car elle conserve toute la logique de traitement des commandes dans Business Central, s'appuie sur la validation native et élimine le middleware comme point de défaillance pour la création des commandes. :::
2.1 Choisir la bonne méthode
Choisissez le point de terminaison BC personnalisé si :
- Votre partenaire d'implémentation BC est disponible pour développer et maintenir une extension AL
- Vous avez besoin de champs personnalisés, de dimensions ou de codes magasin sur les commandes vente
- Vous souhaitez que la logique de traitement des commandes réside entièrement dans Business Central
- Vous préférez limiter au maximum les dépendances à un middleware externe
Choisissez le Connector si :
- Vous devez passer en production rapidement, sans intervention d'un partenaire BC
- Le jeu de champs standard de l'API BC est suffisant pour vos besoins
- Votre partenaire BC n'est pas disponible ou l'extension AL n'est pas encore prête
2.2 Aperçu de l'architecture
Méthode A — Point de terminaison BC personnalisé (recommandé) :
Webhook (JSON)
┌──────────┐ ──────────────────────────► ┌──────────────────┐
│ Hyperfox │ │ Business Central │
│ Platform │ ◄────────────────────────── │ (your tenant) │
│ │ HTTP response │ │
│ │ │ Custom API page │
│ │ Data retrieval ◄─► │ via AL extension │
│ │ (Basic Auth, BC REST API) │ │
└──────────┘ └──────────────────┘
Méthode B — Hyperfox Connector :
Webhook (JSON)
┌──────────┐ ──────────────────► ┌─────────────┐ BC REST API ┌──────────────────┐
│ Hyperfox │ │ Connector │ ─────────────►│ Business Central │
│ Platform │ │ Application │ ◄─────────────│ (your tenant) │
│ │ └─────────────┘ Sales order └──────────────────┘
│ │ creation ▲
│ │ │
│ │ Data retrieval (Basic Auth, BC REST API) │
│ │ ────────────────────────────────────────────────────────────►
└──────────┘
3. Prérequis
Les éléments suivants doivent être en place avant que l'intégration puisse être activée.
3.1 Accès à l'API Business Central
(Les deux) Hyperfox nécessite un accès API à votre environnement Business Central pour la récupération de données (lecture des clients, des articles et des autres données de base). Avec la méthode Connector, les mêmes informations d'identification servent également à la création des commandes. Les informations suivantes, spécifiques à l'environnement, sont nécessaires lors de la configuration :
| Configuration | Description | Exemple |
|---|---|---|
| URL de l'API BC | URL de base de l'API BC standard | https://api.businesscentral.dynamics.com/v2.0/{tenantId}/{env}/api/v2.0/companies({companyId}) |
| Informations d'identification API | Nom d'utilisateur et mot de passe pour l'authentification de base | Fournis par votre administrateur BC |
| URL de l'API Commandes vente (Connector uniquement) | Point de terminaison pour la création des commandes vente (peut différer en cas d'extension personnalisée) | Identique à l'URL de l'API, ou URL d'une extension personnalisée |
3.2 Autorisations BC requises
Le compte utilisateur API requiert au minimum les ensembles d'autorisations suivants :
| Ensemble d'autorisations | Niveau d'accès | Objectif | Applicabilité |
|---|---|---|---|
D365 READ | Lecture | Rechercher les clients, les articles et les autres données de base | (Les deux) |
D365 SALES DOC, EDIT | Lecture / Écriture | Créer des commandes vente et des lignes commande vente | (Connector uniquement) |
Si une extension personnalisée pour les pièces jointes est utilisée, des autorisations supplémentaires peuvent être nécessaires pour ce point de terminaison.
3.3 Configuration réseau
(Les deux) Hyperfox et le Connector communiquent avec Business Central depuis les adresses IP statiques suivantes. Si votre organisation utilise des règles de pare-feu ou des stratégies d'accès conditionnel, veuillez autoriser ces adresses :
| Service | Adresse IP | FQDN |
|---|---|---|
| Connector / communication API | 185.86.19.68 | n/a |
| Application (Production) — webhooks | 3.73.107.207 | production.egress.hyperfox.net |
| Application (Staging) — webhooks | 3.123.145.36 | staging.egress.hyperfox.net |
:::note Remarque sur l'autorisation des adresses IP Business Central Online ne prend pas en charge nativement les restrictions basées sur l'adresse IP au niveau de l'application. Pour BC Online, les restrictions d'adresses IP sont appliquées via des stratégies d'accès conditionnel Entra ID (nécessite une licence Azure AD Premium P1/P2). Pour BC On-Premises, les règles de pare-feu standard s'appliquent. Les adresses IP ci-dessus sont fournies pour votre infrastructure réseau et à des fins d'audit, quel que soit le type de déploiement. :::
Toutes les communications utilisent TLS 1.2 ou une version supérieure. Aucune donnée n'est transmise en clair.
3.4 Liste de contrôle de mise en service
Les éléments suivants doivent être fournis par le client à l'équipe Hyperfox avant que l'intégration puisse être configurée :
- Informations d'identification Basic Auth — Nom d'utilisateur et mot de passe du compte utilisateur API BC dédié
- URL de base de Business Central — L'URL de base complète de l'API, incluant l'identifiant de locataire, l'environnement et l'identifiant de société
- Noms des points de terminaison API — Si des pages API personnalisées sont utilisées, indiquez les noms des points de terminaison pour :
- Customers
- Items
- Customer_Item (facultatif)
- Units_of_measure (facultatif)
- Item_Unit_Of_Measure (facultatif)
- Point de terminaison webhook — (Méthode point de terminaison BC personnalisé uniquement) L'URL de la page API personnalisée dans BC qui recevra le webhook Hyperfox
4. Point de terminaison BC personnalisé (recommandé)
Cette section décrit la méthode d'intégration recommandée, dans laquelle Business Central reçoit directement le webhook Hyperfox et le traite en interne.
4.1 Fonctionnement
- Une commande est validée dans Hyperfox (automatiquement ou après vérification manuelle).
- Hyperfox envoie la commande validée sous forme de webhook JSON directement à une page API personnalisée dans Business Central.
- L'extension AL dans BC traite la charge utile et crée la commande vente — le tout avec la logique native de BC.
- BC renvoie une réponse de succès ou d'erreur. Hyperfox met à jour le statut de la commande en conséquence.
Comme tout le traitement des commandes se déroule dans Business Central, cette méthode bénéficie d'un accès complet aux règles de validation de BC, aux champs personnalisés, aux dimensions, aux codes magasin et à toute autre logique métier configurée dans l'environnement. Le Connector n'intervient pas dans ce flux.
4.2 Ce que le partenaire BC doit développer
Le partenaire d'implémentation BC du client crée une extension AL qui comprend :
- Une page API personnalisée qui accepte la charge utile du webhook Hyperfox (voir la section 7 pour la structure JSON complète).
- Une logique de traitement des commandes qui mappe les champs Hyperfox entrants aux champs de la commande vente BC (résolution du client par numéro de compte, résolution de l'article par SKU, création des lignes avec les quantités).
- Une gestion des erreurs qui renvoie des codes de statut HTTP et des messages d'erreur explicites, afin qu'Hyperfox puisse détecter et signaler les échecs.
Hyperfox fournit :
- La spécification de la charge utile du webhook (section 7)
- Un environnement de staging pour les tests de bout en bout
- Un accompagnement pendant le développement de l'intégration et la mise en production
5. Intégration via le Connector
Le Connector est un service middleware léger développé et hébergé par Hyperfox. Lorsqu'une commande validée est prête, Hyperfox envoie le webhook au Connector, qui crée ensuite une commande vente standard dans Business Central via l'API REST BC (v2.0).
Le Connector utilise les pages API standard salesOrders et salesOrderLines. Aucune extension AL ni aucun développement personnalisé n'est requis côté BC — le Connector fonctionne avec une configuration Business Central par défaut.
Si votre environnement BC utilise des pages API personnalisées, le Connector peut être configuré pour les utiliser à la place. Veuillez en discuter avec Hyperfox lors de la mise en service.
6. Sécurité
6.1 Authentification
(Récupération de données) L'intégration BC native de Hyperfox s'authentifie via l'authentification de base HTTP avec un compte utilisateur API BC dédié.
(Méthode Connector) Le Connector s'authentifie auprès de Business Central avec les mêmes informations d'identification d'authentification de base HTTP. Celles-ci sont stockées sous forme de variables d'environnement sur le serveur du Connector et ne sont jamais transmises en clair.
(Méthode point de terminaison BC personnalisé) L'authentification entre Hyperfox et le point de terminaison BC personnalisé est gérée par les mécanismes d'authentification propres à la plateforme BC (généralement Entra ID / OAuth 2.0).
| Contrôle de sécurité | Mise en œuvre |
|---|---|
| Chiffrement du transport | TLS 1.2+ (obligatoire) |
| Stockage des informations d'identification | Variables d'environnement (chiffrées au repos sur le serveur) |
| Authentification API (récupération de données et Connector) | Authentification de base HTTP avec un compte de service dédié |
| Authentification API (point de terminaison personnalisé) | Authentification de la plateforme BC (Entra ID / OAuth 2.0) |
6.2 Sécurité réseau
Toutes les connexions sortantes de Hyperfox et du Connector proviennent des adresses IP statiques répertoriées à la section 3.3. Pour Business Central Online, les restrictions d'accès peuvent être appliquées via :
- Stratégies d'accès conditionnel Entra ID : Limiter l'émission de jetons API aux adresses IP statiques autorisées (nécessite Azure AD Premium P1/P2).
- Autorisation de locataires : Les administrateurs BC peuvent restreindre l'accès à l'environnement à un maximum de 10 identifiants de locataires Entra externes.
Pour Business Central On-Premises, les contrôles de sécurité réseau standard (pare-feu, VPN, autorisation d'adresses IP) s'appliquent au niveau de l'infrastructure.
6.3 Traitement des données
(Méthode Connector) Le Connector traite les données de commande uniquement en transit. La charge utile brute du webhook est stockée temporairement sur le serveur du Connector pendant le traitement et n'est pas conservée une fois la commande créée avec succès dans Business Central.
(Méthode point de terminaison BC personnalisé) Aucune donnée de commande ne transite par le Connector ni par un quelconque middleware — elle circule directement de Hyperfox vers Business Central.
7. Annexe : structure de la charge utile du webhook Hyperfox
Vous trouverez ci-dessous la structure JSON qu'Hyperfox envoie lors de la livraison d'une commande validée. Cette charge utile est identique, qu'elle soit envoyée au Connector ou à un point de terminaison BC personnalisé.
7.1 En-tête de commande
| Champ | Type | Description |
|---|---|---|
id | UUID | Identifiant unique de la commande Hyperfox |
created_at | Date | Date de création de la commande dans Hyperfox |
updated_at | Date | Date de la dernière mise à jour |
sales_order_id | String | null | Identifiant de la commande vente BC (renseigné après une création réussie) |
processing_status | String | Toujours "validated" lors de l'envoi |
issue_date | Date | Date d'émission de la commande → correspond à orderDate |
delivery_date | Date | null | Date de livraison souhaitée (niveau en-tête) → correspond à requestedDeliveryDate |
notes | String | null | Remarques en texte libre issues de la commande |
customer_reference | String | Référence de commande du client → correspond à externalDocumentNumber |
accuracy | Integer | Score de confiance de l'IA (0–100) |
error_reason | String | null | Description de l'erreur (null lorsque la commande est validée) |
buyer_customer_party_id | String | Identifiant du compte client acheteur → utilisé pour la recherche du client dans BC |
accounting_customer_party_id | String | Identifiant du compte client de facturation (peut différer de l'acheteur) |
order_inquiry_id | UUID | Référence à l'e-mail d'origine |
7.2 Objet tiers client
Les objets buyer_customer_party et accounting_customer_party contiennent les coordonnées complètes du client :
| Champ | Type | Description |
|---|---|---|
id | UUID | Identifiant client interne Hyperfox |
created_at | Date | Date de création de la fiche client |
updated_at | Date | Date de dernière mise à jour de la fiche client |
account_id | String | Numéro de client (par ex. "C2480") → utilisé pour la recherche dans BC |
name | String | Nom de l'entreprise |
language | String | null | Code de langue du client |
website_uri | String | null | Site web du client |
street_name | String | Adresse (rue) |
additional_street_name | String | Complément d'adresse |
city_name | String | Ville |
postal_zone | String | Code postal |
country | String | Code pays ISO (par ex. "BE") |
contact_name | String | null | Nom de la personne de contact |
contact_telephone | String | Numéro de téléphone du contact |
contact_email | String | Adresse e-mail du contact |
7.3 Tableau des lignes de commande
| Champ | Type | Description |
|---|---|---|
id | UUID | Identifiant unique de la ligne |
created_at | Date | Date de création de la ligne |
updated_at | Date | Date de dernière mise à jour de la ligne |
order_id | UUID | Référence à l'id de la commande parente |
quantity | Integer | Quantité commandée → correspond à quantity |
item_id | String | SKU de l'article → utilisé pour la recherche de l'article dans BC |
delivery_date | Date | Date de livraison souhaitée pour la ligne |
customer_reference | String | Référence client au niveau de la ligne |
7.4 Objet article (imbriqué dans chaque ligne)
| Champ | Type | Description |
|---|---|---|
id | UUID | Identifiant d'article interne Hyperfox |
created_at | Date | Date de création de la fiche article |
updated_at | Date | Date de dernière mise à jour de la fiche article |
name | String | Désignation de l'article |
description | String | Description détaillée de l'article |
brand_name | String | null | Nom de la marque |
sku | String | Code SKU de l'article (par ex. "FX-PLUSH-STD") → utilisé pour la recherche de l'article dans BC |
ean | String | EAN / code-barres |
base_unit_code_id | String | Unité de mesure (par ex. "PCE", "BOX") |
7.5 Exemple de charge utile
Cet exemple utilise des données anonymisées. Les valeurs réelles des champs varient selon le client.
{
"validated_order": {
"id": "b3e7a1d2-4f89-4c2e-a615-9d82f3b70c41",
"created_at": "2026-03-10",
"updated_at": "2026-03-10",
"sales_order_id": null,
"processing_status": "validated",
"issue_date": "2026-03-10",
"delivery_date": null,
"notes": null,
"customer_reference": "PO-2026-04821",
"accuracy": 92,
"error_reason": null,
"buyer_customer_party_id": "C2480",
"accounting_customer_party_id": "C2480",
"order_inquiry_id": "019d4a82-bc13-7291-a445-e83d91b2f507",
"buyer_customer_party": {
"id": "019c3f17-8a4d-7012-b891-3c6e42a85901",
"created_at": "2026-01-15",
"updated_at": "2026-03-10",
"account_id": "C2480",
"name": "Foxden Trading NV",
"language": null,
"website_uri": null,
"street_name": "Vossenstraat 12",
"additional_street_name": "",
"city_name": "Antwerp",
"postal_zone": "2030",
"country": "BE",
"contact_name": null,
"contact_telephone": "",
},
"accounting_customer_party": {
"id": "019c3f17-8a4d-7012-b891-3c6e42a85901",
"created_at": "2026-01-15",
"updated_at": "2026-03-10",
"account_id": "C2480",
"name": "Foxden Trading NV",
"language": null,
"website_uri": null,
"street_name": "Vossenstraat 12",
"additional_street_name": "",
"city_name": "Antwerp",
"postal_zone": "2030",
"country": "BE",
"contact_name": null,
"contact_telephone": "",
},
"lines": [
{
"id": "b3e7a1d2-5a12-4891-b203-7e41c8d930a1",
"created_at": "2026-03-10",
"updated_at": "2026-03-10",
"order_id": "b3e7a1d2-4f89-4c2e-a615-9d82f3b70c41",
"quantity": 120,
"item_id": "FX-PLUSH-STD",
"delivery_date": "2026-04-02",
"customer_reference": "4500892347",
"item": {
"id": "019c3f17-6b22-7a1e-94d3-8f2a41e07b55",
"created_at": "2026-01-15",
"updated_at": "2026-03-10",
"name": "Hyperfox plush toy — standard",
"description": "",
"brand_name": "Hyperfox",
"sku": "FX-PLUSH-STD",
"ean": "5412345678901",
"base_unit_code_id": "PCE"
}
},
{
"id": "b3e7a1d2-5d34-4f7a-a891-2b53d7e104c8",
"created_at": "2026-03-10",
"updated_at": "2026-03-10",
"order_id": "b3e7a1d2-4f89-4c2e-a615-9d82f3b70c41",
"quantity": 80,
"item_id": "FX-PLUSH-STD",
"delivery_date": "2026-04-09",
"customer_reference": "4500892347",
"item": {
"id": "019c3f17-6b22-7a1e-94d3-8f2a41e07b55",
"created_at": "2026-01-15",
"updated_at": "2026-03-10",
"name": "Hyperfox plush toy — standard",
"description": "",
"brand_name": "Hyperfox",
"sku": "FX-PLUSH-STD",
"ean": "5412345678901",
"base_unit_code_id": "PCE"
}
},
{
"id": "b3e7a1d2-6147-4e5b-bc42-9a17f3c285d9",
"created_at": "2026-03-10",
"updated_at": "2026-03-10",
"order_id": "b3e7a1d2-4f89-4c2e-a615-9d82f3b70c41",
"quantity": 25,
"item_id": "FX-MUG-CER",
"delivery_date": "2026-04-15",
"customer_reference": "4500892347",
"item": {
"id": "019c3f17-7c91-7d4f-b562-4e9130d82a77",
"created_at": "2026-01-15",
"updated_at": "2026-03-10",
"name": "Hyperfox ceramic mug 350ml",
"description": "Fox-print enamel-coated ceramic mug",
"brand_name": "Hyperfox",
"sku": "FX-MUG-CER",
"ean": "5412345679205",
"base_unit_code_id": "PCE"
}
}
]
}
}