跳转到内容

快速开始

开始对接只需要一个 API 密钥。密钥由您的 Golden Arcus 对接人为您的账号创建,只提供一次,以 ga_live_ 开头。

  1. 调用 API。 在 Authorization 请求头中带上密钥。

    curl "https://api.ga-oms.com/v1/shipments?limit=1" \
    -H "Authorization: Bearer ga_live_YOUR_KEY"
  2. 查看返回结果。 列表包含 data 和 has_more。每票货都有 id、mawb(主单号)、phase(当前阶段),以及 checkpoints 对象,记录各节点的完成时间。

    {
    "object": "list",
    "has_more": true,
    "data": [
    {
    "id": "shp_0a1b2c3d4e5f4a6b8c7d9e0f1a2b3c4d",
    "object": "shipment",
    "mawb": "000-12345675",
    "destination": "LAX",
    "phase": "warehouse",
    "customs": "released",
    "hold": false,
    "checkpoints": {
    "arrived": {
    "reached": true,
    "time": "2026-11-11T22:05:00-08:00"
    },
    "released": {
    "reached": true,
    "time": "2026-11-12T06:30:00-08:00"
    }
    }
    }
    ]
    }

    示例有删减,完整字段见货物。

  3. 先全量同步一次。 分页查询货物列表:把上一页最后一个 id 作为 after 传入,直到 has_more 为 false。

    curl https://api.ga-oms.com/v1/shipments -G \
    -d limit=100 \
    -d after=shp_0a1b2c3d4e5f4a6b8c7d9e0f1a2b3c4d \
    -H "Authorization: Bearer ga_live_YOUR_KEY"
  4. 之后同步更新。 两种方式任选其一:

    • 主动查询。 约每分钟调用一次 GET /v1/events,传入您已处理的最后一个事件的 id。见事件。
    • 接收推送。 提供一个 https 地址,事件一产生我们就推送过去。见 Webhook。

    两种方式得到的事件相同,每个事件都包含货物当时的完整数据,直接覆盖保存即可。

每个错误响应都会说明原因,并带有 request_id(请求 ID)。把它发给我们,我们就能定位到那一次调用。见错误处理。