Sviluppatori

Sviluppa con l'API di MG Ship

Integra la visibilità delle spedizioni in tempo reale nei tuoi sistemi con un'API REST semplice e versionata.

Panoramica

L'API di MG Ship è un'API REST che restituisce JSON tramite HTTPS. Offre ai tuoi sistemi accesso programmatico ai dati di visibilità delle spedizioni — elenchi, record completi delle spedizioni e cronologie di tracciamento — così puoi importare le milestone nel tuo TMS, ERP o portale clienti.

Ogni endpoint risiede sotto il percorso base versionato indicato di seguito. L'API è versionata nel percorso dell'URL (v1). Le modifiche non retrocompatibili vengono rilasciate sotto un nuovo percorso (v2) con una finestra di deprecazione di 12 mesi per la versione precedente, così un'integrazione realizzata su v1 continua a funzionare.

URL di base

Scegli l'URL di base dell'ambiente con cui ti stai integrando. Ogni percorso di endpoint qui sotto è relativo a esso. Staging e Test (VPS) sono destinati allo sviluppo e ai test; usa Production solo con chiavi attive.

Ambiente	URL di 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`

Scarica la specifica OpenAPI ↓Scarica la collezione Postman ↓

Autenticazione

Autentica ogni richiesta con una chiave API inviata come token Bearer nell'header Authorization. Le chiavi vengono emesse per ciascun tenant dall'API Portal, sono mostrate una sola volta al momento della creazione, prevedono ambiti espliciti (ad esempio shipments.read) e possono essere ruotate o revocate in qualsiasi momento.

Mantieni le chiavi lato server — non includerle mai nel codice del browser o delle app mobile. Se una chiave viene esposta, ruotala dall'API Portal e la vecchia chiave smette immediatamente di funzionare.

bash

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

Convenzioni

Paginazione

Gli endpoint di elenco utilizzano la paginazione a cursore. Passa limit (1–100, predefinito 20) per definire la dimensione di una pagina. Quando esistono altri risultati, la risposta imposta has_more su true e restituisce next_cursor; rimandalo come parametro di query cursor per recuperare la pagina successiva. I cursori sono opachi — trattali come un token, non costruirli autonomamente.

Limiti di frequenza

Le richieste sono soggette a un limite di frequenza al minuto in base al tier del tuo account. Ogni risposta include gli header X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (secondi al ripristino della finestra). Il superamento del limite restituisce 429 con un valore retry_after_seconds nel corpo. Le singole chiavi possono ottenere un limite più alto su richiesta.

Tier	Richieste / min
Bronze	60
Silver	300
Gold	1000
Platinum	5000
Enterprise	Illimitate

Idempotenza

Gli endpoint di scrittura (come POST /shipments) richiedono un header Idempotency-Key. Ripetere una richiesta con la stessa chiave restituisce il risultato originale invece di creare un duplicato, perciò un nuovo tentativo dopo un errore di rete è sempre sicuro. Gli endpoint di sola lettura (GET) non ne hanno bisogno.

Endpoint

GET/health

Verifica che la tua chiave funzioni e visualizza il tuo tier attuale e lo stato del limite di frequenza. Una chiamata leggera per verificare la connettività.

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

Registra una spedizione affinché la piattaforma inizi a tracciarla. Richiede l'ambito shipments.write e un header Idempotency-Key univoco. La spedizione viene conteggiata nella quota mensile del tuo piano.

Parametro	Tipo	Descrizione
`Idempotency-Key`*	string (header)	Univoco per ogni richiesta; ripetere la richiesta con lo stesso valore restituisce la spedizione originale invece di crearne un duplicato.
`tracking_number`*	string	Il numero AWB / B-L / di tracciamento.
`carrier_code`*	string	Codice del vettore o della compagnia aerea (codice PCS, codice IATA della compagnia aerea o slug del corriere AfterShip).
`mode`*	string	Modalità di trasporto: sea, air o 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

Elenca le tue spedizioni, dalla più recente, con paginazione a cursore e filtri opzionali.

Parametro	Tipo	Descrizione
`limit`	integer	1–100, predefinito 20.
`cursor`	string	Cursore opaco di una pagina precedente.
`status`	string	Filtra per stato della spedizione, ad esempio in_transit.
`q`	string	Ricerca full-text tra i campi della spedizione.
`mode`	string	air, sea, rail o road.
`carrier_code`	string	Filtra per vettore, ad esempio maersk.
`po`	string	Filtra per numero d'ordine d'acquisto.

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}

Recupera una singola spedizione con i dettagli completi del carico e la sua cronologia delle milestone.

Parametro	Tipo	Descrizione
`id`*	integer	L'id della spedizione (parametro di percorso).

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

Ottieni le condizioni meteo attuali / le previsioni (Open-Meteo) all'origine e alla destinazione della spedizione. Arricchimento su richiesta, memorizzato in cache ~30 min; una tratta è null quando la sua posizione non può essere risolta.

Parametro	Tipo	Descrizione
`id`*	integer	L'id della spedizione (parametro di percorso).

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

Ottieni gli eventi di conflitto / disordini civili nei pressi dell'origine e della destinazione della spedizione (entro 100 km negli ultimi 7 days). Arricchimento su richiesta con risultati del provider memorizzati in cache.

Parametro	Tipo	Descrizione
`id`*	integer	L'id della spedizione (parametro di percorso).

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

Ottieni la cronologia di tracciamento compatta (eventi milestone ordinati) di una spedizione.

Parametro	Tipo	Descrizione
`id`*	integer	L'id della spedizione (parametro di percorso).

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"
  }
}

Webhook

Invece di interrogare ripetutamente, iscriviti ai webhook per ricevere una notifica quando accade qualcosa — ad esempio quando una spedizione genera un'eccezione. Configuri gli URL degli endpoint e selezioni i tipi di evento nell'API Portal, e per ogni evento inviamo una richiesta POST con un payload JSON al tuo URL.

Ogni consegna è firmata così puoi verificare che provenga da noi. Inviamo la firma nell'header X-MGS-Signature, il tipo di evento in X-MGS-Event e un id di consegna univoco in X-MGS-Delivery-Id (riutilizzalo per rendere idempotente il tuo handler). Le consegne vengono ritentate con backoff esponenziale nell'arco di 24 ore.

X-MGS-Signature ha la forma t=<timestamp>,v1=<signature>, dove signature è l'HMAC-SHA256 esadecimale della stringa "<timestamp>.<raw-request-body>" calcolato con la chiave del segreto del tuo endpoint. Per verificarlo: estrai t e v1, ricalcola l'HMAC sul timestamp, un punto letterale e il corpo grezzo esatto, quindi confronta. Rifiuta se non corrisponde o se il timestamp è troppo vecchio.

http

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

Errori

Gli errori utilizzano codici di stato HTTP standard e un envelope JSON coerente. L'oggetto errore riporta sempre un code stabile e un message leggibile; alcuni errori aggiungono campi di contesto. Ogni risposta include un request_id — citalo quando contatti il supporto.

Stato	Codice	Quando
400	`validation_error`	Il corpo della richiesta è mancante o non valido (o l'header Idempotency-Key è assente).
401	`auth.token_invalid`	Chiave API mancante o non valida.
402	`shipment.overage_payment_required`	Quota spedizioni esaurita; salda prima l'eccedenza in sospeso.
403	`auth.insufficient_scope`	La chiave non dispone dell'ambito richiesto, ad esempio shipments.read.
403	`auth.tenant_suspended`	L'account del tenant non è attivo.
404	`shipment.not_found`	La risorsa richiesta non esiste.
409	`shipment.duplicate`	Una spedizione con questo numero di tracciamento e questo vettore esiste già.
429	`rate_limit_exceeded`	Limite di frequenza raggiunto; vedi 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"
}

Per iniziare

Crea una chiave API

Genera e gestisci chiavi con ambiti definiti nell'API Portal.

Vai alle chiavi API →

Configura i webhook

Iscriviti agli eventi invece di interrogare ripetutamente per rilevare le modifiche.

Configura i webhook →

Monitora l'utilizzo

Tieni traccia del volume delle tue richieste rispetto al tuo limite di frequenza.

Visualizza l'utilizzo →