认证

换取访问令牌：client_credentials（client_id = 渠道号，client_secret = 口令）或 password（username = OMS 登录账号，password = OMS 密码）→ Bearer access_token

POST/api/v1/auth/token无需 token

请求体（JSON）

字段	类型	说明
grant_type	string	OAuth2 授权类型：client_credentials（渠道号 + 口令）或 password（OMS 账号 + 密码）。可省略：给了 username 就按 password 处理，否则按 client_credentials。
client_id	string	渠道号（OAuth2 的 client_id），由对接人发放；client_credentials 方式用。想先试可以用 sandbox。最长 32 · 格式 ^[A-Za-z0-9_-]+$
client_secret	string	渠道口令（OAuth2 的 client_secret）；client_credentials 方式用。想先试可以用 sandbox（沙箱返回演示数据，不碰真库存）。最长 256
username	string	OMS 网站的登录账号（password 方式用），比如 100470admin；建议给系统对接单独建一个子账号。想先试可以用 sandbox。最长 64
password	string	OMS 登录密码（password 方式用）。只在换 token 那一刻经手，网关不保存、不记日志。想先试可以用 sandbox。最长 256

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

认证

当前 token 的身份：账号、渠道、能用的仓、权限、业务开关（OMS 账号登录的给 OMS 档案；渠道口令的给仓白名单与网关 scope）

GET/api/v1/me需要 token1 点

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

仓库与库存

仓库清单：仓码、名称、国家、所属公司、合计视图 / 实体仓、能否发货、币种

GET/api/v1/warehouses无需 token

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

仓库与库存

某仓库存：不带筛选 = 整仓（可 page / page_size 分页，响应头 X-Stock-Version 给增量同步用）；sku= 一个变体；product_code= 一款全部变体

GET/api/v1/warehouses/{warehouse_code}/stock需要 tokenstock:read整仓 60 点（分页 5 点）

某仓库存：不带筛选 = 整仓（可 page / page_size 分页，响应头 X-Stock-Version 给增量同步用）；sku= 一个变体；product_code= 一款全部变体。OMS 账号登录时按款 / 按 SKU 走 OMS 实时库存（现货 + 预售批次）

路径参数

名称	类型	说明
warehouse_code 必填	string	仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。

查询参数

名称	类型	说明
sku	string	SKU / 条码——具体到颜色和尺码的那一层，如 OB0021611。查整个款请改用 product_code。最长 64 · 格式 ^[A-Za-z0-9_./-]+$
product_code	string	款号——一个款（含全部色码 / 尺码变体），如 OB002。查单个变体请改用 sku。查价格时可用逗号分隔多个。最长 64 · 格式 ^[A-Za-z0-9_./-]+$
page	number	页码，从 1 开始（选填）。整仓库存不传则返回全量——有三万多行，建议分页。最小 1
page_size	number	每页条数（选填），最大 2000。 1–2000

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

整仓一次约 7.2 MB、60 点。日常同步请用 /Changes 增量口，全量只在首次或游标失效（full=true）时拉。

仓库与库存

库存变更（增量）

GET/api/v1/warehouses/{warehouse_code}/stock/changes需要 tokenstock:read按返回条数计点

库存变更（增量）。传 since=上次拿到的 version；has_more=true 就带着新 version 再调一次，直到 false。needs_full_sync=true 表示 since 太旧，需重做一次全量

路径参数

名称	类型	说明
warehouse_code 必填	string	仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。

查询参数

名称	类型	说明
since	number	上次拿到的 version。首次同步传 0（会返回 needs_full_sync=true，表示要先拉一次全量）。最小 0
limit	number	本次最多返回多少条变更（选填，默认 1000、最大 5000）。是软上限：同一个 version 的变更不会被拆开，所以实际可能略多于这个数。 1–5000

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

限流按实际返回条数计点：跟上进度时每次只算 1 点；落后很多再追，会按追回的条数计。整仓拉一次固定 60 点。

产品

某仓产品列表（按款号去重，含价格；search 按款号 / 品名搜）

GET/api/v1/products需要 tokenproduct:read30 点

某仓产品列表（按款号去重，含价格；search 按款号 / 品名搜）。OMS 账号登录时按你的渠道价与禁售规则返回，和网页一致

查询参数

名称	类型	说明
warehouse_code 必填	string	仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。
search	string	搜索关键词（选填），按款号或品名模糊匹配。最长 128
business_type	string	业务类型（选填）：wholesale 批发 / dropship 代发。不传 = 全部。
page	number	页码，从 1 开始（选填）。整仓库存不传则返回全量——有三万多行，建议分页。最小 1
page_size	number	每页条数（选填），最大 2000。 1–2000

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

产品

款号查产品详情（图片 / 描述 / 价格 + 全部变体 skus）

GET/api/v1/products/{product_code}需要 tokenproduct:read1 点

款号查产品详情（图片 / 描述 / 价格 + 全部变体 skus）。OMS 账号登录时含结算价、最低限价、可买组合（available）、现货与预售批次

路径参数

名称	类型	说明
product_code 必填	string	款号——一个款（含全部色码 / 尺码变体），如 OB002。查单个变体请改用 sku。查价格时可用逗号分隔多个。最长 64 · 格式 ^[A-Za-z0-9_./-]+$

查询参数

名称	类型	说明
warehouse_code	string	仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

产品

SKU 查变体详情（单对象）

GET/api/v1/skus/{sku}需要 tokenproduct:read1 点

路径参数

名称	类型	说明
sku 必填	string	SKU / 条码——具体到颜色和尺码的那一层，如 OB0021611。查整个款请改用 product_code。最长 64 · 格式 ^[A-Za-z0-9_./-]+$

查询参数

名称	类型	说明
warehouse_code	string	仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

产品

代发系统在售产品列表（分页）

GET/api/v1/dropship-products需要 tokenproduct:read1 点

查询参数

名称	类型	说明
warehouse_code 必填	string	仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。
search	string	搜索关键词（选填），按款号或品名模糊匹配。最长 128
business_type	string	业务类型（选填）：wholesale 批发 / dropship 代发。不传 = 全部。
page	number	页码，从 1 开始（选填）。整仓库存不传则返回全量——有三万多行，建议分页。最小 1
page_size	number	每页条数（选填），最大 2000。 1–2000

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

