API-Referenz

Diese Referenz richtet sich an Integratoren. Alle Endpunkte liegen unter

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

Endpunkt	Methode	Zweck
labelRequests	POST, GET	Etikett anfordern, Ergebnis lesen
shipmentLabels	GET	Etiketten lesen (ohne Dokumente, ohne Adressen)
shipmentLabels({id})/Microsoft.NAV.cancel	POST	Sendung beim Carrier stornieren
shipmentLabels({id})/Microsoft.NAV.refreshTracking	POST	Zustellstatus beim Carrier abfragen
shipmentLabelDocuments({id})	GET	Label, Retourenlabel, Zolldokument, COD-Label als Base64

Anfrage statt Direktschreiben

Etiketten werden nie über die API eingefügt oder geändert. Der Client legt eine Anfrage an; die App prüft sie, erstellt das Etikett über den Hub und schreibt das Ergebnis auf die Anfrage zurück. Das schützt Lizenzprüfung, Versandregeln und Tracking vor Umgehung.

---

Etikett anfordern

POST …/labelRequests
Content-Type: application/json

{
  "externalReference": "WMS-2026-000481",
  "source": "WMS",
  "salesOrderNo": "VA-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": ""
}

Felder der Anfrage

Feld	Pflicht	Bedeutung
externalReference	ja	Referenz des aufrufenden Systems, zusammen mit source eindeutig
source	empfohlen	Kennung des Systems, z. B. WMS oder SHOP
salesOrderNo / salesShipmentNo	genau eines	Verkaufsauftrag oder gebuchte Verkaufslieferung
providerCode	nein	Versanddienstleister; leer = Versandart des Belegs, Standarddienstleister oder der einzige aktivierte
weightGrams	nein	Paketgewicht; 0 = berechnetes Beleggewicht
productCode	nein	Zustellerservicecode, wählt das Carrier-Produkt
mode	nein	Sync oder Async; leer = Standardmodus der Einrichtung
servicesJson	nein	JSON-Array mit Zusatzleistungen, siehe unten
shipToName … shipToPhone	nein	Ersetzen die Lieferadresse des Belegs
lengthCm, widthCm, heightCm	nein	Paketmaße

Zusatzleistungen

servicesJson ist ein JSON-Array aus Objekten mit code, parameter1 und parameter2. Die Codes sind carrier-spezifisch und stammen aus dem jeweiligen Connector. Für DHL: Entwicklerschnittstelle → Service-Codes.

Parameter sind auf je 50 Zeichen begrenzt. Ein Parameter, der nicht ins Format passt, beendet die Anfrage mit einem Fehler; es entsteht kein Etikett mit stillschweigend fehlender Leistung.

Verhalten

• Sync antwortet mit dem fertigen Ergebnis, typisch ein bis drei Sekunden.
• Async antwortet sofort mit status = Pending; der Client liest die Anfrage später per GET …/labelRequests({id}) oder ?$filter=externalReference eq '…'.
• Eingabefehler (fehlende Referenz, unbekannter Beleg, ungültiges JSON, doppelte Referenz) geben HTTP 400. Die Anfrage wird nicht gespeichert.
• Schutzmechanismen (Modul nicht aktiv, Dienstleister nicht ermittelbar, Etikett vorhanden, Stundenlimit) speichern die Anfrage mit status = Error und einem lesbaren errorMessage.
• Carrier-Fehler speichern die Anfrage mit status = Error; errorMessage enthält die Kernmeldung des Carriers, shipmentLabelEntryNo verweist auf das fehlgeschlagene Etikett.

Statuswerte

Status	Bedeutung
Pending	Wartet auf die Aufgabenwarteschlange
Processing	Wird gerade verarbeitet
Completed	Etikett erstellt, trackingNo gefüllt
Error	Abgewiesen oder beim Carrier gescheitert, siehe errorMessage
Cancelled	Vor der Verarbeitung storniert

---

Etiketten lesen

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

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

Dokumente

GET …/shipmentLabelDocuments({id})

Liefert labelBase64, returnLabelBase64, customsDocBase64 und codLabelBase64. Das Format steht in labelFormat (PDF oder ZPL). Nur in Business Central gespeicherte Dokumente werden geliefert; ein nie gespeichertes Etikett kommt leer zurück.

Aktionen

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

cancel storniert beim Carrier und antwortet mit true. refreshTracking fragt den Carrier ab und antwortet mit dem neuen Zustellstatus als Text. Beide Aktionen prüfen, dass das Modul aktiv und lizenziert ist.

---

Business Events

Für Power Automate und Dataverse stellt die App drei Business Events in der Kategorie merchantCENTRAL Versand bereit. Die Nutzlast enthält nur Kennungen, Nummern und Status; wer Adressen braucht, liest sie mit den Rechten seiner Verbindung über die API.

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

Die Events werden nur ausgelöst, solange das Modul aktiv und lizenziert ist.

---

Berechtigungen

Berechtigungssatz	Für wen
Integration API - Client	Die Entra-Anwendung des externen Systems. Anfragen anlegen und lesen, Etiketten und Belege lesen, API-Pages ausführen. Dazu den User-Satz des jeweiligen Carriers.
Integration API - User	Versandmitarbeiter: Anfragen überwachen, wiederholen, stornieren.
Integration API - Admin	Einrichtung, Assistent, Aufgabenwarteschlange.