Entwickler

Entwickeln Sie mit der MG Ship-API

Binden Sie Echtzeit-Sendungstransparenz über eine einfache, versionierte REST-API direkt in Ihre eigenen Systeme ein.

Übersicht

Die MG Ship-API ist eine REST-API, die JSON über HTTPS zurückgibt. Sie bietet Ihren Systemen programmatischen Zugriff auf Daten zur Sendungstransparenz – Auflistungen, vollständige Sendungsdatensätze und Tracking-Verläufe –, sodass Sie Meilensteine in Ihr eigenes TMS, ERP oder Kundenportal übernehmen können.

Jeder Endpunkt befindet sich unter dem unten angegebenen versionierten Basispfad. Die API wird im URL-Pfad versioniert (v1). Breaking Changes werden unter einem neuen Pfad (v2) ausgeliefert, mit einem 12-monatigen Abkündigungszeitraum für die vorherige Version, sodass eine gegen v1 entwickelte Integration weiterhin funktioniert.

Basis-URLs

Wählen Sie die Basis-URL für die Umgebung, gegen die Sie integrieren. Jeder Endpunktpfad unten ist relativ dazu. Staging und Test (VPS) dienen der Entwicklung und dem Testen; verwenden Sie Production nur mit Live-Schlüsseln.

Umgebung	Basis-URL
Production	`https://api.mglobalship.com/api/v1/external`
Staging	`https://api.staging.mglobalship.com/api/v1/external`
Test (VPS)	`https://mgs.aipipis.com/api/v1/external`

OpenAPI-Spezifikation herunterladen ↓Postman-Sammlung herunterladen ↓

Authentifizierung

Authentifizieren Sie jede Anfrage mit einem API-Schlüssel, der als Bearer-Token im Authorization-Header gesendet wird. Schlüssel werden pro Mandant im API Portal ausgestellt, werden nur einmal bei der Erstellung angezeigt, tragen explizite Geltungsbereiche (zum Beispiel shipments.read) und können jederzeit rotiert oder widerrufen werden.

Bewahren Sie Schlüssel serverseitig auf – geben Sie sie niemals in Browser- oder Mobil-Code aus. Falls ein Schlüssel offengelegt wird, rotieren Sie ihn im API Portal, und der alte Schlüssel funktioniert sofort nicht mehr.

bash

curl https://api.staging.mglobalship.com/api/v1/external/health \
  -H "Authorization: Bearer mgs_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Konventionen

Paginierung

List-Endpunkte sind cursor-paginiert. Übergeben Sie limit (1–100, Standard 20), um die Seitengröße festzulegen. Wenn weitere Ergebnisse vorhanden sind, setzt die Antwort has_more auf true und gibt next_cursor zurück; übergeben Sie diesen als cursor-Query-Parameter zurück, um die nächste Seite abzurufen. Cursor sind opak – behandeln Sie sie als Token und erstellen Sie sie nicht selbst.

Ratenlimits

Anfragen werden pro Minute auf Basis Ihrer Konto-Stufe ratenbegrenzt. Jede Antwort enthält die Header X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset (Sekunden bis zum Zurücksetzen des Zeitfensters). Wird das Limit überschritten, wird 429 mit einem retry_after_seconds-Wert im Body zurückgegeben. Einzelnen Schlüsseln kann auf Anfrage eine höhere Obergrenze gewährt werden.

Stufe	Anfragen / Min.
Bronze	60
Silver	300
Gold	1.000
Platinum	5.000
Enterprise	Unbegrenzt

Idempotenz

Schreib-Endpunkte (wie POST /shipments) erfordern einen Idempotency-Key-Header. Ein erneuter Versuch einer Anfrage mit demselben Key gibt das ursprüngliche Ergebnis zurück, anstatt ein Duplikat zu erstellen, sodass ein erneuter Versuch nach einem Netzwerkfehler stets sicher ist. Schreibgeschützte (GET) Endpunkte benötigen ihn nicht.

Endpunkte

GET/health

Prüfen Sie, ob Ihr Schlüssel funktioniert, und sehen Sie Ihre aktuelle Stufe und Ihren Ratenlimit-Status. Ein leichtgewichtiger Aufruf zur Überprüfung der Konnektivität.

bash

curl https://api.staging.mglobalship.com/api/v1/external/health \
  -H "Authorization: Bearer mgs_live_..."

json