价格

本渠道的产品价格（分页；product_code 可逗号分隔多个）

GET/api/v1/prices需要 tokenprice:read1 点

本渠道的产品价格（分页；product_code 可逗号分隔多个）。OMS 账号登录时给结算价 / 吊牌价 / 调价前结算价（和网页一致）

查询参数

名称	类型	说明
warehouse_code 必填	string	仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。
product_code	string	款号——一个款（含全部色码 / 尺码变体），如 OB002。查单个变体请改用 sku。查价格时可用逗号分隔多个。最长 4096
search	string	搜索关键词（选填），按款号或品名模糊匹配。最长 128
page	number	页码，从 1 开始（选填）。整仓库存不传则返回全量——有三万多行，建议分页。最小 1
page_size	number	每页条数（选填），最大 2000。 1–2000

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

批发订单

你这个账号可用的发货方式（自取 / 自送 / 快递…）

GET/api/v1/shipping-methods需要 tokenorder:read1 点

你这个账号可用的发货方式（自取 / 自送 / 快递…）。下批发单时把 shipping_method_id 填进 shipping

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

批发订单

你这个账号可选的物流公司

GET/api/v1/carriers需要 tokenorder:read1 点

你这个账号可选的物流公司。下批发单时把 carrier_id 填进 shipping（选填）

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

批发订单

你在 OMS 里存的收货地址簿

GET/api/v1/addresses需要 tokenorder:read1 点

你在 OMS 里存的收货地址簿。下批发单时把 address_id 填进 shipping；地址簿在 OMS 网站「用户 → 偏好设置 → 批发收货地址」里维护

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

批发订单

创建批发订单（默认只建草稿，auto_confirm=true 才提交审核）

POST/api/v1/orders需要 tokenorder:write写操作2 点

创建批发订单（默认只建草稿，auto_confirm=true 才提交审核）。OMS 账号登录时要有物流信息：shipping 里给 shipping_method_id（见 /shipping-methods）＋ address_id（见 /addresses）；不传则用你 OMS 账号里的默认设置

请求体（JSON）

字段	类型	说明
warehouse_code 必填	string	仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。
lines 必填	array<object>	明细数组，每项 { sku, quantity }。至少一项；quantity=0 在调整锁单 / 购物车时表示去掉这一行。 1–1000
lines[].sku 必填	string	SKU / 条码——具体到颜色和尺码的那一层，如 OB0021611。查整个款请改用 product_code。最长 64
lines[].quantity 必填	integer	件数，正整数，如 2。锁单调整 / 购物车里传 0 表示去掉这一行。 0–99999
note	string	备注（选填，最长 500 字）。最长 500
client_order_number	string	你自己系统里的订单号（下代发单时传的那个）。最长 64
auto_confirm	boolean	是否直接提交（选填）。不传 = 只保存草稿，需要人在 ERP 里确认后才生效——这是有意的默认。代发单提交后会立刻配货、无法再修改。
shipping	object	物流信息（用 OMS 账号登录下批发单时必需）。里面：shipping_method_id（发货方式，见 GET /api/v1/shipping-methods）、address_id（收货地址，见 GET /api/v1/addresses）、carrier_id（物流公司，选填）、pickup_at（自取时间，自取方式才填）。整个不传则用你 OMS 账号里的默认设置；默认也没设会报错并指路。
shipping.shipping_method_id	string	发货方式编号，从 GET /api/v1/shipping-methods 取。最长 64
shipping.carrier_id	string	物流公司编号（选填），从 GET /api/v1/carriers 取。最长 64
shipping.address_id	string	收货地址编号，从 GET /api/v1/addresses 取。地址簿在 OMS 网站「用户 → 偏好设置 → 批发收货地址」里维护。最长 64
shipping.pickup_at	string	自取时间（选填，自取方式才用），如 2026-09-10T14:00:00。最长 32

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

写操作请带 Idempotency-Key 头（任意唯一串，如 UUID）：网络重试不会重复下单。下单默认只建草稿，由人在 ERP 确认后生效。

批发订单

按日期区间查本渠道批发订单；可再按 client_order_number 收窄

GET/api/v1/orders需要 tokenorder:read1 点

查询参数

名称	类型	说明
client_order_number	string	你自己那边的单号（下单时传过的）——对账时拿它找回我们这边的单最长 64
start_date 必填	string	起始日期，格式 YYYY-MM-DD（含）。最长 10 · 格式 ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
end_date 必填	string	截止日期，格式 YYYY-MM-DD（含）。最长 10 · 格式 ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
status	string	逗号分隔：draft / confirmed / cancelled 最长 128 · 格式 ^[A-Za-z0-9,\s_-]*$

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

批发订单

批发订单详情（带归属校验）

GET/api/v1/orders/{order_id}需要 tokenorder:read1 点

路径参数

名称	类型	说明
order_id 必填	string	批发订单号，从订单列表拿到。只能查本渠道自己的单。最长 64

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

批发订单

作废批发订单（连同它占住的配货一起释放）

DEL/api/v1/orders/{order_id}需要 tokenorder:write写操作2 点

作废批发订单（连同它占住的配货一起释放）。已发货的作废不了

路径参数

名称	类型	说明
order_id 必填	string	批发订单号，从订单列表拿到。只能查本渠道自己的单。最长 64

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

写操作请带 Idempotency-Key 头（任意唯一串，如 UUID）：网络重试不会重复下单。下单默认只建草稿，由人在 ERP 确认后生效。

批发订单

配货预览：逐行给出能配多少 / 欠多少 / 预售几时到货，以及应付金额与余额是否够

POST/api/v1/orders/{order_id}/allocation-preview需要 tokenorder:write写操作2 点

配货预览：逐行给出能配多少 / 欠多少 / 预售几时到货，以及应付金额与余额是否够。⚠️ 预览会占住库存——看完要么提交，要么取消订单

路径参数

名称	类型	说明
order_id 必填	string	批发订单号，从订单列表拿到。只能查本渠道自己的单。最长 64

请求体（JSON）

