Mga Developer

Mag-build gamit ang MG Ship API

Hilahin ang real-time na shipment visibility papasok sa iyong sariling mga sistema sa pamamagitan ng simple at versioned na REST API.

Pangkalahatang-ideya

Ang MG Ship API ay isang REST API na nagbabalik ng JSON sa pamamagitan ng HTTPS. Binibigyan nito ang iyong mga sistema ng programmatic na access sa shipment visibility data — mga listing, kumpletong shipment record, at mga tracking timeline — para mahila mo ang mga milestone papasok sa iyong sariling TMS, ERP, o customer portal.

Bawat endpoint ay nasa ilalim ng versioned base path sa ibaba. Ang API ay versioned sa URL path (v1). Ang mga breaking change ay inilalabas sa ilalim ng bagong path (v2) na may 12-buwang deprecation window para sa nakaraang bersyon, kaya patuloy na gumagana ang isang integration na ginawa laban sa v1.

Mga Base URL

Piliin ang base URL para sa environment na iyong ini-integrate. Bawat endpoint path sa ibaba ay relative dito. Ang Staging at Test (VPS) ay para sa development at testing; gamitin lang ang Production na may live na mga key.

Environment	Base 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`

I-download ang OpenAPI spec ↓I-download ang Postman collection ↓

Authentication

I-authenticate ang bawat request gamit ang isang API key na ipinapadala bilang Bearer token sa Authorization header. Ang mga key ay inilalabas kada tenant mula sa API Portal, ipinapakita lamang nang isang beses sa paggawa, nagdadala ng tahasang mga scope (halimbawa shipments.read), at maaaring i-rotate o i-revoke anumang oras.

Panatilihin ang mga key sa server-side — huwag kailanman ilagay ang mga ito sa browser o mobile code. Kung mailantad ang isang key, i-rotate ito mula sa API Portal at agad na hihinto sa paggana ang lumang key.

bash

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

Mga Convention

Pagination

Ang mga list endpoint ay cursor-paginated. Ipasa ang limit (1–100, default 20) para itakda ang laki ng isang pahina. Kapag may higit pang resulta, itinatakda ng response ang has_more sa true at nagbabalik ng next_cursor; ipasa ito pabalik bilang cursor query parameter para makuha ang susunod na pahina. Ang mga cursor ay opaque — ituring ang mga ito bilang token, huwag itong gawin mismo nang ikaw na lang.

Mga rate limit

Ang mga request ay rate-limited kada minuto batay sa tier ng iyong account. Bawat response ay may kasamang mga header na X-RateLimit-Limit, X-RateLimit-Remaining, at X-RateLimit-Reset (mga segundo hanggang mag-reset ang window). Ang paglampas sa limit ay nagbabalik ng 429 na may retry_after_seconds value sa body. Ang mga indibidwal na key ay maaaring bigyan ng mas mataas na ceiling kapag hiniling.

Tier	Mga request / min
Bronze	60
Silver	300
Gold	1,000
Platinum	5,000
Enterprise	Walang limitasyon

Idempotency

Ang mga write endpoint (tulad ng POST /shipments) ay nangangailangan ng Idempotency-Key header. Ang muling pagsubok ng request gamit ang parehong key ay nagbabalik ng orihinal na resulta sa halip na gumawa ng duplicate, kaya laging ligtas ang isang network retry. Hindi ito kailangan ng read-only (GET) na mga endpoint.

Mga Endpoint

GET/health

Tiyakin na gumagana ang iyong key at tingnan ang iyong kasalukuyang tier at rate-limit status. Isang magaan na tawag para i-verify ang connectivity.

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

Magrehistro ng isang shipment para simulan itong i-track ng platform. Nangangailangan ng shipments.write scope at isang natatanging Idempotency-Key header. Ang shipment ay binibilang laban sa buwanang quota ng iyong plan.

Parameter	Type	Paglalarawan
`Idempotency-Key`*	string (header)	Natatangi sa bawat request; ang muling pagsubok gamit ang parehong value ay nagbabalik ng orihinal na shipment sa halip na gumawa ng duplicate.
`tracking_number`*	string	Ang AWB / B-L / tracking number.
`carrier_code`*	string	Carrier o airline code (PCS code, IATA airline code, o AfterShip courier slug).
`mode`*	string	Mode ng transportasyon: 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

Ilista ang iyong mga shipment, pinakabago muna, na may cursor pagination at opsyonal na mga filter.

Parameter	Type	Paglalarawan
`limit`	integer	1–100, default 20.
`cursor`	string	Opaque na cursor mula sa nakaraang pahina.
`status`	string	I-filter ayon sa shipment status, hal. in_transit.
`q`	string	Full-text na paghahanap sa mga field ng shipment.
`mode`	string	air, sea, rail, o road.
`carrier_code`	string	I-filter ayon sa carrier, hal. maersk.
`po`	string	I-filter ayon sa purchase-order number.

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}

Kunin ang isang shipment na may kumpletong cargo detail at ang milestone history nito.

Parameter	Type	Paglalarawan
`id`*	integer	Ang shipment id (path parameter).

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

Kunin ang kasalukuyan/forecast na panahon (Open-Meteo) sa pinagmulan at destinasyon ng shipment. On-demand na enrichment, naka-cache nang ~30 min; null ang isang leg kapag hindi matukoy ang posisyon nito.

Parameter	Type	Paglalarawan
`id`*	integer	Ang shipment id (path parameter).

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

Kunin ang mga conflict / civil-unrest event malapit sa pinagmulan at destinasyon ng shipment (sa loob ng 100 km sa nakalipas na 7 days). On-demand na enrichment na may naka-cache na resulta ng provider.

Parameter	Type	Paglalarawan
`id`*	integer	Ang shipment id (path parameter).

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

Kunin ang compact na tracking timeline (nakaayos na mga milestone event) para sa isang shipment.

Parameter	Type	Paglalarawan
`id`*	integer	Ang shipment id (path parameter).

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

Sa halip na mag-poll, mag-subscribe sa webhooks para maabisuhan kapag may nangyari — halimbawa kapag umabot sa exception ang isang shipment. I-configure mo ang mga endpoint URL at piliin ang mga event type sa API Portal, at mag-POST kami ng JSON payload sa iyong URL para sa bawat event.

Bawat delivery ay nilalagdaan para ma-verify mo na galing ito sa amin. Ipinapadala namin ang signature sa X-MGS-Signature header, ang event type sa X-MGS-Event, at isang natatanging delivery id sa X-MGS-Delivery-Id (gamitin itong muli para gawing idempotent ang iyong handler). Ang mga delivery ay sinusubukang muli gamit ang exponential backoff sa loob ng 24 na oras.

Ang X-MGS-Signature ay may anyong t=<timestamp>,v1=<signature>, kung saan ang signature ay ang hex HMAC-SHA256 ng string na "<timestamp>.<raw-request-body>" na naka-key sa iyong endpoint secret. Para i-verify: ihiwalay ang t at v1, muling kalkulahin ang HMAC sa ibabaw ng timestamp, isang literal na tuldok, at ang eksaktong raw body, at ihambing. Tanggihan kung hindi ito tumugma o kung masyadong luma na ang timestamp.

http

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

Mga Error

Ang mga error ay gumagamit ng standard na HTTP status code at isang pare-parehong JSON envelope. Ang error object ay laging may dalang stable na code at human-readable na message; ang ilang error ay nagdadagdag ng mga context field. Bawat response ay may kasamang request_id — banggitin ito kapag nakikipag-ugnayan sa support.

Status	Code	Kailan
400	`validation_error`	Nawawala o di-wasto ang request body (o wala ang Idempotency-Key header).
401	`auth.token_invalid`	Nawawala o di-wastong API key.
402	`shipment.overage_payment_required`	Naubos ang shipment quota; ayusin muna ang nakabinbing overage.
403	`auth.insufficient_scope`	Kulang ang key sa kinakailangang scope, hal. shipments.read.
403	`auth.tenant_suspended`	Hindi aktibo ang tenant account.
404	`shipment.not_found`	Hindi umiiral ang hiniling na resource.
409	`shipment.duplicate`	May umiiral nang shipment na may ganitong tracking number at carrier.
429	`rate_limit_exceeded`	Naabot ang rate limit; tingnan ang 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"
}

Magsimula

Gumawa ng API key

Gumawa at pamahalaan ang mga scoped key sa API Portal.

Pumunta sa mga API key →

Mag-set up ng webhooks

Mag-subscribe sa mga event sa halip na mag-poll para sa mga pagbabago.

I-configure ang webhooks →

Subaybayan ang usage

Subaybayan ang dami ng iyong mga request laban sa iyong rate limit.

Tingnan ang usage →