Microsoft Dynamics 365 Business Central Integration Guide

1. Introduction

Hyperfox is a B2B order processing automation platform that uses AI to transform unstructured email orders into structured, ERP-ready data. This guide describes how Hyperfox integrates with Microsoft Dynamics 365 Business Central (BC) to deliver validated sales orders.

Separately from order creation, Hyperfox maintains its own built-in integration with Business Central for data retrieval (reading customers, items, and other master data). This default integration uses HTTP Basic Authentication and operates independently of which order creation method is used.

1.1 Terminology

Term	Definition
BC	Microsoft Dynamics 365 Business Central (Online or On-Premises)
Connector	The Hyperfox Connector — a middleware service developed and hosted by Hyperfox that creates sales orders in Business Central via the BC API
v2.0 API	The standard REST API exposed by Business Central for entities like customers, items, and sales orders
Entra ID	Microsoft Entra ID (formerly Azure Active Directory), the identity platform used for authentication
AL Extension	A custom code package written in Microsoft's AL language that is installed inside a Business Central environment to extend its functionality
Custom endpoint	A BC API page created via an AL extension (e.g. `HFOX_SalesOrders` instead of the standard `salesOrders`)

2. Integration methods

There are two methods for creating sales orders in Business Central from Hyperfox. Both methods receive the same webhook payload (see Section 7 for the full specification).

	Custom BC endpoint (recommended)	Hyperfox Connector
Order creation	BC processes the webhook internally	Connector creates the order via BC API calls
Customer/item resolution	Handled inside BC (native lookups)	Connector queries BC API to resolve IDs
Business logic & validation	Full access to BC validation rules	Limited to what the BC API exposes
Custom fields	Yes — the extension controls the mapping	Only if using custom BC API pages
BC partner required	Yes (to build the AL extension)	No
Middleware dependency	None	Yes — Connector must be available

:::tip Recommendation The custom BC endpoint is the preferred approach because it keeps all order processing logic inside Business Central, leverages native validation, and eliminates middleware as a point of failure for order creation. :::

2.1 Choosing the right method

Choose the custom BC endpoint if:

Your BC implementation partner is available to build and maintain an AL extension
You need custom fields, dimensions, or location codes on sales orders
You want order processing logic to live entirely inside Business Central
You prefer to minimize external middleware dependencies

Choose the Connector if:

You need to go live quickly without BC partner involvement
The standard BC API field set is sufficient for your needs
Your BC partner is not available or the AL extension is not yet ready

2.2 Architecture overview

Method A — Custom BC endpoint (recommended):

                Webhook (JSON)
┌──────────┐ ──────────────────────────► ┌──────────────────┐
│ Hyperfox │                             │ Business Central │
│ Platform │ ◄────────────────────────── │   (your tenant)  │
│          │      HTTP response          │                  │
│          │                             │ Custom API page  │
│          │      Data retrieval     ◄─► │ via AL extension │
│          │ (Basic Auth, BC REST API)   │                  │
└──────────┘                             └──────────────────┘

Method 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. Prerequisites

Before the integration can be activated, the following must be in place.

3.1 Business Central API access

(Both) Hyperfox requires API access to your Business Central environment for data retrieval (reading customers, items, and other master data). When using the Connector method, the same credentials are also used for order creation. The following environment-specific information is needed during setup:

Configuration	Description	Example
BC API URL	Base URL for the standard BC API	`https://api.businesscentral.dynamics.com/v2.0/{tenantId}/{env}/api/v2.0/companies({companyId})`
API credentials	Username and password for Basic Authentication	Provided by your BC administrator
Sales Order API URL (Connector only)	Endpoint for sales order creation (may differ if using a custom extension)	Same as API URL, or a custom extension URL

3.2 Required BC permissions

The API user account requires the following minimum permission sets:

Permission Set	Access Level	Purpose	Applicability
`D365 READ`	Read	Look up customers, items, and other master data	(Both)
`D365 SALES DOC, EDIT`	Read / Write	Create sales orders and sales order lines	(Connector only)

If a custom attachment extension is used, additional permissions for that endpoint may be required.

3.3 Network configuration

(Both) Hyperfox and the Connector communicate with Business Central from the following static IP addresses. If your organization uses firewall rules or conditional access policies, please whitelist these addresses:

