跳转到内容

事件

只要一票货上您可见的内容发生变化,我们就会记录一个事件。您可以随时查询事件,也可以由我们推送给您(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。