curl https://api.ga-oms.com/v1/shipments \
-G -d mawb=000-12345675 \
-H "Authorization: Bearer ga_live_••••"
// 200
{ "object": "list", "has_more": false,
"data": [{
"id": "shp_4f9x…",
"mawb": "000-12345675",
"phase": "customs",
"hold": false,
"eta": "2026-12-01T10:00:00-08:00"
}] }全程七个节点,逐一记录时间
Section titled “全程七个节点,逐一记录时间”- 已预报
prealert11月9日 - 已订舱
bookedCX 880 - 已到港
arrived11月11日 22:05 - 已放行
released11月12日 06:30 - 已入仓
in_warehouse11月12日 10:15 - 已拆板
breakdown11月12日 12:40 - 已出库
shipped未出库
000-12345675,目的仓 LAX,当前处于 warehouse(在仓)阶段。每票货都有这七个节点,每个节点都标明是否已完成及完成时间。获取更新的两种方式
Section titled “获取更新的两种方式”主动查询
约每分钟调用一次,获取上次之后的新事件。您无需部署任何服务。
GET /v1/events?after=evt_e3-01JCX7…
Authorization: Bearer ga_live_••••
// 200
{ "object": "list", "has_more": false,
"data": [{ "type": "shipment.updated",
"changed": ["phase", "lines"], … }] }事件查询或接收推送
提供一个 https 地址,每次更新都会带签名推送过去,通常在一分钟内送达。
POST https://erp.example.com/ga/webhooks
webhook-id: evt_e3-01JCX7…
webhook-timestamp: 1794521112
webhook-signature: v1,K5oZfzN95Z9U…
{ "type": "shipment.updated",
"changed": ["phase", "lines"], … }Webhook 推送为系统对接而设计
Section titled “为系统对接而设计”- 错误信息明确
- 每个错误响应都有固定的
code、一句原因说明和对应的文档页面。错误处理 - 每个响应都带请求 ID
- 把请求 ID 发给我们,我们就能定位到那一次调用。排查问题时无需提供密钥。
- 推送可验签
- Webhook 遵循 Standard Webhooks 规范,并提供 Node.js、Python、PHP 和 Java 的验签示例代码。Webhook
- 一份 OpenAPI 文档
- 整套 API 由一份 OpenAPI 文档描述,可直接导入代码生成器、Postman、Apifox 或 AI 助手:openapi.json
- 只增不改
- v1 只做新增,已有的字段不会改名或删除。更新日志