开发者

在 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 密钥进行身份验证，该密钥作为 Bearer 令牌在 Authorization 标头中发送。密钥按租户从 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 中生成和管理带作用域的密钥。

订阅事件，而无需轮询变更。

跟踪您的请求量与速率限制的对比情况。