Ontwikkelaars

Bouw op de MG Ship-API

Haal realtime zendingzichtbaarheid binnen in je eigen systemen met een eenvoudige, geversioneerde REST-API.

Overzicht

De MG Ship-API is een REST-API die JSON over HTTPS retourneert. Het geeft je systemen programmatische toegang tot gegevens over zendingzichtbaarheid — overzichten, volledige zendingrecords en trackingtijdlijnen — zodat je mijlpalen kunt binnenhalen in je eigen TMS, ERP of klantportaal.

Elk endpoint bevindt zich onder het geversioneerde basispad hieronder. De API is geversioneerd in het URL-pad (v1). Brekende wijzigingen worden uitgebracht onder een nieuw pad (v2) met een afbouwperiode van 12 maanden voor de vorige versie, zodat een integratie die op v1 is gebouwd blijft werken.

Basis-URL's

Kies de basis-URL voor de omgeving waartegen je integreert. Elk endpointpad hieronder is daaraan relatief. Staging en Test (VPS) zijn voor ontwikkeling en testen; gebruik Production alleen met live sleutels.

Omgeving	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-specificatie downloaden ↓Postman-collectie downloaden ↓

Authenticatie

Authenticeer elke aanvraag met een API-sleutel die als Bearer-token in de Authorization-header wordt verzonden. Sleutels worden per tenant uitgegeven vanuit de API Portal, worden slechts één keer getoond bij aanmaak, dragen expliciete scopes (bijvoorbeeld shipments.read) en kunnen op elk moment worden geroteerd of ingetrokken.

Houd sleutels server-side — verzend ze nooit in browser- of mobiele code. Als een sleutel wordt blootgesteld, roteer hem dan vanuit de API Portal en de oude sleutel werkt onmiddellijk niet meer.

bash

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

Conventies

Paginering

Lijst-endpoints zijn cursor-gepagineerd. Geef limit door (1–100, standaard 20) om een pagina te dimensioneren. Wanneer er meer resultaten bestaan, stelt de respons has_more in op true en retourneert next_cursor; geef die terug als de cursor-queryparameter om de volgende pagina op te halen. Cursors zijn ondoorzichtig — behandel ze als een token en stel ze niet zelf samen.

Rate limits

Aanvragen worden per minuut gelimiteerd op basis van je accounttier. Elke respons bevat de headers X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset (seconden tot het venster wordt gereset). Het overschrijden van de limiet retourneert 429 met een retry_after_seconds-waarde in de body. Individuele sleutels kunnen op verzoek een hoger plafond krijgen.

Tier	Aanvragen / min
Bronze	60
Silver	300
Gold	1.000
Platinum	5.000
Enterprise	Onbeperkt

Idempotentie

Schrijf-endpoints (zoals POST /shipments) vereisen een Idempotency-Key-header. Een aanvraag opnieuw proberen met dezelfde sleutel retourneert het oorspronkelijke resultaat in plaats van een duplicaat te maken, dus een netwerk-retry is altijd veilig. Alleen-lezen (GET) endpoints hebben deze niet nodig.

Endpoints

GET/health

Controleer of je sleutel werkt en bekijk je huidige tier en rate-limitstatus. Een lichtgewicht aanroep om connectiviteit te verifiëren.

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

Registreer een zending zodat het platform deze gaat tracken. Vereist de scope shipments.write en een unieke Idempotency-Key-header. De zending telt mee voor het maandquotum van je abonnement.

Parameter	Type	Beschrijving
`Idempotency-Key`*	string (header)	Uniek per aanvraag; opnieuw proberen met dezelfde waarde retourneert de oorspronkelijke zending in plaats van een duplicaat te maken.
`tracking_number`*	string	Het AWB-/B-L-/trackingnummer.
`carrier_code`*	string	Vervoerders- of luchtvaartmaatschappijcode (PCS-code, IATA-luchtvaartmaatschappijcode of AfterShip-courier-slug).
`mode`*	string	Transportmodus: sea, air of 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

Lijst je zendingen, nieuwste eerst, met cursorpaginering en optionele filters.