{
  "status": "ok",
  "tenant_id": 123,
  "tier": "silver",
  "rate_limit": {
    "limit": 300,
    "remaining": 299,
    "reset_seconds": 59
  }
}

POST/shipments

Registrieren Sie eine Sendung, damit die Plattform mit ihrer Verfolgung beginnt. Erfordert den Geltungsbereich shipments.write und einen eindeutigen Idempotency-Key-Header. Die Sendung wird auf Ihr monatliches Kontingent angerechnet.

Parameter	Typ	Beschreibung
`Idempotency-Key`*	string (header)	Pro Anfrage eindeutig; ein erneuter Versuch mit demselben Wert gibt die ursprüngliche Sendung zurück, anstatt ein Duplikat zu erstellen.
`tracking_number`*	string	Die AWB-/B-L-/Tracking-Nummer.
`carrier_code`*	string	Carrier- oder Airline-Code (PCS-Code, IATA-Airline-Code oder AfterShip-Courier-Slug).
`mode`*	string	Transportmodus: sea, air oder courier.

bash

curl -X POST https://api.staging.mglobalship.com/api/v1/external/shipments \
  -H "Authorization: Bearer mgs_live_..." \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7890" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_number": "160-12345675",
    "carrier_code": "pcs",
    "mode": "air"
  }'

json

{
  "object": "shipment",
  "id": 12346,
  "tracking_number": "160-12345675",
  "carrier_code": "pcs",
  "mode": "air",
  "status": "pending",
  "awb_number": "160-12345675",
  "_links": {
    "self": "/api/v1/external/shipments/12346",
    "tracking": "/api/v1/external/shipments/12346/tracking"
  }
}

GET/shipments

Listen Sie Ihre Sendungen auf, neueste zuerst, mit Cursor-Paginierung und optionalen Filtern.

Parameter	Typ	Beschreibung
`limit`	integer	1–100, Standard 20.
`cursor`	string	Opaker Cursor aus einer vorherigen Seite.
`status`	string	Filtern nach Sendungsstatus, z. B. in_transit.
`q`	string	Volltextsuche über Sendungsfelder.
`mode`	string	air, sea, rail oder road.
`carrier_code`	string	Filtern nach Carrier, z. B. maersk.
`po`	string	Filtern nach Bestellnummer.

bash

curl "https://api.staging.mglobalship.com/api/v1/external/shipments?status=in_transit&limit=20" \
  -H "Authorization: Bearer mgs_live_..."

json

