订单
通过 API 下单,与在客户门户的在线下单页面下单完全一致:同样的校验规则,提交成功即录入系统,并发送同样的确认邮件。密钥需要具备 orders:write 权限,请联系您的 Golden Arcus 对接人开通。
curl -X POST https://api.ga-oms.com/v1/orders \ -H "Authorization: Bearer ga_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d @order.jsonorder.json:
{ "mawb": "000-12345675", "service_type": "T11", "destination": "LAX", "origin": "HGH", "eta": "2026-12-01", "flight": "CX 880", "cartons": 120, "gross_weight_kg": 1520.5, "importers": ["Example Importer LLC"], "channels": [ { "channel": "UPS", "cartons": 80 }, { "channel": "USPS", "cartons": 40 } ]}下单成功返回 201,包含订单及其对应的货物:
{ "id": "ord_0a1b2c3d4e5f4a6b8c7d9e0f1a2b3c4d", "object": "order", "shipment_id": "shp_0a1b2c3d4e5f4a6b8c7d9e0f1a2b3c4d", "warnings": [], "shipment": { "id": "shp_0a1b2c3d4e5f4a6b8c7d9e0f1a2b3c4d", "object": "shipment", "mawb": "000-12345675", "phase": "flight", "…": "…" }}请保存 id,用于之后修改订单;保存 shipment_id,用于通过货物和事件跟踪这票货。
| 字段 | 含义 |
|---|---|
mawb |
主单号,格式 NNN-NNNNNNNN |
service_type |
服务类型:T01、T11 或 Ground Handling |
destination |
目的仓:LAX、ORD、JFK 或 IAH |
origin |
起运机场 |
eta |
预计到达日期,YYYY-MM-DD |
flight |
航班号 |
cartons |
总箱数 |
pieces |
分单件数(HAWB PCS) |
gross_weight_kg |
毛重,单位千克 |
importers |
进口商账号。T01 最多三个,T11 一个,Ground Handling 不需要 |
channels |
尾程派送:每个渠道一项,含渠道 channel、箱数 cartons 和胶带颜色 tape(可选)。各渠道箱数之和须等于总箱数 |
draft_7501 |
为 true 时,7501 草单在申报前先交您确认 |
tracking |
追踪模式。box 为扫箱,需要通过 template_file 提供装箱单;默认 none |
customer_ref |
客户参考号,会显示在确认邮件中 |
remark |
备注,供我们的操作团队查看 |
template_file |
已填写的 GA 下单模板,需先上传,见下文 |
attachments |
其他附件,需先上传,最多 10 个 |
数值字段请传数字,不要传字符串。API 无法识别的字段会直接报错,避免拼错的字段名被悄悄忽略。
用下单模板下单
Section titled “用下单模板下单”GA 下单模板(.xlsx,可在客户门户的在线下单页面下载)包含清关资料和装箱单。请先上传文件:
curl -X POST https://api.ga-oms.com/v1/files \ -H "Authorization: Bearer ga_live_YOUR_KEY" \ -F purpose=order_template \{ "id": "file_01JCX7M4Z9Q8R6T5V3W2Y1N0AB", "object": "file", "purpose": "order_template", "filename": "GA-order-000-12345675.xlsx", "size": 48213, "expires_at": "2026-11-19T22:05:11Z"}然后在订单中引用该文件。未传的字段从模板中读取;同时传了的字段,以您传入的值为准:
{ "template_file": "file_01JCX7M4Z9Q8R6T5V3W2Y1N0AB" }purpose可为order_template(下单模板,.xlsx,最大 10 MB)或attachment(其他附件:pdf、doc、docx、xls、xlsx、csv、png、jpg,最大 25 MB)。- 一个文件只能用于一张订单;上传后两天内未被使用的文件会被删除。
- 模板有问题时会被拒绝,并逐条指出问题所在的工作表和行号。
POST /v1/orders/validate 接受与下单相同的请求体,校验规则与下单完全一致,但不会保存任何数据:
{ "object": "order_check", "valid": true, "action": "create", "warnings": [] }无法通过校验的订单,返回与下单时相同的错误响应。
订单未通过校验时
Section titled “订单未通过校验时”所有问题会一次性返回,错误代码为 order_invalid:
{ "type": "https://developers.ga-oms.com/errors/order_invalid", "title": "The order has problems", "status": 422, "code": "order_invalid", "detail": "The order was not accepted: 2 problems", "errors": [ { "message": "ETA \"soon\" must be Y-m-d" }, { "message": "Last-mile CTNs (120) do not equal total CTNs (130)" } ], "request_id": "req_01JCX7M4Z9Q8R6T5V3W2Y1N0AB"}请求头带上 Accept-Language: zh,问题说明将以中文返回。
PATCH /v1/orders/{id} 只修改您传入的字段:
curl -X PATCH https://api.ga-oms.com/v1/orders/ord_0a1b2c3d4e5f4a6b8c7d9e0f1a2b3c4d \ -H "Authorization: Bearer ga_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "flight": "CX 884", "gross_weight_kg": 1498 }'- 可修改的字段:
origin、eta、flight、cartons、pieces、gross_weight_kg、remark、channels、attachments,以及template_file(同时传tracking: "box"可开启扫箱)。 - 系统中已有的 ETA 不会被覆盖,我们团队更正过的数据也不会被覆盖。未生效的内容会在响应的
warnings中说明。 channels的渠道数量须与订单现有的渠道数量一致。mawb、destination、service_type、importers、draft_7501和customer_ref不支持通过 API 修改,请联系我们。
GET /v1/orders/{id} 查询订单及其货物的当前状态。
一个主单只对应一张订单。如果不确定下单是否成功,可以重新提交:如果之前已成功,将返回 order_exists,并带上该订单的 id。
{ "type": "https://developers.ga-oms.com/errors/order_exists", "title": "Already on file", "status": 409, "code": "order_exists", "detail": "MAWB 000-12345675 is already your order ord_0a1b…: change it with PATCH /v1/orders/ord_0a1b….", "order_id": "ord_0a1b2c3d4e5f4a6b8c7d9e0f1a2b3c4d", "shipment_id": "shp_0a1b2c3d4e5f4a6b8c7d9e0f1a2b3c4d", "request_id": "req_01JCX7M4Z9Q8R6T5V3W2Y1N0AB"}返回 busy 时没有保存任何数据:请等待 Retry-After 指定的秒数后,重新发送相同的请求。
| 字段 | 含义 |
|---|---|
id |
由我们生成,用于查询和修改订单 |
shipment_id |
该订单对应的货物 id |
warnings |
已接受但未按原值生效的内容说明。查询订单时为空数组 |
shipment |
完整的货物对象,为当前状态 |