跳转到内容

货物

一票货对应您账号下的一个主单(MAWB);主单分批到港时,对应其中一批。无论订单来自客户门户、邮件,还是由我们的团队录入,都包含在内。数据与您在货物看板上看到的一致。

curl "https://api.ga-oms.com/v1/shipments?limit=25" \
-H "Authorization: Bearer ga_live_YOUR_KEY"

按时间倒序返回,最新的在前。以下参数均为可选:

参数 含义
limit 每页数量,1 到 100,默认 25
after 上一页最后一票货的 id
mawb 主单号,格式 NNN-NNNNNNNN
phase 只返回处于该阶段的货物
updated_since ISO 8601 时间,只返回该时间及之后有更新的货物

返回 { "object": "list", "data": [...], "has_more": true }。has_more 为 true 时,把 after 设为最后一个 id,继续查询下一页。

curl https://api.ga-oms.com/v1/shipments/shp_0a1b2c3d4e5f4a6b8c7d9e0f1a2b3c4d \
-H "Authorization: Bearer ga_live_YOUR_KEY"

id 不属于您账号下的货物时,返回 not_found。

{
"id": "shp_0a1b2c3d4e5f4a6b8c7d9e0f1a2b3c4d",
"object": "shipment",
"mawb": "000-12345675",
"part": null,
"service_type": "T11",
"origin": "HGH",
"destination": "LAX",
"flight": "CX 880",
"cartons": 120,
"eta": "2026-11-11T21:40:00-08:00",
"ata": "2026-11-11T22:05:00-08:00",
"phase": "warehouse",
"customs": "released",
"hold": false,
"flags": [],
"status_text": "Ship Out / Breakdown",
"checkpoints": {
"prealert": { "reached": true, "time": "2026-11-09" },
"booked": { "reached": true, "time": null },
"arrived": { "reached": true, "time": "2026-11-11T22:05:00-08:00" },
"released": { "reached": true, "time": "2026-11-12T06:30:00-08:00" },
"in_warehouse": { "reached": true, "time": "2026-11-12T10:15:00-08:00" },
"breakdown": { "reached": true, "time": "2026-11-12T12:40:00-08:00" },
"shipped": { "reached": false, "time": null }
},
"lines": [
{
"channel": "UPS",
"cartons": 80,
"status": "Ship Out",
"customer_ref": null,
"received_at": "2026-11-12T10:15:00-08:00",
"shipped_at": "2026-11-12T13:55:00-08:00"
},
{
"channel": "FEDEX",
"cartons": 40,
"status": "Breakdown",
"customer_ref": null,
"received_at": "2026-11-12T10:15:00-08:00",
"shipped_at": null
}
],
"parts": [],
"cancelled": false,
"updated_at": "2026-11-12T14:04:00-08:00"
}
字段 含义
id 由我们生成,固定不变,主单号更正后也不会变。请保存此 id
mawb 主单号,NNN-NNNNNNNN
part 主单分批到港且该批单独显示时,为该批的字母;否则为 null
service_type 服务类型:T01、T11 或 Ground Handling
origin、destination 起运机场和目的仓。目的仓为 LAX、ORD、JFK 或 IAH
flight 已订舱的航班号,没有则为 null
cartons 主单总箱数,没有则为 null
eta、ata 预计到港时间和实际到港时间
phase 货物当前所处阶段:prealert 已预报、flight 运输中、customs 清关中、released 已放行、warehouse 在仓、shipped 已出库
customs 清关状态,单独给出:not_arrived 未到港、pending 待放行、released 已放行、hold 海关扣货
hold 货物被扣期间为 true;全部出库后恒为 false
flags 需要您关注的事项:hold 海关扣货、pga PGA 查验、action_required 有 7501 草单待您在货物看板上确认
status_text 操作团队填写的状态原文,仅用于展示,请勿用于程序判断
checkpoints 七个固定节点,每个节点包含 reached(是否已完成)和 time(完成时间)
lines 尾程渠道明细,每个渠道一条,含入仓时间和出库时间
parts 主单分多个航班到港时,每个航班一条;否则为空数组
cancelled 订单是否已取消
updated_at 该票货最近一次更新的时间
  • 时间格式为带时区偏移的 ISO 8601,采用目的机场当地时间。只有日期、没有具体时间的(如预报),值为 YYYY-MM-DD。节点已完成但没有记录时间时,time 为 null。
  • 节点按顺序推进。 后面的节点已完成,说明之前的运输节点也已完成。海关放行是例外:货物可能在落地前就已放行。
  • 全部出库才算已出库。 所有渠道都出库后,checkpoints.shipped 才算完成;在此之前 phase 保持 warehouse,可通过 lines 中各渠道的 shipped_at 查看哪些已出库。
  • 字段和取值可能增加。 请忽略不认识的字段;遇到不认识的 flags 取值,按无需处理对待。