Zum Inhalt

Integration API

Die merchantCENTRAL Integration API öffnet die Versandplattform für externe Systeme: Lagerverwaltung, Shopsysteme, Middleware oder Power Automate erzeugen Versandetiketten über eine REST-API, lesen Etiketten und Dokumente, stornieren Sendungen und erhalten Business Events.

Die API ist carrier-neutral. Sie arbeitet mit jedem installierten merchantCENTRAL Versand-Connector (DHL, DPD, GLS, UPS, Hermes, Rhenus) und läuft über denselben Weg wie der Dialog „Label erstellen": Lizenzprüfung, Versandregeln, Vertragsauflösung, Tracking-Eintrag und die Hub-Events des Carriers greifen bei jeder Anfrage.

Eigenschaft Wert
App AD merchantCENTRAL Integration API
Modul MCAPI, separat lizenziert, ein Preis für alle Carrier
Voraussetzung merchantCENTRAL Hub ab 2.88 und mindestens ein aktivierter Versand-Connector
Basis-Pfad /api/altenbrand/mcIntegration/v1.0/companies({id})/…
Authentifizierung OAuth2 gegen Microsoft Entra ID, App-Benutzer in Business Central

Lizenz

Die Integration API ist ein eigenes Modul. Sie starten die kostenlose 30-Tage-Demo aus dem Einrichtungsassistenten oder der Einrichtungskarte. Ohne aktives Modul oder Demo enden Anfragen mit Status Error und einem klaren Hinweis; es entsteht kein Etikett. Zusätzlich muss das Carrier-Modul lizenziert sein, für das ein Etikett angefordert wird.

Der manuelle Weg über den Dialog „Label erstellen" bleibt vollständig im Carrier-Modul enthalten.

Einrichtung

  1. Installieren Sie die App aus AppSource. Der Hub muss bereits eingerichtet sein.
  2. Öffnen Sie Unterstützte Einrichtung → AD merchantCENTRAL Setup → Integration API einrichten.
  3. Registrieren Sie die Demo oder prüfen Sie die Lizenz.
  4. Legen Sie die Schutzmechanismen fest (siehe unten) und schließen Sie den Assistenten ab. Er aktiviert den wiederkehrenden Auftrag für asynchrone Anfragen.
  5. Aktivieren Sie das Modul im Hub unter Erweiterungen.

Zugriff für externe Systeme

  1. Registrieren Sie eine Anwendung in Microsoft Entra ID (Client Credentials).
  2. Legen Sie sie in Business Central unter Microsoft Entra-Anwendungen an und setzen Sie den Status auf Aktiviert.

  3. Weisen Sie ihr genau diese Berechtigungssätze zu:

    Berechtigungssatz Wofür
    D365 BASIC Grundzugriff einer Business-Central-Sitzung
    D365 READ Lesen der Stammdaten, die die Etikettenerstellung braucht (Artikel, Artikelkategorien, Adressen)
    merchantCENTRAL User Lesen der Versanddienstleister, Schreiben der Etiketten über den Hub
    Integration API - Client Anfragen anlegen und lesen, Etiketten und Belege lesen
    Benutzer-Satz jedes Versand-Connectors, für den sie Etiketten erstellen darf zum Beispiel merchantCENTRAL DHL User

Keinen Administrator-Berechtigungssatz vergeben

Der Client-Satz erlaubt genau das, was die Endpunkte brauchen: Anfragen anlegen und lesen, Etiketten lesen. Er kann weder Etiketten direkt schreiben noch eine Einrichtung ändern. Anfragen ändert nur die Verarbeitung selbst; ein direktes PATCH über die API wird abgelehnt.

Fehlt ein Recht, nennt die Antwort die Tabelle

Eine Antwort mit HTTP 403 und dem Text Sorry, the current permissions prevented the action nennt Tabelle und App. Ergänzen Sie den passenden Satz aus der Liste oben, statt einen Administrator-Satz zu vergeben.

Schutzmechanismen

Jedes Etikett kostet beim Dienstleister Geld. Die Einrichtungskarte bietet deshalb:

Einstellung Wirkung
Standardmodus Synchron erstellt das Etikett im API-Aufruf, Asynchron stellt es für die Aufgabenwarteschlange ein. Der Client kann den Modus je Anfrage überschreiben.
Max. Etiketten pro Stunde Anfragen über dem Limit enden mit Error. 0 schaltet den Schutz ab.
Max. Sendungsverfolgungs-Abrufe pro Stunde Begrenzt refreshTracking. Die Zusteller gewähren nur wenige Abrufe pro Tag, DHL etwa 250, aus denen sich auch die geplante Sendungsverfolgung bedient. Standard 60, 0 schaltet den Schutz ab.
Doppelte Etiketten zulassen Standardmäßig aus: Ein Beleg, der schon ein Etikett mit Status Erstellt hat, wird abgewiesen.
Aufbewahrung (Tage) Abgeschlossene, fehlgeschlagene und stornierte Anfragen werden danach entfernt.

Dazu kommt die Idempotenz: externalReference + source ist eindeutig. Ein wiederholter Aufruf mit derselben Referenz erzeugt kein zweites Etikett, sondern wird mit Verweis auf die vorhandene Anfrage abgewiesen.

Überwachung

  • API-Etikettenanfragen (Suche: Integration API) zeigt jede Anfrage mit Quelle, Referenz, Beleg, Status, Sendungsnummer und Fehlertext. Aktionen: Wiederholen, Anfrage stornieren, Ausstehende verarbeiten, Versandetikett.
  • Die Einrichtungskarte zeigt Kacheln für ausstehende, heute fehlgeschlagene und heute abgeschlossene Anfragen sowie den Status der Aufgabenwarteschlange.
  • Das Hub-Dashboard meldet heute fehlgeschlagene Anfragen in der Aufmerksamkeitsliste.

Nächste Schritte