Service	IP Address	FQDN
Connector / API Communication	`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 Note on IP whitelisting Business Central Online does not natively support IP-based restrictions at the application level. For BC Online, IP restrictions are enforced through Entra ID Conditional Access policies (requires Azure AD Premium P1/P2 licensing). For BC On-Premises, standard firewall rules apply. The IPs above are provided for your network infrastructure and audit purposes regardless of deployment type. :::

All communication uses TLS 1.2 or higher. No data is transmitted in plain text.

3.4 Onboarding checklist

The following items must be provided by the customer to the Hyperfox team before the integration can be configured:

Basic Auth credentials — Username and password for the dedicated BC API user account
Base URL for Business Central — The full API base URL including tenant ID, environment, and company ID
API endpoint names — If custom API pages are used, provide the endpoint names for:
- Customers
- Items
- Customer_Item (optional)
- Units_of_measure (optional)
- Item_Unit_Of_Measure (optional)
Webhook endpoint — (Custom BC endpoint method only) The URL of the custom API page in BC that will receive the Hyperfox webhook

4. Custom BC endpoint (recommended)

This section describes the recommended integration method where Business Central receives the Hyperfox webhook directly and processes it internally.

4.1 How it works

An order is validated in Hyperfox (either automatically or after manual review).
Hyperfox sends the validated order as a JSON webhook directly to a custom API page in Business Central.
The AL extension inside BC processes the payload and creates the sales order — all using native BC logic.
BC returns a success or error response. Hyperfox updates the order status accordingly.

Because all order processing happens inside Business Central, this method has full access to BC's validation rules, custom fields, dimensions, location codes, and any other business logic configured in the environment. The Connector is not involved in this flow.

4.2 What the BC partner needs to build

The customer's BC implementation partner creates an AL extension that includes:

A custom API page that accepts the Hyperfox webhook payload (see Section 7 for the full JSON structure).
Order processing logic that maps the incoming Hyperfox fields to BC sales order fields (customer resolution by account number, item resolution by SKU, line creation with quantities).
Error handling that returns meaningful HTTP status codes and error messages so Hyperfox can detect and report failures.

Hyperfox provides:

The webhook payload specification (Section 7)
A staging environment for end-to-end testing
Support during integration development and go-live

5. Connector integration

The Connector is a lightweight middleware service developed and hosted by Hyperfox. When a validated order is ready, Hyperfox sends the webhook to the Connector, which then creates a standard sales order in Business Central using the BC REST API (v2.0).

The Connector uses the standard salesOrders and salesOrderLines API pages. No AL extension or custom development is required on the BC side — the Connector works with a default Business Central setup.

remarque

If your BC environment uses custom API pages, the Connector can be configured to use those instead. Please discuss with Hyperfox during onboarding.

6. Security

6.1 Authentication

(Data retrieval) Hyperfox's built-in BC integration authenticates using HTTP Basic Authentication with a dedicated BC API user account.

(Connector method) The Connector authenticates with Business Central using the same HTTP Basic Authentication credentials. These are stored as environment variables on the Connector server and are never transmitted in plain text.

(Custom BC endpoint method) Authentication between Hyperfox and the custom BC endpoint is handled by the BC platform's own authentication mechanisms (typically Entra ID / OAuth 2.0).

Security control	Implementation
Transport encryption	TLS 1.2+ (mandatory)
Credential storage	Environment variables (encrypted at rest on server)
API authentication (data retrieval & Connector)	HTTP Basic Auth with dedicated service account
API authentication (Custom endpoint)	BC platform authentication (Entra ID / OAuth 2.0)

6.2 Network security

All outbound connections from Hyperfox and the Connector originate from the static IP addresses listed in Section 3.3. For Business Central Online, access restrictions can be enforced via:

Entra ID Conditional Access policies: Restrict API token issuance to the allowed static IPs (requires Azure AD Premium P1/P2).
Tenant allowlisting: BC administrators can restrict environment access to up to 10 external Entra tenant IDs.

For Business Central On-Premises, standard network security controls (firewalls, VPN, IP whitelisting) apply at the infrastructure level.

6.3 Data handling

(Connector method) The Connector processes order data in transit only. The raw webhook payload is temporarily stored on the Connector server during processing and is not retained after the order has been successfully created in Business Central.

(Custom BC endpoint method) No order data passes through the Connector or any middleware — it flows directly from Hyperfox to Business Central.

7. Appendix: Hyperfox webhook payload structure

Below is the JSON structure that Hyperfox sends when delivering a validated order. This payload is identical regardless of whether it is sent to the Connector or to a custom BC endpoint.

7.1 Order header

Field	Type	Description
`id`	UUID	Unique Hyperfox order identifier
`created_at`	Date	Order creation date in Hyperfox
`updated_at`	Date	Last update date
`sales_order_id`	String \| null	BC sales order ID (populated after successful creation)
`processing_status`	String	Always `"validated"` when sent
`issue_date`	Date	Order issue date → maps to `orderDate`
`delivery_date`	Date \| null	Requested delivery date (header level) → maps to `requestedDeliveryDate`
`notes`	String \| null	Free-text notes from the order
`customer_reference`	String	Customer's order reference → maps to `externalDocumentNumber`
`accuracy`	Integer	AI confidence score (0–100)
`error_reason`	String \| null	Error description (null when validated)
`buyer_customer_party_id`	String	Buyer customer account ID → used for BC customer lookup
`accounting_customer_party_id`	String	Invoicing customer account ID (may differ from buyer)
`order_inquiry_id`	UUID	Reference to original email

7.2 Customer party object

The buyer_customer_party and accounting_customer_party objects contain full customer details:

Field	Type	Description
`id`	UUID	Internal Hyperfox customer identifier
`created_at`	Date	Customer record creation date
`updated_at`	Date	Customer record last update date
`account_id`	String	Customer number (e.g. `"C2480"`) → used for BC lookup
`name`	String	Company name
`language`	String \| null	Customer language code
`website_uri`	String \| null	Customer website
`street_name`	String	Street address
`additional_street_name`	String	Additional address line
`city_name`	String	City
`postal_zone`	String	Postal / ZIP code
`country`	String	ISO country code (e.g. `"BE"`)
`contact_name`	String \| null	Contact person name
`contact_telephone`	String	Contact phone number
`contact_email`	String	Contact email address

7.3 Order lines array

Field	Type	Description
`id`	UUID	Unique line identifier
`created_at`	Date	Line creation date
`updated_at`	Date	Line last update date
`order_id`	UUID	Reference to parent order `id`
`quantity`	Integer	Ordered quantity → maps to `quantity`
`item_id`	String	Item SKU → used for BC item lookup
`delivery_date`	Date	Per-line requested delivery date
`customer_reference`	String	Line-level customer reference

7.4 Item object (nested in each line)

Field	Type	Description
`id`	UUID	Internal Hyperfox item identifier
`created_at`	Date	Item record creation date
`updated_at`	Date	Item record last update date
`name`	String	Item description
`description`	String	Extended item description
`brand_name`	String \| null	Brand name
`sku`	String	Item SKU code (e.g. `"FX-PLUSH-STD"`) → used for BC item lookup
`ean`	String	EAN / barcode
`base_unit_code_id`	String	Unit of measure (e.g. `"PCE"`, `"BOX"`)

7.5 Example payload

remarque

This example uses anonymised data. Actual field values will vary per customer.

{
  "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": "",
      "contact_email": "[email protected]"
    },
    "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": "",
      "contact_email": "[email protected]"
    },
    "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"
        }
      }
    ]
  }
}

1. Introduction​

1.1 Terminology​

2. Integration methods​

2.1 Choosing the right method​

2.2 Architecture overview​

3. Prerequisites​

3.1 Business Central API access​

3.2 Required BC permissions​

3.3 Network configuration​

3.4 Onboarding checklist​

4. Custom BC endpoint (recommended)​

4.1 How it works​

4.2 What the BC partner needs to build​

5. Connector integration​

6. Security​

6.1 Authentication​

6.2 Network security​

6.3 Data handling​

7. Appendix: Hyperfox webhook payload structure​

7.1 Order header​

7.2 Customer party object​

7.3 Order lines array​

7.4 Item object (nested in each line)​

7.5 Example payload​