字段	类型	说明
use_reservation	boolean	是否动用你的锁单（预留库存）来配这批货。不传 = 不动用。

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

写操作请带 Idempotency-Key 头（任意唯一串，如 UUID）：网络重试不会重复下单。下单默认只建草稿，由人在 ERP 确认后生效。

批发订单

提交批发订单（提交后不能再改明细）

POST/api/v1/orders/{order_id}/submit需要 tokenorder:submit写操作2 点

提交批发订单（提交后不能再改明细）。payment_method 默认 invoice（按发票付款）

路径参数

名称	类型	说明
order_id 必填	string	批发订单号，从订单列表拿到。只能查本渠道自己的单。最长 64

请求体（JSON）

字段	类型	说明
payment_method	string	付款方式：balance 余额 / invoice 按发票付款 / wechat 微信 / alipay 支付宝。不传默认 invoice（按发票付款，也就是月结）。
use_reservation	boolean	是否动用你的锁单（预留库存）来配这批货。不传 = 不动用。

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

写操作请带 Idempotency-Key 头（任意唯一串，如 UUID）：网络重试不会重复下单。下单默认只建草稿，由人在 ERP 确认后生效。

代发订单

创建代发订单：一单一个 SKU；收件人（澳新地址要 state / city / postal_code）；shipping normal / express；auto_confirm=true 才提交配货（提交后不能改）

POST/api/v1/dropship-orders需要 tokendf:write写操作2 点

请求体（JSON）

字段	类型	说明
warehouse_code 必填	string	仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。
sku 必填	string	SKU / 条码——具体到颜色和尺码的那一层，如 OB0021611。查整个款请改用 product_code。最长 64
quantity 必填	integer	件数，正整数，如 2。锁单调整 / 购物车里传 0 表示去掉这一行。 1–99999
recipient 必填	object	收件人对象 { name, phone, address, country_code, state, city, postal_code }。country_code 用 AU / CN / NZ；寄澳洲、新西兰时 state / city / postal_code 必填。跨境件电话请带国际区号（如 +61…），地址请含门牌——地址不全是派送失败最常见的原因。
recipient.name 必填	string	收件人姓名，写全名（快递面单上打印的就是它）。最长 128
recipient.phone 必填	string	收件人电话。跨境件请带国际区号（如 +61…），否则清关和派送可能联系不上。最长 64
recipient.address 必填	string	收件地址，请含门牌。地址不全是派送失败最常见的原因。最长 512
recipient.country_code 必填	string	收件国家：AU 澳洲 / CN 中国 / NZ 新西兰（代发只支持这三国）。
recipient.state	string	州 / 省，如 NSW。寄澳洲、新西兰时必填。最长 64
recipient.city	string	城市，如 Sydney。寄澳洲、新西兰时必填。最长 128
recipient.postal_code	string	邮编，如 2000。寄澳洲、新西兰时必填。最长 16
sender	object	发件人对象 { name, phone }（选填），印在面单上的寄件人。
sender.name	string	收件人姓名，写全名（快递面单上打印的就是它）。最长 128
sender.phone	string	收件人电话。跨境件请带国际区号（如 +61…），否则清关和派送可能联系不上。最长 64
shipping_method	string	运输方式：normal 普通（默认）/ express 特快 / ems 邮政EMS。
auto_confirm	boolean	是否直接提交（选填）。不传 = 只保存草稿，需要人在 ERP 里确认后才生效——这是有意的默认。代发单提交后会立刻配货、无法再修改。
client_order_number	string	你自己系统里的订单号（下代发单时传的那个）。最长 64
note	string	备注（选填，最长 500 字）。最长 500

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

写操作请带 Idempotency-Key 头（任意唯一串，如 UUID）：网络重试不会重复下单。下单默认只建草稿，由人在 ERP 确认后生效。

代发订单

代发订单列表：按仓 + 日期区间；或按 client_order_number / serial_number 直接找

GET/api/v1/dropship-orders需要 tokendf:read1 点

查询参数

名称	类型	说明
warehouse_code	string	仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。
start_date	string	起始日期，格式 YYYY-MM-DD（含）。最长 10 · 格式 ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
end_date	string	截止日期，格式 YYYY-MM-DD（含）。最长 10 · 格式 ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
shipped	boolean	只看已发货（true）或未发货（false）的（选填）。
client_order_number	string	你自己系统里的订单号（下代发单时传的那个）。最长 64
serial_number	string	代发流水号，从代发订单列表的返回里拿。只能查本渠道自己的。最长 64

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

代发订单

代发订单汇总列表（分页）

GET/api/v1/dropship-orders/summary需要 tokendf:read1 点

查询参数

名称	类型	说明
warehouse_code 必填	string	仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。
start_date 必填	string	起始日期，格式 YYYY-MM-DD（含）。最长 10 · 格式 ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
end_date 必填	string	截止日期，格式 YYYY-MM-DD（含）。最长 10 · 格式 ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
page	number	页码，从 1 开始（选填）。整仓库存不传则返回全量——有三万多行，建议分页。最小 1
page_size	number	每页条数（选填），最大 2000。 1–2000

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

代发订单

代发订单详情（带归属校验）

GET/api/v1/dropship-orders/{dropship_order_id}需要 tokendf:read1 点

路径参数

名称	类型	说明
dropship_order_id 必填	string	代发订单号，从代发订单列表拿到。只能查本渠道自己的单。最长 64

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

代发订单

作废代发明细（连同它占住的配货一起释放）

DEL/api/v1/dropship-orders/{dropship_order_id}需要 tokendf:write写操作2 点

作废代发明细（连同它占住的配货一起释放）。已发货的作废不了

路径参数

名称	类型	说明
dropship_order_id 必填	string	代发订单号，从代发订单列表拿到。只能查本渠道自己的单。最长 64

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

写操作请带 Idempotency-Key 头（任意唯一串，如 UUID）：网络重试不会重复下单。下单默认只建草稿，由人在 ERP 确认后生效。

代发订单

代发预配：逐条给出能不能配齐、缺多少、预售几时到货、要付多少

POST/api/v1/dropship-orders/allocation-preview需要 tokendf:write写操作2 点

