Skip to content

Integration API

The merchantCENTRAL Integration API opens the shipping platform to external systems: warehouse management, shop systems, middleware or Power Automate create shipment labels through a REST API, read labels and documents, cancel shipments and receive business events.

The API is carrier-neutral. It works with every installed merchantCENTRAL shipment connector (DHL, DPD, GLS, UPS, Hermes, Rhenus) and takes the same route as the Create Label Dialog: licence check, shipping rules, contract resolution, tracking entry and the carrier's hub events apply to every request.

Property Value
App AD merchantCENTRAL Integration API
Module MCAPI, licensed separately, one price for all carriers
Prerequisite merchantCENTRAL hub 2.88 or later and at least one activated shipment connector
Base path /api/altenbrand/mcIntegration/v1.0/companies({id})/…
Authentication OAuth2 against Microsoft Entra ID, application user in Business Central

Licence

The Integration API is a module of its own. Start the free 30-day demo from the setup wizard or the setup card. Without an active module or demo, requests end with status Error and a clear message; no label is created. The carrier module a label is requested for must be licensed as well.

The manual route through the Create Label Dialog stays fully included in the carrier module.

Setup

  1. Install the app from AppSource. The hub must be set up already.
  2. Open Assisted Setup → AD merchantCENTRAL Setup → Set up the Integration API.
  3. Register the demo or check the licence.
  4. Set the request guards (see below) and finish the wizard. It activates the recurring job for asynchronous requests.
  5. Activate the module in the hub under Extensions.

Access for external systems

  1. Register an application in Microsoft Entra ID (client credentials).
  2. Create it in Business Central under Microsoft Entra Applications and set its state to Enabled.

  3. Assign it exactly these permission sets:

    Permission set Purpose
    D365 BASIC Basic access of a Business Central session
    D365 READ Reading the master data label creation needs (items, item categories, addresses)
    merchantCENTRAL User Reading shipment providers, writing labels through the hub
    Integration API - Client Create and read requests, read labels and documents
    The user set of every shipment connector it may create labels for for example merchantCENTRAL DHL User

Never assign an administrator permission set

The client set allows exactly what the endpoints need: create and read requests, read labels. It can neither write labels directly nor change any setup. Requests are updated by the processing itself only; a direct PATCH through the API is refused.

A missing right names its table

A response with HTTP 403 and the text Sorry, the current permissions prevented the action names the table and the app. Add the matching set from the list above instead of granting an administrator set.

Request guards

Every label costs money at the carrier. The setup card therefore offers:

Setting Effect
Default Mode Sync creates the label within the API call, Async queues it for the job queue. The client can override the mode per request.
Max Labels per Hour Requests above the limit end with Error. 0 disables the guard.
Max Tracking Refreshes per Hour Limits refreshTracking. The carriers grant only few tracking calls per day, DHL about 250, and the scheduled tracking draws on the same budget. 60 by default, 0 disables the guard.
Allow Duplicate Labels Off by default: a document that already has a label with status Created is rejected.
Retention Days Completed, failed and cancelled requests are removed afterwards.

Add to that idempotency: externalReference + source is unique. A repeated call with the same reference creates no second label; it is rejected with a pointer to the existing request.

Monitoring

  • API Label Requests (search: Integration API) shows every request with source, reference, document, status, tracking number and error text. Actions: Retry, Cancel Request, Process Pending, Shipment Label.
  • The setup card shows tiles for pending, failed-today and completed-today requests and the state of the job queue.
  • The hub dashboard reports requests that failed today in its attention list.

Next steps