货物
一票货对应您账号下的一个主单(MAWB);主单分批到港时,对应其中一批。无论订单来自客户门户、邮件,还是由我们的团队录入,都包含在内。数据与您在货物看板上看到的一致。
查询货物列表
Section titled “查询货物列表”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,继续查询下一页。
查询单票货物
Section titled “查询单票货物”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取值,按无需处理对待。