代发预配：逐条给出能不能配齐、缺多少、预售几时到货、要付多少。⚠️ 预配会占住库存——看完要么提交，要么调 DELETE …/{dropship_order_id}/allocation 释放

请求体（JSON）

字段	类型	说明
warehouse_code 必填	string	仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。
dropship_order_ids 必填	array<string>	代发流水号数组（建代发时返回的 serial_number）。一次最多 200 条。 1–200
use_reservation	boolean	是否动用你的锁单（预留库存）来配这批货。不传 = 不动用。

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

写操作请带 Idempotency-Key 头（任意唯一串，如 UUID）：网络重试不会重复下单。下单默认只建草稿，由人在 ERP 确认后生效。

代发订单

提交代发（提交后不能改）

POST/api/v1/dropship-orders/submit需要 tokendf:submit写操作2 点

提交代发（提交后不能改）。建议先预配看缺货，再带上 preview_key 提交；payment_method 默认 invoice

请求体（JSON）

字段	类型	说明
warehouse_code 必填	string	仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。
dropship_order_ids 必填	array<string>	代发流水号数组（建代发时返回的 serial_number）。一次最多 200 条。 1–200
preview_key	string	上一步「配货预览」返回的 preview_key。带上它表示「就按那次预览的结果提交」；不带则提交时重新算一次。最长 128
payment_method	string	付款方式：balance 余额 / invoice 按发票付款 / wechat 微信 / alipay 支付宝。不传默认 invoice（按发票付款，也就是月结）。
use_reservation	boolean	是否动用你的锁单（预留库存）来配这批货。不传 = 不动用。

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

写操作请带 Idempotency-Key 头（任意唯一串，如 UUID）：网络重试不会重复下单。下单默认只建草稿，由人在 ERP 确认后生效。

代发订单

释放这条代发明细占住的预配库存（预配之后决定不提交时用）

DEL/api/v1/dropship-orders/{dropship_order_id}/allocation需要 tokendf:write写操作2 点

路径参数

名称	类型	说明
dropship_order_id 必填	string	代发订单号，从代发订单列表拿到。只能查本渠道自己的单。最长 64

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

写操作请带 Idempotency-Key 头（任意唯一串，如 UUID）：网络重试不会重复下单。下单默认只建草稿，由人在 ERP 确认后生效。

发货与物流

本渠道发货单列表

GET/api/v1/shipments需要 tokensend:read1 点

查询参数

名称	类型	说明
warehouse_code 必填	string	仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。
start_date	string	起始日期，格式 YYYY-MM-DD（含）。最长 10 · 格式 ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
end_date	string	截止日期，格式 YYYY-MM-DD（含）。最长 10 · 格式 ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

发货与物流

上传收件人证件影像 ⚠️ 终端消费者身份证正反面（PII）

POST/api/v1/shipments/identity-documents需要 tokenlogistics:write写操作2 点

上传收件人证件影像 ⚠️ 终端消费者身份证正反面（PII）。默认关闭，需显式申请开通；只透传、不落日志、不进缓存

请求体（JSON）

字段	类型	说明
front_image 必填	string	⚠️ 身份证正面影像（base64）。这是终端消费者的敏感个人信息，我们只透传、不落日志、不进缓存。此接口默认关闭，需显式申请。最长 8000000
back_image 必填	string	⚠️ 身份证背面影像（base64）。同上。最长 8000000
shipment_ids	array<string>	关联的发货单号数组（选填）。 0–100
recipient	object	收件人对象 { name, phone, address, country_code, state, city, postal_code }。country_code 用 AU / CN / NZ；寄澳洲、新西兰时 state / city / postal_code 必填。跨境件电话请带国际区号（如 +61…），地址请含门牌——地址不全是派送失败最常见的原因。
recipient.name	string	收件人姓名，写全名（快递面单上打印的就是它）。最长 128
recipient.phone	string	收件人电话。跨境件请带国际区号（如 +61…），否则清关和派送可能联系不上。最长 64
document_number	string	收件人证件号（选填），清关时核对用。最长 64

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

写操作请带 Idempotency-Key 头（任意唯一串，如 UUID）：网络重试不会重复下单。下单默认只建草稿，由人在 ERP 确认后生效。

发货与物流

发货单详情（带归属校验）

GET/api/v1/shipments/{shipment_id}需要 tokensend:read1 点

路径参数

名称	类型	说明
shipment_id 必填	string	发货单号（物流轨迹里也是它），从发货单列表拿到。只能查本渠道自己的单。最长 64

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

发货与物流

物流轨迹（澳邮 Auexpress；默认关闭，需申请开通）

GET/api/v1/shipments/{shipment_id}/tracking需要 tokenlogistics:read1 点

路径参数

名称	类型	说明
shipment_id 必填	string	发货单号（物流轨迹里也是它），从发货单列表拿到。只能查本渠道自己的单。最长 64

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

锁单

本渠道锁单 / 预留库存列表（默认 reserved + cancelled；status= 只看一种）

GET/api/v1/reservations需要 tokenpdstock:read1 点

查询参数

名称	类型	说明
warehouse_code 必填	string	仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。
start_date	string	起始日期，格式 YYYY-MM-DD（含）。最长 10 · 格式 ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
end_date	string	截止日期，格式 YYYY-MM-DD（含）。最长 10 · 格式 ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
status	string	状态过滤（选填），多个用逗号分隔。批发订单：draft 未审核 / confirmed 已审核 / cancelled 作废；锁单：reserved 锁定中 / cancelled 已作废。不传则不过滤（锁单默认 reserved + cancelled）。响应里 status 是同一套词，status_raw 是上游原值。

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

锁单

锁单详情（带归属校验）

GET/api/v1/reservations/{reservation_id}需要 tokenpdstock:read1 点

路径参数

名称	类型	说明
reservation_id 必填	string	锁单单据号，从锁单列表拿到。只能查 / 改本渠道自己的单。最长 64

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

锁单

调整锁单明细（写；带归属校验）

PATCH/api/v1/reservations/{reservation_id}需要 tokenpdstock:write写操作2 点

路径参数

名称	类型	说明
reservation_id 必填	string	锁单单据号，从锁单列表拿到。只能查 / 改本渠道自己的单。最长 64

