API Reference

This reference is for integrators. All endpoints live under

https://api.businesscentral.dynamics.com/v2.0/{tenant}/{environment}/api/altenbrand/mcIntegration/v1.0/companies({companyId})/

Endpoint	Method	Purpose
`labelRequests`	POST, GET	Request a label, read the outcome
`shipmentLabels`	GET	Read labels (no documents, no addresses)
`shipmentLabels({id})/Microsoft.NAV.cancel`	POST	Cancel the shipment at the carrier
`shipmentLabels({id})/Microsoft.NAV.refreshTracking`	POST	Ask the carrier for the delivery status
`shipmentLabelDocuments({id})`	GET	Label, return label, customs document, COD label as Base64

Request instead of direct write

Labels are never inserted or modified through the API. The client creates a request; the app validates it, creates the label through the hub and writes the outcome back to the request. This keeps licence check, shipping rules and tracking out of reach of any client.

Requesting a label

POST …/labelRequests
Content-Type: application/json

{
  "externalReference": "WMS-2026-000481",
  "source": "WMS",
  "salesOrderNo": "SO-2026-01187",
  "providerCode": "DHL",
  "weightGrams": 1850,
  "mode": "Sync",
  "servicesJson": "[{\"code\":\"AGE_CHECK\",\"parameter1\":\"A18\"},{\"code\":\"INSURANCE\",\"parameter1\":\"2500.00\",\"parameter2\":\"EUR\"}]"
}

{
  "id": "5f0c…",
  "entryNo": 42,
  "status": "Completed",
  "shipmentLabelId": "b71e…",
  "shipmentLabelEntryNo": 10342,
  "trackingNo": "00340434161094015902",
  "errorMessage": ""
}

Request fields

Field	Required	Meaning
`externalReference`	yes	Reference of the calling system, unique together with `source`
`source`	recommended	Identifier of the system, e.g. `WMS` or `SHOP`
`salesOrderNo` / `salesShipmentNo`	exactly one	Sales order or posted sales shipment
`providerCode`	no	Shipment provider; empty = shipping agent of the document, default provider or the only enabled one
`weightGrams`	no	Parcel weight; 0 = calculated document weight
`productCode`	no	Shipping agent service code that selects the carrier product
`mode`	no	`Sync` or `Async`; empty = default mode of the setup
`servicesJson`	no	JSON array of additional services, see below
`shipToName` … `shipToPhone`	no	Replace the ship-to address of the document
`lengthCm`, `widthCm`, `heightCm`	no	Parcel dimensions

Additional services

servicesJson is a JSON array of objects with code, parameter1 and parameter2. The codes are carrier-specific and come from the respective connector. For DHL see Developer Interface → Service codes.

Parameters are limited to 50 characters each. A parameter that does not match the format ends the request with an error; no label is created with a service silently missing.

Behaviour

Sync answers with the final outcome, typically one to three seconds.
Async answers immediately with status = Pending; the client reads the request later via GET …/labelRequests({id}) or ?$filter=externalReference eq '…'.
Input errors (missing reference, unknown document, invalid JSON, duplicate reference) return HTTP 400. The request is not stored.
Guards (module not active, provider not resolvable, label exists, hourly limit) store the request with status = Error and a readable errorMessage.
Carrier errors store the request with status = Error; errorMessage carries the core carrier message, shipmentLabelEntryNo points to the failed label.

Status values

Status	Meaning
`Pending`	Waiting for the job queue
`Processing`	Being processed
`Completed`	Label created, `trackingNo` filled
`Error`	Rejected or failed at the carrier, see `errorMessage`
`Cancelled`	Cancelled before processing

Reading labels

GET …/shipmentLabels?$filter=salesOrderNo eq 'SO-2026-01187'
GET …/shipmentLabels({id})

Fields: id, entryNo, providerCode, salesOrderNo, salesShipmentNo, status, shipmentNo, trackingNo, trackingUrl, labelFormat, weightGrams, productCode, referenceNo, deliveryStatus, lastTrackingUpdate, createdDateTime, cancelledDateTime, errorMessage.

Documents

GET …/shipmentLabelDocuments({id})

Returns labelBase64, returnLabelBase64, customsDocBase64 and codLabelBase64. The format is in labelFormat (PDF or ZPL). Only documents stored in Business Central are returned; a label that was never stored comes back empty.

Actions

POST …/shipmentLabels({id})/Microsoft.NAV.cancel
POST …/shipmentLabels({id})/Microsoft.NAV.refreshTracking

cancel cancels at the carrier and answers true. refreshTracking asks the carrier and answers with the new delivery status as text. Both actions check that the module is active and licensed.

Business events

For Power Automate and Dataverse the app provides three business events in the category merchantCENTRAL Shipment. The payload carries identifiers, numbers and states only; whoever needs addresses reads them through the API with the rights of their own connection.

Event	Payload
`ShipmentLabelCreated`	`labelId`, `labelEntryNo`, `providerCode`, `salesOrderNo`, `salesShipmentNo`, `trackingNo`
`ShipmentLabelFailed`	`labelId`, `labelEntryNo`, `providerCode`, `salesOrderNo`, `salesShipmentNo`, `errorMessage`
`DeliveryStatusChanged`	`labelId`, `labelEntryNo`, `providerCode`, `trackingNo`, `oldStatus`, `newStatus`

The events are raised only while the module is active and licensed.

Permissions

Permission set	For whom
Integration API - Client	The Entra application of the external system. Create and read requests, read labels and documents, execute the API pages. Add the user set of the respective carrier.
Integration API - User	Shipping staff: monitor, retry and cancel requests.
Integration API - Admin	Setup, wizard, job queue.