開發人員

在 MG Ship API 上開發

透過簡單、具版本管理的 REST API，將即時貨件追蹤資訊引入你自己的系統。

概覽

MG Ship API 是一個透過 HTTPS 回傳 JSON 的 REST API。它讓你的系統能以程式化方式存取貨件追蹤資料——包括列表、完整貨件記錄及追蹤時間軸——讓你可以將里程碑資訊引入你自己的 TMS、ERP 或客戶入口網站。

每個端點都位於下方具版本管理的基底路徑之下。本 API 以 URL 路徑進行版本管理（v1）。破壞性變更會以新路徑（v2）發布，並為舊版本提供 12 個月的棄用過渡期，因此針對 v1 建構的整合可繼續運作。

基礎 URL

請根據您要對接的環境選擇對應的基礎 URL。下方所有端點路徑均為相對於該基礎 URL 的相對路徑。預備（Staging）和測試（VPS）環境用於開發和測試；正式環境請僅使用正式密鑰。

環境	基礎 URL
正式環境	`https://api.mglobalship.com/api/v1/external`
預備環境	`https://api.staging.mglobalship.com/api/v1/external`
測試（VPS）	`https://mgs.aipipis.com/api/v1/external`

下載 OpenAPI 規格 ↓下載 Postman 集合 ↓

驗證

每個請求都需以 API 密鑰進行驗證，並在 Authorization 標頭中以 Bearer 權杖形式傳送。密鑰按租戶於 API Portal 發出，只在建立時顯示一次，並帶有明確的範圍（例如 shipments.read），可隨時輪換或撤銷。

請將密鑰保留於伺服器端——切勿置於瀏覽器或流動裝置程式碼中。若密鑰外洩，請於 API Portal 進行輪換，舊密鑰會即時失效。

bash

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

慣例

分頁

列表端點採用游標分頁。傳入 limit（1–100，預設 20）以設定每頁大小。當有更多結果時，回應會將 has_more 設為 true 並回傳 next_cursor；將其作為 cursor 查詢參數傳回，即可取得下一頁。游標是不透明的——請將其視為權杖，切勿自行建構。

速率上限

請求會根據你的帳戶等級按每分鐘設定速率上限。每個回應都會包含 X-RateLimit-Limit、X-RateLimit-Remaining 及 X-RateLimit-Reset（距離視窗重設的秒數）標頭。超出上限會回傳 429，並在主體中附帶 retry_after_seconds 值。個別密鑰可按要求獲授予更高的上限。

等級	請求 / 分鐘
Bronze	60
Silver	300
Gold	1,000
Platinum	5,000
Enterprise	無限制

冪等性

寫入端點（例如 POST /shipments）需要 Idempotency-Key 標頭。以相同的密鑰重試請求會回傳原本的結果，而非建立重複記錄，因此網絡重試始終是安全的。唯讀（GET）端點則不需要它。

端點

GET/health

檢查你的密鑰是否有效，並查看你目前的等級及速率上限狀態。這是一項用以驗證連線的輕量級呼叫。

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

登記一件貨件，讓平台開始為其進行追蹤。需要 shipments.write 範圍及唯一的 Idempotency-Key 標頭。該貨件會計入你方案的每月配額。

參數	類型	說明
`Idempotency-Key`*	string (header)	每個請求皆唯一；以相同的值重試會回傳原本的貨件，而非建立重複記錄。
`tracking_number`*	string	AWB / B-L / 追蹤號碼。
`carrier_code`*	string	承運商或航空公司代碼（PCS 代碼、IATA 航空公司代碼或 AfterShip courier 標識）。
`mode`*	string	運輸方式：sea、air 或 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

列出你的貨件，由最新排起，並支援游標分頁及選用的篩選條件。

參數	類型	說明
`limit`	integer	1–100，預設 20。
`cursor`	string	來自上一頁的不透明游標。
`status`	string	按貨件狀態篩選，例如 in_transit。
`q`	string	跨貨件欄位的全文搜尋。
`mode`	string	air、sea、rail 或 road。
`carrier_code`	string	按承運商篩選，例如 maersk。
`po`	string	按採購訂單號碼篩選。

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}

擷取單一貨件，包含完整貨物詳情及其里程碑歷史。

參數	類型	說明
`id`*	integer	貨件 id（路徑參數）。

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

取得該貨件起運地及目的地的即時／預報天氣（Open-Meteo）。按需補充資料，快取約 30 分鐘；當某段航程的位置無法解析時，該段為 null。

參數	類型	說明
`id`*	integer	貨件 id（路徑參數）。

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

取得該貨件起運地及目的地附近（過去 7 days 內、100 km 範圍內）的衝突／民眾騷亂事件。按需補充資料，並快取供應商的結果。

參數	類型	說明
`id`*	integer	貨件 id（路徑參數）。

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

取得某貨件的精簡追蹤時間軸（已排序的里程碑事件）。

參數	類型	說明
`id`*	integer	貨件 id（路徑參數）。

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

毋須輪詢，你可訂閱 webhook，當有事情發生時即獲通知——例如當貨件出現異常時。你可在 API Portal 中設定端點 URL 及選擇事件類型，我們會就每個事件向你的 URL POST 一個 JSON 酬載。

每次傳送都會經過簽署，讓你可以驗證它確實來自我們。我們會在 X-MGS-Signature 標頭中傳送簽章、在 X-MGS-Event 中傳送事件類型，並在 X-MGS-Delivery-Id 中傳送唯一的傳送 id（重用它即可令你的處理常式具冪等性）。傳送失敗會在 24 小時內以指數退避方式重試。

X-MGS-Signature 的格式為 t=<timestamp>,v1=<signature>，其中 signature 是以你的端點密鑰為密鑰，對字串「<timestamp>.<raw-request-body>」計算所得的十六進制 HMAC-SHA256。驗證方法：分拆出 t 及 v1，對時間戳、一個實際的點號及完全相同的原始主體重新計算 HMAC，然後比較。若不相符或時間戳過舊，則予以拒絕。

http

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

錯誤

錯誤採用標準 HTTP 狀態碼及一致的 JSON 封裝結構。錯誤物件必定帶有一個穩定的 code 及一段人類可讀的 message；部分錯誤會附加情境欄位。每個回應都會包含 request_id——聯絡支援團隊時請一併提供。

狀態	代碼	情況
400	`validation_error`	請求主體缺失或無效（或欠缺 Idempotency-Key 標頭）。
401	`auth.token_invalid`	缺少或無效的 API 密鑰。
402	`shipment.overage_payment_required`	貨件配額已用盡；請先結清未付的超額費用。
403	`auth.insufficient_scope`	密鑰欠缺所需範圍，例如 shipments.read。
403	`auth.tenant_suspended`	租戶帳戶並非有效狀態。
404	`shipment.not_found`	所請求的資源並不存在。
409	`shipment.duplicate`	已存在使用此追蹤號碼及承運商的貨件。
429	`rate_limit_exceeded`	已達速率上限；請參閱 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"
}

開始使用

建立 API 密鑰

在 API Portal 中產生及管理具範圍限制的密鑰。

訂閱事件，毋須輪詢以偵測變更。

追蹤你的請求數量與速率上限的比較。