请求体（JSON）

字段	类型	说明
lines 必填	array<object>	明细数组，每项 { sku, quantity }。至少一项；quantity=0 在调整锁单 / 购物车时表示去掉这一行。 1–1000
lines[].sku 必填	string	SKU / 条码——具体到颜色和尺码的那一层，如 OB0021611。查整个款请改用 product_code。最长 64
lines[].quantity 必填	integer	件数，正整数，如 2。锁单调整 / 购物车里传 0 表示去掉这一行。 0–99999
note	string	备注（选填，最长 500 字）。最长 500

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

写操作请带 Idempotency-Key 头（任意唯一串，如 UUID）：网络重试不会重复下单。下单默认只建草稿，由人在 ERP 确认后生效。

对账

你的账户余额（澳洲 / 中国 / 新西兰，开了哪个给哪个）

GET/api/v1/balances需要 tokenfinance:read1 点

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

对账

交易流水（充值 / 扣款 / 退款），带每笔之后的账户余额；amount_total 是这批的合计

GET/api/v1/transactions需要 tokenfinance:read1 点

交易流水（充值 / 扣款 / 退款），带每笔之后的账户余额；amount_total 是这批的合计。对账主表

查询参数

名称	类型	说明
start_date	string	起始日期，格式 YYYY-MM-DD（含）。最长 10 · 格式 ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
end_date	string	截止日期，格式 YYYY-MM-DD（含）。最长 10 · 格式 ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
type	string	只看某一类交易流水（选填）：recharge 充值 / payment 扣款 / refund 退款。不传 = 全部。
page	number	页码，从 1 开始（选填）。整仓库存不传则返回全量——有三万多行，建议分页。最小 1
page_size	number	每页条数（选填），最大 2000。 1–2000

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

对账

月度账单（按仓、按月，含是否已付）

GET/api/v1/bills需要 tokenfinance:read1 点

查询参数

名称	类型	说明
start_date	string	起始日期，格式 YYYY-MM-DD（含）。最长 10 · 格式 ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
end_date	string	截止日期，格式 YYYY-MM-DD（含）。最长 10 · 格式 ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
page	number	页码，从 1 开始（选填）。整仓库存不传则返回全量——有三万多行，建议分页。最小 1
page_size	number	每页条数（选填），最大 2000。 1–2000

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

对账

退款单（批发 / 代发，含审核状态与原因）

GET/api/v1/refunds需要 tokenfinance:read1 点

查询参数

名称	类型	说明
start_date	string	起始日期，格式 YYYY-MM-DD（含）。最长 10 · 格式 ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
end_date	string	截止日期，格式 YYYY-MM-DD（含）。最长 10 · 格式 ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
page	number	页码，从 1 开始（选填）。整仓库存不传则返回全量——有三万多行，建议分页。最小 1
page_size	number	每页条数（选填），最大 2000。 1–2000

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

对账

运费单（承运商、运单号、箱数、金额）

GET/api/v1/freight-bills需要 tokenfinance:read1 点

查询参数

名称	类型	说明
start_date	string	起始日期，格式 YYYY-MM-DD（含）。最长 10 · 格式 ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
end_date	string	截止日期，格式 YYYY-MM-DD（含）。最长 10 · 格式 ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
page	number	页码，从 1 开始（选填）。整仓库存不传则返回全量——有三万多行，建议分页。最小 1
page_size	number	每页条数（选填），最大 2000。 1–2000

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

购物车

查某账号购物车

GET/api/v1/carts/{account}需要 tokencart:read1 点

路径参数

名称	类型	说明
account 必填	string	购物车所属账号（OMS 网站的登录账号，如 100470admin）。最长 64

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

购物车

添加 / 更新购物车条目（幂等）

PUT/api/v1/carts/{account}/lines需要 tokencart:write写操作2 点

路径参数

名称	类型	说明
account 必填	string	购物车所属账号（OMS 网站的登录账号，如 100470admin）。最长 64

请求体（JSON）

字段	类型	说明
lines 必填	array<object>	明细数组，每项 { sku, quantity }。至少一项；quantity=0 在调整锁单 / 购物车时表示去掉这一行。 1–500
lines[].sku 必填	string	SKU / 条码——具体到颜色和尺码的那一层，如 OB0021611。查整个款请改用 product_code。最长 64
lines[].quantity 必填	integer	件数，正整数，如 2。锁单调整 / 购物车里传 0 表示去掉这一行。 0–99999

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

写操作请带 Idempotency-Key 头（任意唯一串，如 UUID）：网络重试不会重复下单。下单默认只建草稿，由人在 ERP 确认后生效。

购物车

按 SKU 移除购物车条目

DEL/api/v1/carts/{account}/lines/{sku}需要 tokencart:write写操作2 点

路径参数

名称	类型	说明
account 必填	string	购物车所属账号（OMS 网站的登录账号，如 100470admin）。最长 64
sku 必填	string	SKU / 条码——具体到颜色和尺码的那一层，如 OB0021611。查整个款请改用 product_code。最长 64

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

写操作请带 Idempotency-Key 头（任意唯一串，如 UUID）：网络重试不会重复下单。下单默认只建草稿，由人在 ERP 确认后生效。

购物车

按款号移除购物车里这一款的全部 SKU

DEL/api/v1/carts/{account}/products/{product_code}需要 tokencart:write写操作2 点

路径参数

名称	类型	说明
account 必填	string	购物车所属账号（OMS 网站的登录账号，如 100470admin）。最长 64
product_code 必填	string	款号——一个款（含全部色码 / 尺码变体），如 OB002。查单个变体请改用 sku。查价格时可用逗号分隔多个。最长 64

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

写操作请带 Idempotency-Key 头（任意唯一串，如 UUID）：网络重试不会重复下单。下单默认只建草稿，由人在 ERP 确认后生效。

Feeds

取商品 feed（Google Merchant 规格，同时就是批量导出）：有现成的先给你，旧了后台重拼；一次没拼过则回 202 并开始拼

GET/api/v1/feeds/products需要 tokenproduct:read1 点