{
  "object": "list",
  "data": [
    {
      "object": "shipment",
      "id": 12345,
      "tracking_number": "MAEU1234567",
      "carrier_code": "maersk",
      "mode": "sea",
      "status": "in_transit",
      "origin": { "country": "CN", "city": "Shanghai", "port_code": "CNSHA" },
      "destination": { "country": "MY", "city": "Port Klang", "port_code": "MYPKG" },
      "po_number": "PO-2026-001",
      "estimated_arrival": "2026-04-30T14:00:00+08:00",
      "_links": {
        "self": "/api/v1/external/shipments/12345",
        "tracking": "/api/v1/external/shipments/12345/tracking"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "_links": { "self": "/api/v1/external/shipments" }
}

GET/shipments/{id}

Rufen Sie eine einzelne Sendung mit vollständigen Frachtdetails und ihrem Meilenstein-Verlauf ab.

Parameter	Typ	Beschreibung
`id`*	integer	Die Sendungs-ID (Pfadparameter).

bash

curl https://api.staging.mglobalship.com/api/v1/external/shipments/12345 \
  -H "Authorization: Bearer mgs_live_..."

json

{
  "object": "shipment",
  "id": 12345,
  "tracking_number": "MAEU1234567",
  "carrier_code": "maersk",
  "mode": "sea",
  "status": "in_transit",
  "origin": { "country": "CN", "city": "Shanghai", "port_code": "CNSHA" },
  "destination": { "country": "MY", "city": "Port Klang", "port_code": "MYPKG" },
  "po_number": "PO-2026-001",
  "container_no": "MAEU123456789",
  "estimated_arrival": "2026-04-30T14:00:00+08:00",
  "vessel_name": "MSC GULSUN",
  "voyage_number": "2026W0105",
  "cargo": {
    "weight_kg": 18000.5,
    "volume_cbm": 45.25,
    "pieces": 120,
    "description": "Electronics",
    "hs_code": "8471.30",
    "container_size": "40HQ",
    "declared_value": { "amount": 499900, "currency": "USD" }
  },
  "milestones": [
    {
      "object": "milestone",
      "status_code": "PICKED_UP",
      "status_text": "Picked up",
      "location": "Shanghai",
      "occurred_at": "2026-04-22T08:15:00+08:00",
      "source": "maersk_direct_api"
    }
  ],
  "_links": {
    "self": "/api/v1/external/shipments/12345",
    "tracking": "/api/v1/external/shipments/12345/tracking"
  }
}

GET/shipments/{id}/weather

Rufen Sie das aktuelle Wetter bzw. die Vorhersage (Open-Meteo) am Ausgangs- und Zielort der Sendung ab. Bedarfsgesteuerte Anreicherung, ca. 30 Min. zwischengespeichert; ein Abschnitt ist null, wenn seine Position nicht ermittelt werden kann.

Parameter	Typ	Beschreibung
`id`*	integer	Die Sendungs-ID (Pfadparameter).

bash

curl https://api.staging.mglobalship.com/api/v1/external/shipments/12345/weather \
  -H "Authorization: Bearer mgs_live_..."

json

{
  "object": "weather",
  "shipment_id": 12345,
  "origin": {
    "label": "Singapore, SG",
    "lat": 1.29,
    "lng": 103.85,
    "observed_at": "2026-06-25T12:00:00+00:00",
    "temperature_c": 29.4,
    "wind_mps": 2.7,
    "condition_id": 803,
    "condition_main": "Clouds",
    "severity": "low",
    "summary": "Clouds",
    "alerts_count": 0
  },
  "destination": {
    "label": "New York, US",
    "lat": 40.71,
    "lng": -74.0,
    "observed_at": "2026-06-25T12:00:00+00:00",
    "temperature_c": 17.1,
    "wind_mps": 0.5,
    "condition_id": 803,
    "condition_main": "Clouds",
    "severity": "low",
    "summary": "Clouds",
    "alerts_count": 0
  },
  "_links": {
    "self": "/api/v1/external/shipments/12345/weather",
    "shipment": "/api/v1/external/shipments/12345"
  }
}

GET/shipments/{id}/risk

Rufen Sie Konflikt-/Unruhe-Ereignisse in der Nähe des Ausgangs- und Zielorts der Sendung ab (innerhalb von 100 km in den letzten 7 days). Bedarfsgesteuerte Anreicherung mit zwischengespeicherten Anbieterergebnissen.

Parameter	Typ	Beschreibung
`id`*	integer	Die Sendungs-ID (Pfadparameter).

bash

curl https://api.staging.mglobalship.com/api/v1/external/shipments/12345/risk \
  -H "Authorization: Bearer mgs_live_..."

json

{
  "object": "geopolitical_risk",
  "shipment_id": 12345,
  "origin": {
    "label": "Singapore, SG",
    "lat": 1.29,
    "lng": 103.85,
    "observed_at": "2026-06-25T12:00:00+00:00",
    "severity": "high",
    "radius_km": 100,
    "since_days": 7,
    "summary": "High: 1 violence_civilians event",
    "events_count": 1,
    "top_events": [
      {
        "occurred_on": "2026-06-21",
        "type": "violence_civilians",
        "sub_type": "Attack",
        "location": "Singapore",
        "fatalities": 0,
        "distance_km": 12.0,
        "description": "High: 1 violence_civilians event"
      }
    ]
  },
  "destination": null,
  "_links": {
    "self": "/api/v1/external/shipments/12345/risk",
    "shipment": "/api/v1/external/shipments/12345"
  }
}

GET/shipments/{id}/tracking

Rufen Sie den kompakten Tracking-Verlauf (geordnete Meilenstein-Ereignisse) für eine Sendung ab.

Parameter	Typ	Beschreibung
`id`*	integer	Die Sendungs-ID (Pfadparameter).

bash

curl https://api.staging.mglobalship.com/api/v1/external/shipments/12345/tracking \
  -H "Authorization: Bearer mgs_live_..."

json

{
  "object": "tracking",
  "shipment_id": 12345,
  "status": "in_transit",
  "estimated_arrival": "2026-04-30T14:00:00+08:00",
  "last_event_at": "2026-04-23T06:00:00+08:00",
  "events": [
    {
      "object": "milestone",
      "status_code": "PICKED_UP",
      "status_text": "Picked up at origin",
      "location": "Shanghai",
      "occurred_at": "2026-04-22T08:15:00+08:00",
      "source": "maersk_direct_api"
    },
    {
      "object": "milestone",
      "status_code": "DEPARTED_ORIGIN",
      "status_text": "Departed origin port",
      "location": "Shanghai",
      "occurred_at": "2026-04-23T06:00:00+08:00",
      "source": "maersk_direct_api"
    }
  ],
  "_links": {
    "self": "/api/v1/external/shipments/12345/tracking",
    "shipment": "/api/v1/external/shipments/12345"
  }
}

Webhooks

Anstatt abzufragen, abonnieren Sie Webhooks, um benachrichtigt zu werden, wenn etwas passiert – zum Beispiel, wenn bei einer Sendung eine Ausnahme auftritt. Sie konfigurieren Endpunkt-URLs und wählen Ereignistypen im API Portal aus, und wir senden für jedes Ereignis einen JSON-Payload per POST an Ihre URL.

Jede Zustellung ist signiert, sodass Sie überprüfen können, dass sie von uns stammt. Wir senden die Signatur im X-MGS-Signature-Header, den Ereignistyp in X-MGS-Event und eine eindeutige Zustellungs-ID in X-MGS-Delivery-Id (verwenden Sie diese erneut, um Ihren Handler idempotent zu machen). Zustellungen werden mit exponentiellem Backoff über 24 Stunden erneut versucht.

X-MGS-Signature hat die Form t=<timestamp>,v1=<signature>, wobei signature der hexadezimale HMAC-SHA256 der Zeichenkette "<timestamp>.<raw-request-body>" ist, mit Ihrem Endpunkt-Secret als Schlüssel. Zur Überprüfung: Trennen Sie t und v1 heraus, berechnen Sie den HMAC über den Zeitstempel, einen wörtlichen Punkt und den exakten Roh-Body neu und vergleichen Sie. Weisen Sie ab, wenn es nicht übereinstimmt oder wenn der Zeitstempel zu alt ist.

http

X-MGS-Event: shipment.exception
X-MGS-Delivery-Id: whd_8f3c2a1b
X-MGS-Signature: t=1715241600,v1=4e2c...hex...sha256

Fehler

Fehler verwenden standardmäßige HTTP-Statuscodes und einen einheitlichen JSON-Umschlag. Das Fehlerobjekt trägt stets einen stabilen Code und eine menschenlesbare Nachricht; einige Fehler fügen Kontextfelder hinzu. Jede Antwort enthält eine request_id – geben Sie diese an, wenn Sie den Support kontaktieren.

Status	Code	Wann
400	`validation_error`	Der Anfragetext fehlt oder ist ungültig (oder der Idempotency-Key-Header fehlt).
401	`auth.token_invalid`	Fehlender oder ungültiger API-Schlüssel.
402	`shipment.overage_payment_required`	Sendungskontingent erschöpft; begleichen Sie zuerst den ausstehenden Mehrverbrauch.
403	`auth.insufficient_scope`	Dem Schlüssel fehlt der erforderliche Geltungsbereich, z. B. shipments.read.
403	`auth.tenant_suspended`	Das Mandantenkonto ist nicht aktiv.
404	`shipment.not_found`	Die angeforderte Ressource existiert nicht.
409	`shipment.duplicate`	Eine Sendung mit dieser Tracking-Nummer und diesem Carrier existiert bereits.
429	`rate_limit_exceeded`	Ratenlimit erreicht; siehe retry_after_seconds.

json

{
  "error": {
    "code": "auth.token_invalid",
    "message": "Token invalid."
  },
  "request_id": "req_9a8b7c6d"
}

json

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded for Silver tier (300 req/min). Wait 23s.",
    "retry_after_seconds": 23
  },
  "request_id": "req_1f2e3d4c"
}

Erste Schritte

API-Schlüssel erstellen

Erstellen und verwalten Sie geltungsbereichsspezifische Schlüssel im API Portal.

Zu den API-Schlüsseln →

Webhooks einrichten

Abonnieren Sie Ereignisse, anstatt Änderungen abzufragen.

Webhooks konfigurieren →

Nutzung überwachen

Verfolgen Sie Ihr Anfragevolumen im Verhältnis zu Ihrem Ratenlimit.

Nutzung anzeigen →