跳转到内容

订单

通过 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.json

order.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 无法识别的字段会直接报错,避免拼错的字段名被悄悄忽略。

GA 下单模板(.xlsx,可在客户门户的在线下单页面下载)包含清关资料和装箱单。请先上传文件:

curl -X POST https://api.ga-oms.com/v1/files \
-H "Authorization: Bearer ga_live_YOUR_KEY" \
-F purpose=order_template \
-F file=@GA-order-000-12345675.xlsx
{
"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": [] }

无法通过校验的订单,返回与下单时相同的错误响应。

所有问题会一次性返回,错误代码为 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 完整的货物对象,为当前状态