Développeurs

Développez avec l'API MG Ship

Intégrez la visibilité des expéditions en temps réel dans vos propres systèmes grâce à une API REST simple et versionnée.

Présentation

L'API MG Ship est une API REST qui renvoie du JSON via HTTPS. Elle offre à vos systèmes un accès programmatique aux données de visibilité des expéditions — listes, enregistrements complets d'expédition et chronologies de suivi — afin que vous puissiez importer les jalons dans votre propre TMS, ERP ou portail client.

Chaque point de terminaison se trouve sous le chemin de base versionné ci-dessous. L'API est versionnée dans le chemin de l'URL (v1). Les changements incompatibles sont publiés sous un nouveau chemin (v2) avec une période de dépréciation de 12 mois pour la version précédente, de sorte qu'une intégration développée pour v1 continue de fonctionner.

URL de base

Choisissez l'URL de base de l'environnement avec lequel vous intégrez. Chaque chemin de point de terminaison ci-dessous lui est relatif. Staging et Test (VPS) sont destinés au développement et aux tests ; n'utilisez Production qu'avec des clés en production.

Environnement	URL de base
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`

Télécharger la spécification OpenAPI ↓Télécharger la collection Postman ↓

Authentification

Authentifiez chaque requête avec une clé d'API envoyée sous forme de jeton Bearer dans l'en-tête Authorization. Les clés sont émises par locataire depuis l'API Portal, ne sont affichées qu'une seule fois lors de leur création, portent des portées explicites (par exemple shipments.read) et peuvent être renouvelées ou révoquées à tout moment.

Conservez les clés côté serveur — ne les intégrez jamais dans du code navigateur ou mobile. Si une clé est exposée, renouvelez-la depuis l'API Portal et l'ancienne clé cesse immédiatement de fonctionner.

bash

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

Conventions

Pagination

Les points de terminaison de liste sont paginés par curseur. Transmettez limit (1–100, valeur par défaut 20) pour dimensionner une page. Lorsqu'il existe d'autres résultats, la réponse définit has_more sur true et renvoie next_cursor ; renvoyez-le comme paramètre de requête cursor pour récupérer la page suivante. Les curseurs sont opaques — traitez-les comme un jeton, ne les construisez pas vous-même.

Limites de débit

Les requêtes sont limitées par minute en fonction du niveau de votre compte. Chaque réponse inclut les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset (secondes avant la réinitialisation de la fenêtre). Le dépassement de la limite renvoie 429 avec une valeur retry_after_seconds dans le corps. Un plafond plus élevé peut être accordé à des clés individuelles sur demande.

Niveau	Requêtes / min
Bronze	60
Silver	300
Gold	1 000
Platinum	5 000
Enterprise	Illimité

Idempotence

Les points de terminaison d'écriture (tels que POST /shipments) nécessitent un en-tête Idempotency-Key. Réessayer une requête avec la même clé renvoie le résultat initial au lieu de créer un doublon, de sorte qu'une nouvelle tentative après une erreur réseau est toujours sûre. Les points de terminaison en lecture seule (GET) n'en ont pas besoin.

Points de terminaison

GET/health

Vérifiez que votre clé fonctionne et consultez votre niveau actuel ainsi que l'état de votre limite de débit. Un appel léger pour vérifier la connectivité.

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

Enregistrez une expédition pour que la plateforme commence à la suivre. Nécessite la portée shipments.write et un en-tête Idempotency-Key unique. L'expédition est décomptée du quota mensuel de votre forfait.

Paramètre	Type	Description
`Idempotency-Key`*	string (header)	Unique par requête ; réessayer avec la même valeur renvoie l'expédition initiale au lieu de créer un doublon.
`tracking_number`*	string	Le numéro d'AWB / B-L / de suivi.
`carrier_code`*	string	Code du transporteur ou de la compagnie aérienne (code PCS, code IATA de compagnie aérienne ou slug de transporteur AfterShip).
`mode`*	string	Mode de transport : sea, air ou 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

Listez vos expéditions, les plus récentes en premier, avec pagination par curseur et filtres facultatifs.

Paramètre	Type	Description
`limit`	integer	1–100, valeur par défaut 20.
`cursor`	string	Curseur opaque issu d'une page précédente.
`status`	string	Filtrer par statut d'expédition, par exemple in_transit.
`q`	string	Recherche en texte intégral dans les champs d'expédition.
`mode`	string	air, sea, rail ou road.
`carrier_code`	string	Filtrer par transporteur, par exemple maersk.
`po`	string	Filtrer par numéro de bon de commande.

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}

Récupérez une expédition unique avec les détails complets de la cargaison et son historique de jalons.

Paramètre	Type	Description
`id`*	integer	L'identifiant de l'expédition (paramètre de chemin).

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

Obtenez la météo actuelle / les prévisions (Open-Meteo) à l'origine et à la destination de l'expédition. Enrichissement à la demande, mis en cache ~30 min ; un tronçon est null lorsque sa position ne peut pas être résolue.

Paramètre	Type	Description
`id`*	integer	L'identifiant de l'expédition (paramètre de chemin).

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

Obtenez les événements de conflit / troubles civils à proximité de l'origine et de la destination de l'expédition (dans un rayon de 100 km au cours des 7 days). Enrichissement à la demande avec mise en cache des résultats du fournisseur.

Paramètre	Type	Description
`id`*	integer	L'identifiant de l'expédition (paramètre de chemin).

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

Obtenez la chronologie de suivi compacte (événements de jalons ordonnés) d'une expédition.

Paramètre	Type	Description
`id`*	integer	L'identifiant de l'expédition (paramètre de chemin).

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

Au lieu d'interroger, abonnez-vous aux webhooks pour être notifié lorsqu'un événement se produit — par exemple lorsqu'une expédition rencontre une exception. Vous configurez les URL des points de terminaison et sélectionnez les types d'événements dans l'API Portal, et nous envoyons une requête POST avec une charge utile JSON à votre URL pour chaque événement.

Chaque livraison est signée afin que vous puissiez vérifier qu'elle provient bien de nous. Nous envoyons la signature dans l'en-tête X-MGS-Signature, le type d'événement dans X-MGS-Event et un identifiant de livraison unique dans X-MGS-Delivery-Id (réutilisez-le pour rendre votre gestionnaire idempotent). Les livraisons sont réessayées avec un délai exponentiel sur 24 heures.

X-MGS-Signature a la forme t=<timestamp>,v1=<signature>, où signature est le HMAC-SHA256 hexadécimal de la chaîne « <timestamp>.<raw-request-body> » signée avec le secret de votre point de terminaison. Pour vérifier : isolez t et v1, recalculez le HMAC sur l'horodatage, un point littéral et le corps brut exact, puis comparez. Rejetez si la correspondance échoue ou si l'horodatage est trop ancien.

http

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

Erreurs

Les erreurs utilisent des codes de statut HTTP standard et une enveloppe JSON cohérente. L'objet d'erreur porte toujours un code stable et un message lisible par un humain ; certaines erreurs ajoutent des champs de contexte. Chaque réponse inclut un request_id — mentionnez-le lorsque vous contactez le support.

Statut	Code	Quand
400	`validation_error`	Le corps de la requête est manquant ou invalide (ou l'en-tête Idempotency-Key est absent).
401	`auth.token_invalid`	Clé d'API manquante ou invalide.
402	`shipment.overage_payment_required`	Quota d'expéditions épuisé ; réglez d'abord le dépassement en attente.
403	`auth.insufficient_scope`	La clé ne dispose pas de la portée requise, par exemple shipments.read.
403	`auth.tenant_suspended`	Le compte du locataire n'est pas actif.
404	`shipment.not_found`	La ressource demandée n'existe pas.
409	`shipment.duplicate`	Une expédition avec ce numéro de suivi et ce transporteur existe déjà.
429	`rate_limit_exceeded`	Limite de débit atteinte ; voir 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"
}

Premiers pas

Créer une clé d'API

Générez et gérez des clés à portée restreinte dans l'API Portal.

Accéder aux clés d'API →

Configurer les webhooks

Abonnez-vous aux événements au lieu d'interroger les changements.

Configurer les webhooks →

Surveiller l'utilisation

Suivez votre volume de requêtes par rapport à votre limite de débit.

Voir l'utilisation →