事件
只要一票货上您可见的内容发生变化,我们就会记录一个事件。您可以随时查询事件,也可以由我们推送给您(Webhook)。两种方式得到的事件相同。
curl "https://api.ga-oms.com/v1/events?limit=50" \ -H "Authorization: Bearer ga_live_YOUR_KEY"按时间正序返回,最早的在前,便于依次处理。两个参数均为可选:
| 参数 | 含义 |
|---|---|
limit |
每页数量,1 到 100,默认 50 |
after |
您已处理的最后一个事件的 id,只返回其后的事件 |
最简单的做法:记下已处理的最后一个事件的 id,约每分钟调用一次并把它作为 after 传入,按顺序处理返回的事件。has_more 为 true 时立即继续调用。
{ "id": "evt_e3-01JCX7M4Z9Q8R6T5V3W2Y1N0AB", "object": "event", "type": "shipment.updated", "created_at": "2026-11-12T22:05:11Z", "changed": ["phase", "checkpoints.in_warehouse", "lines"], "data": { "object": { "id": "shp_0a1b2c3d4e5f4a6b8c7d9e0f1a2b3c4d", "object": "shipment", "phase": "warehouse" } }}| 字段 | 含义 |
|---|---|
id |
唯一标识。同一事件重复推送时 id 不变 |
type |
shipment.created(您的账号下新增一票货)或 shipment.updated(货物有更新) |
created_at |
事件的记录时间,UTC |
changed |
相比上一个事件发生变化的字段,节点按名称逐个列出 |
data.object |
事件发生时完整的货物对象。上面的示例有删减 |
- 事件携带完整的货物数据,而不是变更差异。 即使漏掉某个事件,处理下一个事件后数据仍是最新的。
- 顺序。 查询时事件按记录顺序返回;通过 Webhook 推送时可能乱序到达,请以
updated_at最新的一份为准。 - 哪些变化会产生事件。 只有货物对象中您可见的字段发生变化才会产生事件,我们的内部备注不会。
- 创建第一个密钥之前已有的货物不会产生事件。 请先全量查询一次货物列表(快速开始),再从此开始同步事件。
- 事件保留 90 天。 如果
after对应的事件已超过保留期,请不传after,从最早保留的事件开始。 - 事件类型可能增加。 请忽略不认识的
type。