取商品 feed（Google Merchant 规格，同时就是批量导出）：有现成的先给你，旧了后台重拼；一次没拼过则回 202 并开始拼。响应头里带行数、有图数、扔掉了什么、会被平台挑什么毛病、以及这份拼于什么时候

查询参数

名称	类型	说明
warehouse_code 必填	string	仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。
format	string	csv（默认）/ xml / json 最长 8
link_template	string	你站上的商品页地址模板，里面用 {product_code} 或 {sku} 占位，我们替你拼。不给就不出 link，而 link 是必填项最长 300
image_base	string	图片链接的绝对前缀。不给用服务端配置。必须走加密链接（TLS），明文图片链接各平台基本都会拒最长 200
rebuild	boolean	强制重拼，不用缓存那份

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

Feeds

看 feed 拼到哪了：在拼 / 好了 / 失败（带原因），以及最新一份的行数与毛病

GET/api/v1/feeds/products/status需要 tokenproduct:read1 点

查询参数

名称	类型	说明
warehouse_code 必填	string	仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。

响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 { data: … }（列表另带 page / page_size / has_more 或 total_count）；失败是 4xx / 5xx，正文 { error: { code, message, hint, request_id, doc_url } }。

参考资料

业务流程

一个流程 = 一件事，内部按顺序调哪几条接口都列在这里。AI 助手和 MCP 用的就是这份定义，所以它不会和代码对不上。

check_stock

一次问一批货还有没有：给一串 SKU（条码），逐个告诉你可用数量、你的结算价、缺货的预计到货日。问「这几个还有吗」用这个，别一个个查。

#	这一步	对应接口
1	me	GET /api/v1/me
2	stock_list	GET /api/v1/warehouses/{warehouse_code}/stock

需要权限：stock:read

find_products

按关键词找货：给款号或品名的一部分，返回匹配的款、你的结算价、能不能补货。想知道某一款有哪些颜色尺码、有没有货，再用 check_stock 或 product_get。

#	这一步	对应接口
1	me	GET /api/v1/me
2	product_list	GET /api/v1/products

需要权限：product:read

get_statement

对一段时间的账：一次给出账户余额、这段时间的流水合计和明细。问「这个月花了多少」「余额还剩多少」「对一下账」用这个。

#	这一步	对应接口
1	balance_list	GET /api/v1/balances
2	transaction_list	GET /api/v1/transactions

需要权限：finance:read

quote_order 写操作

批发下单前先看配货：建一张草稿单并跑配货预览，告诉你每一行能配多少、缺多少、几时到货、一共要付多少，不提交。看完要交就用 place_order，不交就用 cancel_order 撤掉（草稿留着会占配货）。

#	这一步	对应接口
1	me	GET /api/v1/me
2	order_create	POST /api/v1/orders
3	order_allocation_preview	POST /api/v1/orders/{order_id}/allocation-preview

需要权限：order:write

place_order 写操作

提交批发订单（提交后不能再改明细）。先用 quote_order 看过配货和金额再交。付款方式默认按发票付款。

#	这一步	对应接口
1	order_submit	POST /api/v1/orders/{order_id}/submit

需要权限：order:write

cancel_order 写操作

作废一张批发订单，连同它占住的配货一起释放。看完配货决定不下了，用这个收尾。

#	这一步	对应接口
1	order_cancel	DELETE /api/v1/orders/{order_id}

需要权限：order:write

quote_dropship 写操作

代发下单前先预配：把这批代发明细建出来并跑预配，逐条告诉你能不能配齐、缺多少、要付多少，不提交。这是代发的标准做法——先看缺货再决定。要交用 place_dropship，不交用 release_dropship 释放。

#	这一步	对应接口
1	me	GET /api/v1/me
2	dropship_order_create	POST /api/v1/dropship-orders
3	dropship_order_allocation_preview	POST /api/v1/dropship-orders/allocation-preview

需要权限：df:write

place_dropship 写操作

提交代发（提交后不能改）。带上 quote_dropship 返回的 preview_key，就按那次预配的结果交。

#	这一步	对应接口
1	me	GET /api/v1/me
2	dropship_order_submit	POST /api/v1/dropship-orders/submit

需要权限：df:write

release_dropship 写操作

释放代发预配占住的库存（预配完决定不交时用）。不释放的话这批货会一直被占着。

#	这一步	对应接口
1	dropship_order_allocation_cancel	DELETE /api/v1/dropship-orders/{dropship_order_id}/allocation

需要权限：df:write

参考资料

错误码目录

错误响应里的 error.code 是稳定的，按它编程判断，别解析文案。error.docUrl 指到这一行。