Parameter	Type	Beschrijving
`limit`	integer	1–100, standaard 20.
`cursor`	string	Ondoorzichtige cursor van een vorige pagina.
`status`	string	Filter op zendingstatus, bijv. in_transit.
`q`	string	Full-text zoeken over zendingvelden.
`mode`	string	air, sea, rail of road.
`carrier_code`	string	Filter op vervoerder, bijv. maersk.
`po`	string	Filter op inkoopordernummer.

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}

Haal één zending op met volledige vrachtgegevens en de bijbehorende mijlpaalgeschiedenis.

Parameter	Type	Beschrijving
`id`*	integer	De zending-id (padparameter).

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

Haal het huidige weer / de weersverwachting (Open-Meteo) op bij de herkomst en bestemming van de zending. Verrijking op aanvraag, ~30 min gecachet; een traject is null wanneer de positie ervan niet kan worden bepaald.

Parameter	Type	Beschrijving
`id`*	integer	De zending-id (padparameter).

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

Haal conflict- / onrustgebeurtenissen op nabij de herkomst en bestemming van de zending (binnen 100 km in de afgelopen 7 days). Verrijking op aanvraag met gecachete resultaten van de provider.

Parameter	Type	Beschrijving
`id`*	integer	De zending-id (padparameter).

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

Haal de compacte trackingtijdlijn (geordende mijlpaalgebeurtenissen) voor een zending op.

Parameter	Type	Beschrijving
`id`*	integer	De zending-id (padparameter).

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

In plaats van te pollen, abonneer je je op webhooks om op de hoogte te worden gesteld wanneer er iets gebeurt — bijvoorbeeld wanneer een zending op een uitzondering stuit. Je configureert endpoint-URL's en selecteert eventtypes in de API Portal, en wij POST'en een JSON-payload naar je URL voor elke event.

Elke aflevering wordt ondertekend zodat je kunt verifiëren dat deze van ons afkomstig is. We sturen de handtekening in de X-MGS-Signature-header, het eventtype in X-MGS-Event en een unieke aflever-id in X-MGS-Delivery-Id (hergebruik deze om je handler idempotent te maken). Afleveringen worden opnieuw geprobeerd met exponentiële backoff gedurende 24 uur.

X-MGS-Signature heeft de vorm t=<timestamp>,v1=<signature>, waarbij signature de hex HMAC-SHA256 is van de string "<timestamp>.<raw-request-body>", gekeyd met je endpoint-secret. Om te verifiëren: splits t en v1 af, herbereken de HMAC over de timestamp, een letterlijke punt en de exacte ruwe body, en vergelijk. Weiger als deze niet overeenkomt of als de timestamp te oud is.

http

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

Fouten

Fouten gebruiken standaard HTTP-statuscodes en een consistente JSON-envelop. Het foutobject draagt altijd een stabiele code en een voor mensen leesbaar bericht; sommige fouten voegen contextvelden toe. Elke respons bevat een request_id — citeer deze wanneer je contact opneemt met support.

Status	Code	Wanneer
400	`validation_error`	De aanvraagbody ontbreekt of is ongeldig (of de Idempotency-Key-header ontbreekt).
401	`auth.token_invalid`	Ontbrekende of ongeldige API-sleutel.
402	`shipment.overage_payment_required`	Zendingsquotum uitgeput; vereffen eerst het openstaande meerverbruik.
403	`auth.insufficient_scope`	Sleutel mist de vereiste scope, bijv. shipments.read.
403	`auth.tenant_suspended`	Het tenant-account is niet actief.
404	`shipment.not_found`	De gevraagde resource bestaat niet.
409	`shipment.duplicate`	Er bestaat al een zending met dit trackingnummer en deze vervoerder.
429	`rate_limit_exceeded`	Rate limit bereikt; zie 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"
}

Aan de slag

Een API-sleutel aanmaken

Genereer en beheer scoped sleutels in de API Portal.

Ga naar API-sleutels →

Webhooks instellen

Abonneer je op events in plaats van te pollen op wijzigingen.

Webhooks configureren →

Gebruik monitoren

Volg je aanvraagvolume ten opzichte van je rate limit.

Gebruik bekijken →