错误码	含义	怎么修
AUTH_MISSING_TOKEN	缺少认证 token	在 Authorization 头带 `Bearer <token>`（/api/v1 不认 ?token= 查询串）。token 用 POST /api/v1/auth/token（请求体 client_id + client_secret）换。
AUTH_INVALID_TOKEN	token 无效	token 格式或签名不对。重新用 POST /api/v1/auth/token 取一个；确认没截断、没多空格。
AUTH_EXPIRED	token 已过期	token 有效期到了。重新取一个；建议客户端在快过期时自动续。
SCOPE_DENIED	无此操作权限	你的渠道角色不包含该能力。到「套餐与申请」选一档申请开通（reader / trader / full），对接人审批后即时生效。
WAREHOUSE_DENIED	无此仓库权限	你的渠道不在该仓的白名单。请管理员在后台把该仓加进你渠道的仓白名单，或清空白名单=不限仓。
AUTHZ_UNAVAILABLE	授权服务暂不可用	授权服务暂时不可用。稍后重试；若持续，带上 requestId 联系对接人。
VALIDATION_FAILED	请求参数不合法	按 error.param 指出的字段修正。各端点字段规格见 /swagger。
NOT_FOUND	查无此项	款号/SKU/单号不存在或拼写有误。核对后重试。
OWNERSHIP_DENIED	无权访问该单据	该单据不属于你的渠道。只能查自己渠道的订单/发货单/锁单。
UPSTREAM_ERROR	上游 ERP 出错	上游 ERP 暂时异常。稍后重试；带上 requestId 联系运维可定位到具体那次。
UPSTREAM_TIMEOUT	上游超时	上游 ERP 响应慢或不通。稍后重试。
INTERNAL	网关内部错误	网关自身异常（少见）。带上 requestId 联系运维。
ADMIN_UNAUTHORIZED	管理员口令不对	检查 x-admin-token 是否是服务器 .env 里的 ADMIN_TOKEN。
ADMIN_DISABLED	后台未启用	服务器未设 ADMIN_TOKEN。设置后重启即可用。
IDEMPOTENCY_IN_PROGRESS	同一幂等请求正在处理	上一次带相同 Idempotency-Key 的请求还没跑完。稍等重试即可，不要换 key（换了就可能重复下单）。
IDEMPOTENCY_MISMATCH	Idempotency-Key 被复用	这个 key 之前用在内容不同的请求上。每一笔业务用一个新 key（建议 UUID 或你自己的订单号）。
IDEMPOTENCY_INVALID_KEY	Idempotency-Key 不合法	key 长度上限 255 字符。建议用 UUID。
RATE_LIMITED	调用额度用完	看响应头 RateLimit-Remaining / Retry-After，等一下再试。拉全仓库存很贵（一次 60 点），改用增量口 /Changes?since= 只花 1 点。确实不够用找对接人提额。
BAD_REQUEST	请求有误	检查请求方法、路径、body 是否正确。
READ_ONLY_MODE	本环境为只读模式	这台服务器有意关闭了对上游 ERP 的写入（WRITES_ENABLED=0），用于安全测试。查询照常可用。需要真正下单请用生产环境。
ENDPOINT_GONE	接口已下线	接口面已迁到 /api/v1/**（路径小写、参数 snake_case）。error.message 里给了对应的新地址；完整清单见 /reference 或 /llms.txt。
WAREHOUSE_UNKNOWN	没有这个仓库	仓码用 GET /api/v1/warehouses 里列出的那几个（AU / AUSYD2 / AUSYD1 / CN / CHNZJ1），不再有 AuStock 这类别名。
UPSTREAM_REJECTED	上游拒绝了这次请求	ERP 没有接受这笔业务（库存不足、单号不存在、字段不合规…），原因在 error.message 里。修正后重试；反复出现请把 request_id 发给对接人。
AUTH_BAD_CREDENTIALS	凭证不对	渠道方式：核对 client_id 和 client_secret（口令只在发放时显示一次，丢了找管理员重发）。OMS 账号方式（grant_type=password）：核对 OMS 网站的登录账号和密码。想先试可以用 sandbox / sandbox。
AUTH_LOCKED	登录失败次数过多，已临时锁定	同一 OMS 账号连续输错密码会锁 15 分钟。确认账号密码后再试；想先试可以用 sandbox / sandbox。
DUPLICATE_SUSPECTED	疑似重复的代发单	同一收件人 + 同一 SKU 短时间内重复提交会被上游判重。确认要下就换一个 client_order_number，或稍后再试。
OMS_LOGIN_REQUIRED	这个接口要用 OMS 账号登录	用 POST /api/v1/auth/token 带 grant_type=password + OMS 账号密码换 token（渠道号 + 口令换的 token 用不了下单链，因为配货规则跟着 OMS 账号走）。
SHIPPING_REQUIRED	缺物流信息	下批发单要指定发货方式：GET /api/v1/shipping-methods 挑一个 shipping_method_id 传进 shipping；送货的再从 GET /api/v1/addresses 挑一个 address_id。也可以在 OMS 网站「用户 → 偏好设置」里设默认值。

参考资料

数据模型

这门生意的领域模型：实体、字段、关系。只列对外可见的字段。机器读的 JSON-LD 在 /ontology。

关系

Product	hasMany	Sku	一款含多个色码 / 尺码变体
Sku	hasStockIn	Warehouse	SKU 在各仓有库存（Stock）
Stock	refersTo	Sku	库存记录对应一个 SKU
Stock	belongsTo	Warehouse	库存行自带 warehouse_code
Channel	hasAccessTo	Warehouse	渠道可访问的仓（仓白名单）
Channel	hasPriceFor	Product	渠道对款的专属价（Price）
Order	belongsTo	Channel	订单归属渠道（归属校验）
DropshipOrder	belongsTo	Channel	代发单归属渠道
Shipment	belongsTo	Channel	发货单归属渠道
Shipment	belongsTo	Order	发货单来自批发订单（order_id）
StockReservation	belongsTo	Order	锁单来自批发订单（order_id）；订单审核后生成锁单，发货后生成发货单
StockReservation	belongsTo	Channel	锁单归属渠道
Cart	belongsTo	Channel	购物车（经 account）归属渠道
Transaction	belongsTo	Channel	一笔流水记在某个渠道的账上
Transaction	refersTo	Order	流水多半挂着一张订货单（order_id）与一张配单（reservation_id）

Product 产品（款）

一个款号，含多个色码 / 尺码变体（SKU）。

字段	类型	说明
product_code	string	款号
product_name	string	英文品名
product_name_zh	string	中文品名（有值才出；目前上游未接）
brand	string	品牌
price_wholesale	number	批发价
price_retail	number	零售价
currency	string	币种（AUD / CNY）
weight_grams	integer	克重（有值才出；目前上游未接）
image_urls	array	产品图片 URL 列表
description	string	规格描述
skus	array	这一款的全部变体（Sku）

Sku SKU（条码 / 变体）

一个具体条码 = 款 × 颜色 × 尺码。

字段	类型	说明
sku	string	SKU / 条码
product_code	string	所属款号
color_code	string	色码
color_name	string	颜色名
color_name_zh	string	颜色中文名（有值才出；目前上游未接）
size	string	尺码

Warehouse 仓库

库存所在的仓。warehouse_code 是唯一标识，路径、参数、响应里都叫它：AU = 澳洲（全部仓合计）（合计视图）；AUSYD2 = 悉尼主仓（Rosehill）；AUSYD1 = 悉尼配件仓；CN = 中国（全部仓合计）（合计视图）；CHNZJ1 = 中国镇江仓

字段	类型	说明
warehouse_code	string	仓库编码：AU / AUSYD2 / AUSYD1 / CN / CHNZJ1
name	string	仓库名（英文）
name_zh	string	仓库名（中文）
country	string	国家（AU / CN）
company_code	string	所属公司编码（100003 澳洲 / 500001 中国）
type	string	group = 公司级合计视图；physical = 真实仓
can_ship	boolean	能否从该仓直接发货
currency	string	币种

Stock 库存

某 SKU 在某仓的实时库存（含价格快照）。整仓、按款、按 SKU、增量口返回的都是它。

字段	类型	说明
warehouse_code	string	所在仓（每行自带）
sku	string	SKU
product_code	string	款号
product_name	string	品名
color_code	string	色码
color_name	string	颜色
size	string	尺码
brand	string	品牌
quantity_on_hand	integer	在库数量
quantity_available	integer	可用数量（在库 − 已锁）
price_wholesale	number	批发价
price_retail	number	零售价
currency	string	币种
expected_arrival_date	string	预计到货日（有在途才出）
quantity_incoming	integer	在途数量（有在途才出）

Channel 渠道（客户）

批发客户。token 里带渠道号；能调什么由角色和仓白名单决定。

字段	类型	说明
channel_code	string	渠道号（客户身份）
region	string	默认区域 au / cn
roles	array	角色（reader / trader / full）

Price 渠道价

某渠道对某款的价格（按渠道算，不是库存里那个统一价）。

字段	类型	说明
warehouse_code	string	仓
channel_code	string	渠道
product_code	string	款号
price_wholesale	number	本渠道批发价
price_retail	number	零售价
price_settlement	number	结算价

Order 批发订单

批发下单 / 查单，归属某渠道。下单发什么、查单拿回什么，同一个形状。

字段	类型	说明
order_id	string	订单号
warehouse_code	string	仓
lines	array	明细 [{sku, quantity}]
status	string	状态：draft 未审核 / confirmed 已审核 / cancelled 作废
status_raw	integer	状态原值
created_date	string	单据日期
note	string	备注
channel_code	string	归属渠道（归属校验用：只能看到自己的）

DropshipOrder 代发订单

代发下单 / 查单，归属某渠道，带收件人。一张代发单只有一个 SKU。

字段	类型	说明
dropship_order_id	string	代发订单号
serial_number	string	流水号
client_order_number	string	客户自己的单号
warehouse_code	string	仓
sku	string	SKU
quantity	integer	件数
quantity_allocated	integer	已配货
quantity_shipped	integer	已发货
recipient	object	收件人 {name, phone, address, country_code, state, city, postal_code}
sender	object	发件人 {name, phone}
shipping_method	string	运输方式 normal / express
carrier	string	承运商
tracking_number	string	运单号
shipped	boolean	是否已发货
shipped_date	string	发货日期
status	string	状态：pending 新建未配货 / shipped 已发货 / intercepted 已拦截 / cancelled 已取消
status_raw	integer	状态原值
paid	boolean	是否已付款
price_settlement	number	结算价
amount_shipping	number	运费
channel_code	string	归属渠道（归属校验用：只能看到自己的）

Shipment 发货单

发货单，归属某渠道；物流轨迹挂在它下面。

字段	类型	说明
shipment_id	string	发货单号
order_id	string	来源批发订单号
reservation_id	string	来源锁单号
warehouse_code	string	仓
status	string	状态：shipped 已发货
tracking_number	string	运单号
lines	array	明细
channel_code	string	归属渠道（归属校验用：只能看到自己的）

StockReservation 锁单 / 预留库存

渠道锁定的库存，归属某渠道。

字段	类型	说明
reservation_id	string	锁单号
order_id	string	来源批发订单号
warehouse_code	string	仓
status	string	状态：reserved 锁定中 / cancelled 已作废 / confirmed 已审核
shipped	boolean	是否已发货
lines	array	明细 [{sku, quantity}]
channel_code	string	归属渠道（归属校验用：只能看到自己的）

Cart 购物车

按 OMS 账号的购物车（账号归属某渠道）。

字段	类型	说明
account	string	OMS 账号
lines	array	明细 [{sku, quantity}]
channel_code	string	归属渠道（归属校验用：只能看到自己的）

Transaction 账户流水

渠道账户的一笔资金变动：充值 / 扣款 / 退款。余额是它们的累计结果。

字段	类型	说明
transaction_id	string	流水号（14 位纯数字，与代发流水号同形——认号要给候选）
transaction_type	string	类型：recharge 充值 / payment 支付 / refund 退款
amount	number	金额（正负号按类型）
currency	string	币种
balance_after	number	这一笔之后的余额——余额链首尾可验算
order_id	string	关联的订货单号（有才出）
reservation_id	string	关联的配单号（有才出）
created_at	string	上游处理时间（不是业务发生时间：补录会落在补录那天）
channel_code	string	归属渠道（归属校验用：只能看到自己的）

参考资料

接入你的 AI（MCP）

你的 AI（Claude Desktop、Cursor 或自己写的 agent）用你的 token 直连网关，工具清单按你的权限裁剪——接进 AI 不会让权限变大。

远程 MCP

在 MCP 客户端的配置里加一个服务器：URL 是本站的 /mcp，头里带你的 token。

用渠道号 + 口令换一个 token（POST /api/v1/auth/token）。
把右边的 JSON 贴进客户端配置，替换 token。
连上后工具清单自动出现：能调什么取决于你的角色和仓白名单。

会敲命令的 AI：用 CLI

Claude Code、Cursor 这类编程助手本来就活在终端里：装上 ever 就能自己查库存、读文档，不用配 MCP。工具名和 MCP 一模一样（都来自能力目录）。

curl -fsSL https://connect.everugg.net.au/cli/install.sh | sh
ever login --sandbox
ever tools --json

文档本身也是给 AI 读的形状：每页有 Markdown，目录在 llms.txt · 命令行工具（CLI）

权限

每个连接都用调用方自己的 token：先解出是谁、有哪些 scope，再裁剪工具；每次调用仍走网关（认证 + 授权 + 仓白名单 + 限流照常）。写操作永不自动执行。

A2A（agent 对 agent）

对端 agent 可以按 A2A 协议直接对话： POST https://connect.everugg.net.au/a2a · agent-card.json