{"openapi":"3.0.3","info":{"title":"Ever API","description":"批发渠道接口。**[← 返回开发者门户](/)** · [快速上手](/start) · [错误码](/errors) · [数据模型](/ontology) · [接进你自己的 AI（MCP）](/agents)\n\n> 这一页只列**你的程序要调的业务接口**。注册 webhook、申请套餐、看自己的权限，都在[门户](/portal/me)上点——不用写代码。\n\n当前契约版本 1.4.0（每个响应的 `X-API-Version` 头里也有）。承诺：**只加字段、不删字段、不改已有字段的含义**——这类改动不升版本，你的代码不用动。真要做会让现有代码出错的改动，会升主版本并开 `/v2/` 前缀，旧版至少并行 6 个月。\n\n先用 `POST /api/v1/auth/token`（请求体 `{\"client_id\":\"…\",\"client_secret\":\"…\"}`；没凭证可用沙箱 `sandbox` / `sandbox`）换 token，再点右上角 Authorize 填进去。写接口请带 `Idempotency-Key` 头防重复提交。","version":"1.4.0"},"tags":[{"name":"认证","description":"换取访问令牌。除仓库清单外，所有接口都要带它。"},{"name":"仓库与库存","description":"仓库主数据与库存。**日常同步请用 /stock/changes 增量口**，别每次拉整仓（7.2MB vs 几百字节）。"},{"name":"产品","description":"产品主数据：品名、图片、描述、变体。**不含库存数量**——那在库存里。"},{"name":"价格","description":"你这个渠道的专属价格。"},{"name":"批发订单","description":"批发下单与查单。下单**默认只建草稿**，需要人在 ERP 确认。"},{"name":"代发订单","description":"代发（一件代发）下单与查单，带收件人。"},{"name":"发货与物流","description":"发货单查询：货发了没有、发了什么；物流轨迹与清关证件（⚠️ 默认关闭，需申请开通）。"},{"name":"锁单","description":"渠道锁单 / 预留库存。"},{"name":"对账","description":"对账：余额、交易流水、月账单、退款单、运费单。只读，只对用 OMS 账号登录的 token 开放。"},{"name":"购物车","description":"OMS 网站的购物车，按登录账号读写。系统对接一般不需要经过它——可以直接下单。"},{"name":"Feeds","description":""}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{}},"paths":{"/api/v1/auth/token":{"post":{"parameters":[],"operationId":"postApiV1AuthToken","summary":"换取访问令牌：client_credentials（client_id = 渠道号，client_secret = 口令）或 password（username = OMS 登录账号，password = OMS 密码）→ Bearer access_token","tags":["认证"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"grant_type":{"anyOf":[{"const":"client_credentials","type":"string"},{"const":"password","type":"string"}],"description":"OAuth2 授权类型：client_credentials（渠道号 + 口令）或 password（OMS 账号 + 密码）。可省略：给了 username 就按 password 处理，否则按 client_credentials。"},"client_id":{"minLength":1,"maxLength":32,"pattern":"^[A-Za-z0-9_-]+$","type":"string","description":"渠道号（OAuth2 的 client_id），由对接人发放；client_credentials 方式用。想先试可以用 sandbox。"},"client_secret":{"minLength":1,"maxLength":256,"type":"string","description":"渠道口令（OAuth2 的 client_secret）；client_credentials 方式用。想先试可以用 sandbox（沙箱返回演示数据，不碰真库存）。"},"username":{"minLength":1,"maxLength":64,"type":"string","description":"OMS 网站的登录账号（password 方式用），比如 100470admin；建议给系统对接单独建一个子账号。想先试可以用 sandbox。"},"password":{"minLength":1,"maxLength":256,"type":"string","description":"OMS 登录密码（password 方式用）。只在换 token 那一刻经手，网关不保存、不记日志。想先试可以用 sandbox。"}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"grant_type":{"anyOf":[{"const":"client_credentials","type":"string"},{"const":"password","type":"string"}]},"client_id":{"minLength":1,"maxLength":32,"pattern":"^[A-Za-z0-9_-]+$","type":"string"},"client_secret":{"minLength":1,"maxLength":256,"type":"string"},"username":{"minLength":1,"maxLength":64,"type":"string"},"password":{"minLength":1,"maxLength":256,"type":"string"}}}},"text/plain":{"schema":{"type":"object","properties":{"grant_type":{"anyOf":[{"const":"client_credentials","type":"string"},{"const":"password","type":"string"}]},"client_id":{"minLength":1,"maxLength":32,"pattern":"^[A-Za-z0-9_-]+$","type":"string"},"client_secret":{"minLength":1,"maxLength":256,"type":"string"},"username":{"minLength":1,"maxLength":64,"type":"string"},"password":{"minLength":1,"maxLength":256,"type":"string"}}}}}},"responses":{"200":{}}}},"/api/v1/me":{"get":{"operationId":"getApiV1Me","summary":"当前 token 的身份：账号、渠道、能用的仓、权限、业务开关（OMS 账号登录的给 OMS 档案；渠道口令的给仓白名单与网关 scope）","tags":["认证"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/shipping-methods":{"get":{"operationId":"getApiV1Shipping-methods","summary":"你这个账号可用的发货方式（自取 / 自送 / 快递…）。下批发单时把 shipping_method_id 填进 shipping","tags":["批发订单"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/carriers":{"get":{"operationId":"getApiV1Carriers","summary":"你这个账号可选的物流公司。下批发单时把 carrier_id 填进 shipping（选填）","tags":["批发订单"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/addresses":{"get":{"operationId":"getApiV1Addresses","summary":"你在 OMS 里存的收货地址簿。下批发单时把 address_id 填进 shipping；地址簿在 OMS 网站「用户 → 偏好设置 → 批发收货地址」里维护","tags":["批发订单"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/balances":{"get":{"operationId":"getApiV1Balances","summary":"你的账户余额（澳洲 / 中国 / 新西兰，开了哪个给哪个）","tags":["对账"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/transactions":{"get":{"parameters":[{"schema":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"in":"query","name":"start_date","required":false,"description":"起始日期，格式 YYYY-MM-DD（含）。"},{"schema":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"in":"query","name":"end_date","required":false,"description":"截止日期，格式 YYYY-MM-DD（含）。"},{"schema":{"anyOf":[{"const":"recharge","type":"string"},{"const":"payment","type":"string"},{"const":"refund","type":"string"}]},"in":"query","name":"type","required":false,"description":"只看某一类交易流水（选填）：recharge 充值 / payment 扣款 / refund 退款。不传 = 全部。"},{"schema":{"minimum":1,"anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":1,"type":"number"}]},"in":"query","name":"page","required":false,"description":"页码，从 1 开始（选填）。整仓库存不传则返回全量——有三万多行，建议分页。"},{"schema":{"minimum":1,"maximum":2000,"anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":1,"maximum":2000,"type":"number"}]},"in":"query","name":"page_size","required":false,"description":"每页条数（选填），最大 2000。"}],"operationId":"getApiV1Transactions","summary":"交易流水（充值 / 扣款 / 退款），带每笔之后的账户余额；amount_total 是这批的合计。对账主表","tags":["对账"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/bills":{"get":{"parameters":[{"schema":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"in":"query","name":"start_date","required":false,"description":"起始日期，格式 YYYY-MM-DD（含）。"},{"schema":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"in":"query","name":"end_date","required":false,"description":"截止日期，格式 YYYY-MM-DD（含）。"},{"schema":{"minimum":1,"anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":1,"type":"number"}]},"in":"query","name":"page","required":false,"description":"页码，从 1 开始（选填）。整仓库存不传则返回全量——有三万多行，建议分页。"},{"schema":{"minimum":1,"maximum":2000,"anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":1,"maximum":2000,"type":"number"}]},"in":"query","name":"page_size","required":false,"description":"每页条数（选填），最大 2000。"}],"operationId":"getApiV1Bills","summary":"月度账单（按仓、按月，含是否已付）","tags":["对账"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/refunds":{"get":{"parameters":[{"schema":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"in":"query","name":"start_date","required":false,"description":"起始日期，格式 YYYY-MM-DD（含）。"},{"schema":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"in":"query","name":"end_date","required":false,"description":"截止日期，格式 YYYY-MM-DD（含）。"},{"schema":{"minimum":1,"anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":1,"type":"number"}]},"in":"query","name":"page","required":false,"description":"页码，从 1 开始（选填）。整仓库存不传则返回全量——有三万多行，建议分页。"},{"schema":{"minimum":1,"maximum":2000,"anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":1,"maximum":2000,"type":"number"}]},"in":"query","name":"page_size","required":false,"description":"每页条数（选填），最大 2000。"}],"operationId":"getApiV1Refunds","summary":"退款单（批发 / 代发，含审核状态与原因）","tags":["对账"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/freight-bills":{"get":{"parameters":[{"schema":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"in":"query","name":"start_date","required":false,"description":"起始日期，格式 YYYY-MM-DD（含）。"},{"schema":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"in":"query","name":"end_date","required":false,"description":"截止日期，格式 YYYY-MM-DD（含）。"},{"schema":{"minimum":1,"anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":1,"type":"number"}]},"in":"query","name":"page","required":false,"description":"页码，从 1 开始（选填）。整仓库存不传则返回全量——有三万多行，建议分页。"},{"schema":{"minimum":1,"maximum":2000,"anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":1,"maximum":2000,"type":"number"}]},"in":"query","name":"page_size","required":false,"description":"每页条数（选填），最大 2000。"}],"operationId":"getApiV1Freight-bills","summary":"运费单（承运商、运单号、箱数、金额）","tags":["对账"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/warehouses":{"get":{"operationId":"getApiV1Warehouses","summary":"仓库清单：仓码、名称、国家、所属公司、合计视图 / 实体仓、能否发货、币种","tags":["仓库与库存"],"responses":{"200":{}}}},"/api/v1/warehouses/{warehouse_code}/stock":{"get":{"parameters":[{"schema":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}]},"in":"path","name":"warehouse_code","required":true,"description":"仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。"},{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_./-]+$"},"in":"query","name":"sku","required":false,"description":"SKU / 条码——**具体到颜色和尺码**的那一层，如 OB0021611。查整个款请改用 product_code。"},{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_./-]+$"},"in":"query","name":"product_code","required":false,"description":"款号——**一个款**（含全部色码 / 尺码变体），如 OB002。查单个变体请改用 sku。查价格时可用逗号分隔多个。"},{"schema":{"minimum":1,"anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":1,"type":"number"}]},"in":"query","name":"page","required":false,"description":"页码，从 1 开始（选填）。整仓库存不传则返回全量——有三万多行，建议分页。"},{"schema":{"minimum":1,"maximum":2000,"anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":1,"maximum":2000,"type":"number"}]},"in":"query","name":"page_size","required":false,"description":"每页条数（选填），最大 2000。"}],"operationId":"getApiV1WarehousesByWarehouse_codeStock","summary":"某仓库存：不带筛选 = 整仓（可 page / page_size 分页，响应头 X-Stock-Version 给增量同步用）；sku= 一个变体；product_code= 一款全部变体。OMS 账号登录时按款 / 按 SKU 走 OMS 实时库存（现货 + 预售批次）","tags":["仓库与库存"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/warehouses/{warehouse_code}/stock/changes":{"get":{"parameters":[{"schema":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}]},"in":"path","name":"warehouse_code","required":true,"description":"仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。"},{"schema":{"minimum":0,"anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":0,"type":"number"}]},"in":"query","name":"since","required":false,"description":"上次拿到的 version。首次同步传 0（会返回 needs_full_sync=true，表示要先拉一次全量）。"},{"schema":{"minimum":1,"maximum":5000,"anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":1,"maximum":5000,"type":"number"}]},"in":"query","name":"limit","required":false,"description":"本次最多返回多少条变更（选填，默认 1000、最大 5000）。**是软上限**：同一个 version 的变更不会被拆开，所以实际可能略多于这个数。"}],"operationId":"getApiV1WarehousesByWarehouse_codeStockChanges","summary":"库存变更（增量）。传 since=上次拿到的 version；has_more=true 就带着新 version 再调一次，直到 false。needs_full_sync=true 表示 since 太旧，需重做一次全量","tags":["仓库与库存"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/products":{"get":{"parameters":[{"schema":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}]},"in":"query","name":"warehouse_code","required":true,"description":"仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。"},{"schema":{"type":"string","maxLength":128},"in":"query","name":"search","required":false,"description":"搜索关键词（选填），按款号或品名模糊匹配。"},{"schema":{"anyOf":[{"const":"wholesale","type":"string"},{"const":"dropship","type":"string"}]},"in":"query","name":"business_type","required":false,"description":"业务类型（选填）：wholesale 批发 / dropship 代发。不传 = 全部。"},{"schema":{"minimum":1,"anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":1,"type":"number"}]},"in":"query","name":"page","required":false,"description":"页码，从 1 开始（选填）。整仓库存不传则返回全量——有三万多行，建议分页。"},{"schema":{"minimum":1,"maximum":2000,"anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":1,"maximum":2000,"type":"number"}]},"in":"query","name":"page_size","required":false,"description":"每页条数（选填），最大 2000。"}],"operationId":"getApiV1Products","summary":"某仓产品列表（按款号去重，含价格；search 按款号 / 品名搜）。OMS 账号登录时按你的渠道价与禁售规则返回，和网页一致","tags":["产品"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/products/{product_code}":{"get":{"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_./-]+$"},"in":"path","name":"product_code","required":true,"description":"款号——**一个款**（含全部色码 / 尺码变体），如 OB002。查单个变体请改用 sku。查价格时可用逗号分隔多个。"},{"schema":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}]},"in":"query","name":"warehouse_code","required":false,"description":"仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。"}],"operationId":"getApiV1ProductsByProduct_code","summary":"款号查产品详情（图片 / 描述 / 价格 + 全部变体 skus）。OMS 账号登录时含结算价、最低限价、可买组合（available）、现货与预售批次","tags":["产品"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/skus/{sku}":{"get":{"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_./-]+$"},"in":"path","name":"sku","required":true,"description":"SKU / 条码——**具体到颜色和尺码**的那一层，如 OB0021611。查整个款请改用 product_code。"},{"schema":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}]},"in":"query","name":"warehouse_code","required":false,"description":"仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。"}],"operationId":"getApiV1SkusBySku","summary":"SKU 查变体详情（单对象）","tags":["产品"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/dropship-products":{"get":{"parameters":[{"schema":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}]},"in":"query","name":"warehouse_code","required":true,"description":"仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。"},{"schema":{"type":"string","maxLength":128},"in":"query","name":"search","required":false,"description":"搜索关键词（选填），按款号或品名模糊匹配。"},{"schema":{"anyOf":[{"const":"wholesale","type":"string"},{"const":"dropship","type":"string"}]},"in":"query","name":"business_type","required":false,"description":"业务类型（选填）：wholesale 批发 / dropship 代发。不传 = 全部。"},{"schema":{"minimum":1,"anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":1,"type":"number"}]},"in":"query","name":"page","required":false,"description":"页码，从 1 开始（选填）。整仓库存不传则返回全量——有三万多行，建议分页。"},{"schema":{"minimum":1,"maximum":2000,"anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":1,"maximum":2000,"type":"number"}]},"in":"query","name":"page_size","required":false,"description":"每页条数（选填），最大 2000。"}],"operationId":"getApiV1Dropship-products","summary":"代发系统在售产品列表（分页）","tags":["产品"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/prices":{"get":{"parameters":[{"schema":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}]},"in":"query","name":"warehouse_code","required":true,"description":"仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。"},{"schema":{"type":"string","maxLength":4096},"in":"query","name":"product_code","required":false,"description":"款号——**一个款**（含全部色码 / 尺码变体），如 OB002。查单个变体请改用 sku。查价格时可用逗号分隔多个。"},{"schema":{"type":"string","maxLength":128},"in":"query","name":"search","required":false,"description":"搜索关键词（选填），按款号或品名模糊匹配。"},{"schema":{"minimum":1,"anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":1,"type":"number"}]},"in":"query","name":"page","required":false,"description":"页码，从 1 开始（选填）。整仓库存不传则返回全量——有三万多行，建议分页。"},{"schema":{"minimum":1,"maximum":2000,"anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":1,"maximum":2000,"type":"number"}]},"in":"query","name":"page_size","required":false,"description":"每页条数（选填），最大 2000。"}],"operationId":"getApiV1Prices","summary":"本渠道的产品价格（分页；product_code 可逗号分隔多个）。OMS 账号登录时给结算价 / 吊牌价 / 调价前结算价（和网页一致）","tags":["价格"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/orders":{"post":{"parameters":[],"operationId":"postApiV1Orders","summary":"创建批发订单（默认只建草稿，auto_confirm=true 才提交审核）。OMS 账号登录时要有物流信息：shipping 里给 shipping_method_id（见 /shipping-methods）＋ address_id（见 /addresses）；不传则用你 OMS 账号里的默认设置","tags":["批发订单"],"security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["warehouse_code","lines"],"properties":{"warehouse_code":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}],"description":"仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。"},"lines":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","required":["sku","quantity"],"properties":{"sku":{"minLength":1,"maxLength":64,"type":"string","description":"SKU / 条码——**具体到颜色和尺码**的那一层，如 OB0021611。查整个款请改用 product_code。"},"quantity":{"minimum":0,"maximum":99999,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"maximum":99999,"type":"integer"}],"description":"件数，正整数，如 2。锁单调整 / 购物车里传 0 表示去掉这一行。"}}},"description":"明细数组，每项 { sku, quantity }。至少一项；quantity=0 在调整锁单 / 购物车时表示去掉这一行。"},"note":{"maxLength":500,"type":"string","description":"备注（选填，最长 500 字）。"},"client_order_number":{"maxLength":64,"type":"string","description":"你自己系统里的订单号（下代发单时传的那个）。"},"auto_confirm":{"type":"boolean","description":"是否直接提交（选填）。**不传 = 只保存草稿**，需要人在 ERP 里确认后才生效——这是有意的默认。代发单提交后会立刻配货、无法再修改。"},"shipping":{"type":"object","properties":{"shipping_method_id":{"minLength":1,"maxLength":64,"type":"string","description":"发货方式编号，从 GET /api/v1/shipping-methods 取。"},"carrier_id":{"minLength":1,"maxLength":64,"type":"string","description":"物流公司编号（选填），从 GET /api/v1/carriers 取。"},"address_id":{"minLength":1,"maxLength":64,"type":"string","description":"收货地址编号，从 GET /api/v1/addresses 取。地址簿在 OMS 网站「用户 → 偏好设置 → 批发收货地址」里维护。"},"pickup_at":{"maxLength":32,"type":"string","description":"自取时间（选填，自取方式才用），如 2026-09-10T14:00:00。"}},"description":"物流信息（用 OMS 账号登录下批发单时必需）。里面：shipping_method_id（发货方式，见 GET /api/v1/shipping-methods）、address_id（收货地址，见 GET /api/v1/addresses）、carrier_id（物流公司，选填）、pickup_at（自取时间，自取方式才填）。整个不传则用你 OMS 账号里的默认设置；默认也没设会报错并指路。"}}}},"multipart/form-data":{"schema":{"type":"object","required":["warehouse_code","lines"],"properties":{"warehouse_code":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}]},"lines":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","required":["sku","quantity"],"properties":{"sku":{"minLength":1,"maxLength":64,"type":"string"},"quantity":{"minimum":0,"maximum":99999,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"maximum":99999,"type":"integer"}]}}}},"note":{"maxLength":500,"type":"string"},"client_order_number":{"maxLength":64,"type":"string"},"auto_confirm":{"type":"boolean"},"shipping":{"type":"object","properties":{"shipping_method_id":{"minLength":1,"maxLength":64,"type":"string"},"carrier_id":{"minLength":1,"maxLength":64,"type":"string"},"address_id":{"minLength":1,"maxLength":64,"type":"string"},"pickup_at":{"maxLength":32,"type":"string"}}}}}},"text/plain":{"schema":{"type":"object","required":["warehouse_code","lines"],"properties":{"warehouse_code":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}]},"lines":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","required":["sku","quantity"],"properties":{"sku":{"minLength":1,"maxLength":64,"type":"string"},"quantity":{"minimum":0,"maximum":99999,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"maximum":99999,"type":"integer"}]}}}},"note":{"maxLength":500,"type":"string"},"client_order_number":{"maxLength":64,"type":"string"},"auto_confirm":{"type":"boolean"},"shipping":{"type":"object","properties":{"shipping_method_id":{"minLength":1,"maxLength":64,"type":"string"},"carrier_id":{"minLength":1,"maxLength":64,"type":"string"},"address_id":{"minLength":1,"maxLength":64,"type":"string"},"pickup_at":{"maxLength":32,"type":"string"}}}}}}}},"responses":{"200":{}}},"get":{"parameters":[{"description":"你自己那边的单号（下单时传过的）——对账时拿它找回我们这边的单","schema":{"type":"string","maxLength":64},"in":"query","name":"client_order_number","required":false},{"schema":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"in":"query","name":"start_date","required":true,"description":"起始日期，格式 YYYY-MM-DD（含）。"},{"schema":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"in":"query","name":"end_date","required":true,"description":"截止日期，格式 YYYY-MM-DD（含）。"},{"description":"逗号分隔：draft / confirmed / cancelled","schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9,\\s_-]*$"},"in":"query","name":"status","required":false}],"operationId":"getApiV1Orders","summary":"按日期区间查本渠道批发订单；可再按 client_order_number 收窄","tags":["批发订单"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/orders/{order_id}":{"get":{"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"order_id","required":true,"description":"批发订单号，从订单列表拿到。只能查本渠道自己的单。"}],"operationId":"getApiV1OrdersByOrder_id","summary":"批发订单详情（带归属校验）","tags":["批发订单"],"security":[{"bearer":[]}],"responses":{"200":{}}},"delete":{"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"order_id","required":true,"description":"批发订单号，从订单列表拿到。只能查本渠道自己的单。"}],"operationId":"deleteApiV1OrdersByOrder_id","summary":"作废批发订单（连同它占住的配货一起释放）。已发货的作废不了","tags":["批发订单"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/orders/{order_id}/allocation-preview":{"post":{"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"order_id","required":true,"description":"批发订单号，从订单列表拿到。只能查本渠道自己的单。"}],"operationId":"postApiV1OrdersByOrder_idAllocation-preview","summary":"配货预览：逐行给出能配多少 / 欠多少 / 预售几时到货，以及应付金额与余额是否够。⚠️ 预览会占住库存——看完要么提交，要么取消订单","tags":["批发订单"],"security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"use_reservation":{"type":"boolean","description":"是否动用你的锁单（预留库存）来配这批货。不传 = 不动用。"}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"use_reservation":{"type":"boolean"}}}},"text/plain":{"schema":{"type":"object","properties":{"use_reservation":{"type":"boolean"}}}}}},"responses":{"200":{}}}},"/api/v1/orders/{order_id}/submit":{"post":{"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"order_id","required":true,"description":"批发订单号，从订单列表拿到。只能查本渠道自己的单。"}],"operationId":"postApiV1OrdersByOrder_idSubmit","summary":"提交批发订单（提交后不能再改明细）。payment_method 默认 invoice（按发票付款）","tags":["批发订单"],"security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"payment_method":{"anyOf":[{"const":"balance","type":"string"},{"const":"wechat","type":"string"},{"const":"alipay","type":"string"},{"const":"invoice","type":"string"}],"description":"付款方式：balance 余额 / invoice 按发票付款 / wechat 微信 / alipay 支付宝。不传默认 invoice（按发票付款，也就是月结）。"},"use_reservation":{"type":"boolean","description":"是否动用你的锁单（预留库存）来配这批货。不传 = 不动用。"}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"payment_method":{"anyOf":[{"const":"balance","type":"string"},{"const":"wechat","type":"string"},{"const":"alipay","type":"string"},{"const":"invoice","type":"string"}]},"use_reservation":{"type":"boolean"}}}},"text/plain":{"schema":{"type":"object","properties":{"payment_method":{"anyOf":[{"const":"balance","type":"string"},{"const":"wechat","type":"string"},{"const":"alipay","type":"string"},{"const":"invoice","type":"string"}]},"use_reservation":{"type":"boolean"}}}}}},"responses":{"200":{}}}},"/api/v1/feeds/products":{"get":{"parameters":[{"schema":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}]},"in":"query","name":"warehouse_code","required":true,"description":"仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。"},{"description":"csv（默认）/ xml / json","schema":{"type":"string","maxLength":8},"in":"query","name":"format","required":false},{"description":"你站上的商品页地址模板，里面用 {product_code} 或 {sku} 占位，我们替你拼。**不给就不出 link**，而 link 是必填项","schema":{"type":"string","maxLength":300},"in":"query","name":"link_template","required":false},{"description":"图片链接的绝对前缀。不给用服务端配置。**必须走加密链接（TLS）**，明文图片链接各平台基本都会拒","schema":{"type":"string","maxLength":200},"in":"query","name":"image_base","required":false},{"description":"强制重拼。**不会再给你旧的那份** —— 回 202，拼好了再来取","schema":{"type":"boolean"},"in":"query","name":"rebuild","required":false}],"operationId":"getApiV1FeedsProducts","summary":"取商品 feed（Google Merchant 规格，同时就是批量导出）：有现成的先给你，旧了后台重拼；一次没拼过则回 202 并开始拼。响应头里带行数、有图数、扔掉了什么、会被平台挑什么毛病、以及这份拼于什么时候","tags":["Feeds"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/feeds/products/status":{"get":{"parameters":[{"schema":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}]},"in":"query","name":"warehouse_code","required":true,"description":"仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。"}],"operationId":"getApiV1FeedsProductsStatus","summary":"看 feed 拼到哪了：在拼 / 好了 / 失败（带原因），以及最新一份的行数与毛病","tags":["Feeds"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/feeds/{channel}/{file}":{"get":{"operationId":"getFeedsByChannelByFile","summary":"下载商品 feed（HTTP Basic；给 Google Merchant 这类定时抓取用）。带 ETag / Last-Modified / 构建时间","tags":["Feeds"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"channel","required":true},{"schema":{"type":"string"},"in":"path","name":"file","required":true}],"responses":{"200":{}}}},"/api/v1/dropship-orders":{"post":{"parameters":[],"operationId":"postApiV1Dropship-orders","summary":"创建代发订单：一单一个 SKU；收件人（澳新地址要 state / city / postal_code）；shipping normal / express；auto_confirm=true 才提交配货（提交后不能改）","tags":["代发订单"],"security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["warehouse_code","sku","quantity","recipient"],"properties":{"warehouse_code":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}],"description":"仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。"},"sku":{"minLength":1,"maxLength":64,"type":"string","description":"SKU / 条码——**具体到颜色和尺码**的那一层，如 OB0021611。查整个款请改用 product_code。"},"quantity":{"minimum":1,"maximum":99999,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":99999,"type":"integer"}],"description":"件数，正整数，如 2。锁单调整 / 购物车里传 0 表示去掉这一行。"},"recipient":{"type":"object","required":["name","phone","address","country_code"],"properties":{"name":{"minLength":1,"maxLength":128,"type":"string","description":"收件人姓名，写全名（快递面单上打印的就是它）。"},"phone":{"minLength":1,"maxLength":64,"type":"string","description":"收件人电话。跨境件请带国际区号（如 +61…），否则清关和派送可能联系不上。"},"address":{"minLength":1,"maxLength":512,"type":"string","description":"收件地址，请含门牌。地址不全是派送失败最常见的原因。"},"country_code":{"anyOf":[{"const":"AU","type":"string"},{"const":"CN","type":"string"},{"const":"NZ","type":"string"}],"description":"收件国家：AU 澳洲 / CN 中国 / NZ 新西兰（代发只支持这三国）。"},"state":{"maxLength":64,"type":"string","description":"州 / 省，如 NSW。寄澳洲、新西兰时必填。"},"city":{"maxLength":128,"type":"string","description":"城市，如 Sydney。寄澳洲、新西兰时必填。"},"postal_code":{"maxLength":16,"type":"string","description":"邮编，如 2000。寄澳洲、新西兰时必填。"}},"description":"收件人对象 { name, phone, address, country_code, state, city, postal_code }。country_code 用 AU / CN / NZ；寄澳洲、新西兰时 state / city / postal_code 必填。跨境件电话请带国际区号（如 +61…），地址请含门牌——地址不全是派送失败最常见的原因。"},"sender":{"type":"object","properties":{"name":{"maxLength":128,"type":"string","description":"收件人姓名，写全名（快递面单上打印的就是它）。"},"phone":{"maxLength":64,"type":"string","description":"收件人电话。跨境件请带国际区号（如 +61…），否则清关和派送可能联系不上。"}},"description":"发件人对象 { name, phone }（选填），印在面单上的寄件人。"},"shipping_method":{"anyOf":[{"const":"normal","type":"string"},{"const":"express","type":"string"},{"const":"ems","type":"string"}],"description":"运输方式：normal 普通（默认）/ express 特快 / ems 邮政EMS。"},"auto_confirm":{"type":"boolean","description":"是否直接提交（选填）。**不传 = 只保存草稿**，需要人在 ERP 里确认后才生效——这是有意的默认。代发单提交后会立刻配货、无法再修改。"},"client_order_number":{"maxLength":64,"type":"string","description":"你自己系统里的订单号（下代发单时传的那个）。"},"note":{"maxLength":500,"type":"string","description":"备注（选填，最长 500 字）。"}}}},"multipart/form-data":{"schema":{"type":"object","required":["warehouse_code","sku","quantity","recipient"],"properties":{"warehouse_code":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}]},"sku":{"minLength":1,"maxLength":64,"type":"string"},"quantity":{"minimum":1,"maximum":99999,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":99999,"type":"integer"}]},"recipient":{"type":"object","required":["name","phone","address","country_code"],"properties":{"name":{"minLength":1,"maxLength":128,"type":"string"},"phone":{"minLength":1,"maxLength":64,"type":"string"},"address":{"minLength":1,"maxLength":512,"type":"string"},"country_code":{"anyOf":[{"const":"AU","type":"string"},{"const":"CN","type":"string"},{"const":"NZ","type":"string"}]},"state":{"maxLength":64,"type":"string"},"city":{"maxLength":128,"type":"string"},"postal_code":{"maxLength":16,"type":"string"}}},"sender":{"type":"object","properties":{"name":{"maxLength":128,"type":"string"},"phone":{"maxLength":64,"type":"string"}}},"shipping_method":{"anyOf":[{"const":"normal","type":"string"},{"const":"express","type":"string"},{"const":"ems","type":"string"}]},"auto_confirm":{"type":"boolean"},"client_order_number":{"maxLength":64,"type":"string"},"note":{"maxLength":500,"type":"string"}}}},"text/plain":{"schema":{"type":"object","required":["warehouse_code","sku","quantity","recipient"],"properties":{"warehouse_code":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}]},"sku":{"minLength":1,"maxLength":64,"type":"string"},"quantity":{"minimum":1,"maximum":99999,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":99999,"type":"integer"}]},"recipient":{"type":"object","required":["name","phone","address","country_code"],"properties":{"name":{"minLength":1,"maxLength":128,"type":"string"},"phone":{"minLength":1,"maxLength":64,"type":"string"},"address":{"minLength":1,"maxLength":512,"type":"string"},"country_code":{"anyOf":[{"const":"AU","type":"string"},{"const":"CN","type":"string"},{"const":"NZ","type":"string"}]},"state":{"maxLength":64,"type":"string"},"city":{"maxLength":128,"type":"string"},"postal_code":{"maxLength":16,"type":"string"}}},"sender":{"type":"object","properties":{"name":{"maxLength":128,"type":"string"},"phone":{"maxLength":64,"type":"string"}}},"shipping_method":{"anyOf":[{"const":"normal","type":"string"},{"const":"express","type":"string"},{"const":"ems","type":"string"}]},"auto_confirm":{"type":"boolean"},"client_order_number":{"maxLength":64,"type":"string"},"note":{"maxLength":500,"type":"string"}}}}}},"responses":{"200":{}}},"get":{"parameters":[{"schema":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}]},"in":"query","name":"warehouse_code","required":false,"description":"仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。"},{"schema":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"in":"query","name":"start_date","required":false,"description":"起始日期，格式 YYYY-MM-DD（含）。"},{"schema":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"in":"query","name":"end_date","required":false,"description":"截止日期，格式 YYYY-MM-DD（含）。"},{"schema":{"anyOf":[{"type":"boolean"},{"format":"boolean","default":false,"type":"string"}]},"in":"query","name":"shipped","required":false,"description":"只看已发货（true）或未发货（false）的（选填）。"},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"query","name":"client_order_number","required":false,"description":"你自己系统里的订单号（下代发单时传的那个）。"},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"query","name":"serial_number","required":false,"description":"代发流水号，从代发订单列表的返回里拿。只能查本渠道自己的。"}],"operationId":"getApiV1Dropship-orders","summary":"代发订单列表：按仓 + 日期区间；或按 client_order_number / serial_number 直接找","tags":["代发订单"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/dropship-orders/summary":{"get":{"parameters":[{"schema":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}]},"in":"query","name":"warehouse_code","required":true,"description":"仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。"},{"schema":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"in":"query","name":"start_date","required":true,"description":"起始日期，格式 YYYY-MM-DD（含）。"},{"schema":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"in":"query","name":"end_date","required":true,"description":"截止日期，格式 YYYY-MM-DD（含）。"},{"schema":{"minimum":1,"anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":1,"type":"number"}]},"in":"query","name":"page","required":false,"description":"页码，从 1 开始（选填）。整仓库存不传则返回全量——有三万多行，建议分页。"},{"schema":{"minimum":1,"maximum":2000,"anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":1,"maximum":2000,"type":"number"}]},"in":"query","name":"page_size","required":false,"description":"每页条数（选填），最大 2000。"}],"operationId":"getApiV1Dropship-ordersSummary","summary":"代发订单汇总列表（分页）","tags":["代发订单"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/dropship-orders/{dropship_order_id}":{"get":{"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"dropship_order_id","required":true,"description":"代发订单号，从代发订单列表拿到。只能查本渠道自己的单。"}],"operationId":"getApiV1Dropship-ordersByDropship_order_id","summary":"代发订单详情（带归属校验）","tags":["代发订单"],"security":[{"bearer":[]}],"responses":{"200":{}}},"delete":{"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"dropship_order_id","required":true,"description":"代发订单号，从代发订单列表拿到。只能查本渠道自己的单。"}],"operationId":"deleteApiV1Dropship-ordersByDropship_order_id","summary":"作废代发明细（连同它占住的配货一起释放）。已发货的作废不了","tags":["代发订单"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/dropship-orders/allocation-preview":{"post":{"parameters":[],"operationId":"postApiV1Dropship-ordersAllocation-preview","summary":"代发预配：逐条给出能不能配齐、缺多少、预售几时到货、要付多少。⚠️ 预配会占住库存——看完要么提交，要么调 DELETE …/{dropship_order_id}/allocation 释放","tags":["代发订单"],"security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["warehouse_code","dropship_order_ids"],"properties":{"warehouse_code":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}],"description":"仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。"},"dropship_order_ids":{"minItems":1,"maxItems":200,"type":"array","items":{"minLength":1,"maxLength":64,"type":"string"},"description":"代发流水号数组（建代发时返回的 serial_number）。一次最多 200 条。"},"use_reservation":{"type":"boolean","description":"是否动用你的锁单（预留库存）来配这批货。不传 = 不动用。"}}}},"multipart/form-data":{"schema":{"type":"object","required":["warehouse_code","dropship_order_ids"],"properties":{"warehouse_code":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}]},"dropship_order_ids":{"minItems":1,"maxItems":200,"type":"array","items":{"minLength":1,"maxLength":64,"type":"string"}},"use_reservation":{"type":"boolean"}}}},"text/plain":{"schema":{"type":"object","required":["warehouse_code","dropship_order_ids"],"properties":{"warehouse_code":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}]},"dropship_order_ids":{"minItems":1,"maxItems":200,"type":"array","items":{"minLength":1,"maxLength":64,"type":"string"}},"use_reservation":{"type":"boolean"}}}}}},"responses":{"200":{}}}},"/api/v1/dropship-orders/submit":{"post":{"parameters":[],"operationId":"postApiV1Dropship-ordersSubmit","summary":"提交代发（提交后不能改）。建议先预配看缺货，再带上 preview_key 提交；payment_method 默认 invoice","tags":["代发订单"],"security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["warehouse_code","dropship_order_ids"],"properties":{"warehouse_code":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}],"description":"仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。"},"dropship_order_ids":{"minItems":1,"maxItems":200,"type":"array","items":{"minLength":1,"maxLength":64,"type":"string"},"description":"代发流水号数组（建代发时返回的 serial_number）。一次最多 200 条。"},"preview_key":{"maxLength":128,"type":"string","description":"上一步「配货预览」返回的 preview_key。带上它表示「就按那次预览的结果提交」；不带则提交时重新算一次。"},"payment_method":{"anyOf":[{"const":"balance","type":"string"},{"const":"wechat","type":"string"},{"const":"alipay","type":"string"},{"const":"invoice","type":"string"}],"description":"付款方式：balance 余额 / invoice 按发票付款 / wechat 微信 / alipay 支付宝。不传默认 invoice（按发票付款，也就是月结）。"},"use_reservation":{"type":"boolean","description":"是否动用你的锁单（预留库存）来配这批货。不传 = 不动用。"}}}},"multipart/form-data":{"schema":{"type":"object","required":["warehouse_code","dropship_order_ids"],"properties":{"warehouse_code":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}]},"dropship_order_ids":{"minItems":1,"maxItems":200,"type":"array","items":{"minLength":1,"maxLength":64,"type":"string"}},"preview_key":{"maxLength":128,"type":"string"},"payment_method":{"anyOf":[{"const":"balance","type":"string"},{"const":"wechat","type":"string"},{"const":"alipay","type":"string"},{"const":"invoice","type":"string"}]},"use_reservation":{"type":"boolean"}}}},"text/plain":{"schema":{"type":"object","required":["warehouse_code","dropship_order_ids"],"properties":{"warehouse_code":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}]},"dropship_order_ids":{"minItems":1,"maxItems":200,"type":"array","items":{"minLength":1,"maxLength":64,"type":"string"}},"preview_key":{"maxLength":128,"type":"string"},"payment_method":{"anyOf":[{"const":"balance","type":"string"},{"const":"wechat","type":"string"},{"const":"alipay","type":"string"},{"const":"invoice","type":"string"}]},"use_reservation":{"type":"boolean"}}}}}},"responses":{"200":{}}}},"/api/v1/dropship-orders/{dropship_order_id}/allocation":{"delete":{"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"dropship_order_id","required":true,"description":"代发订单号，从代发订单列表拿到。只能查本渠道自己的单。"}],"operationId":"deleteApiV1Dropship-ordersByDropship_order_idAllocation","summary":"释放这条代发明细占住的预配库存（预配之后决定不提交时用）","tags":["代发订单"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/shipments":{"get":{"parameters":[{"schema":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}]},"in":"query","name":"warehouse_code","required":true,"description":"仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。"},{"schema":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"in":"query","name":"start_date","required":false,"description":"起始日期，格式 YYYY-MM-DD（含）。"},{"schema":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"in":"query","name":"end_date","required":false,"description":"截止日期，格式 YYYY-MM-DD（含）。"}],"operationId":"getApiV1Shipments","summary":"本渠道发货单列表","tags":["发货与物流"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/shipments/identity-documents":{"post":{"parameters":[],"operationId":"postApiV1ShipmentsIdentity-documents","summary":"上传收件人证件影像 ⚠️ 终端消费者身份证正反面（PII）。默认关闭，需显式申请开通；只透传、不落日志、不进缓存","tags":["发货与物流"],"security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["front_image","back_image"],"properties":{"front_image":{"maxLength":8000000,"type":"string","description":"⚠️ 身份证正面影像（base64）。这是终端消费者的敏感个人信息，我们只透传、不落日志、不进缓存。此接口默认关闭，需显式申请。"},"back_image":{"maxLength":8000000,"type":"string","description":"⚠️ 身份证背面影像（base64）。同上。"},"shipment_ids":{"maxItems":100,"type":"array","items":{"minLength":1,"maxLength":64,"type":"string"},"description":"关联的发货单号数组（选填）。"},"recipient":{"type":"object","properties":{"name":{"maxLength":128,"type":"string","description":"收件人姓名，写全名（快递面单上打印的就是它）。"},"phone":{"maxLength":64,"type":"string","description":"收件人电话。跨境件请带国际区号（如 +61…），否则清关和派送可能联系不上。"}},"description":"收件人对象 { name, phone, address, country_code, state, city, postal_code }。country_code 用 AU / CN / NZ；寄澳洲、新西兰时 state / city / postal_code 必填。跨境件电话请带国际区号（如 +61…），地址请含门牌——地址不全是派送失败最常见的原因。"},"document_number":{"maxLength":64,"type":"string","description":"收件人证件号（选填），清关时核对用。"}}}},"multipart/form-data":{"schema":{"type":"object","required":["front_image","back_image"],"properties":{"front_image":{"maxLength":8000000,"type":"string"},"back_image":{"maxLength":8000000,"type":"string"},"shipment_ids":{"maxItems":100,"type":"array","items":{"minLength":1,"maxLength":64,"type":"string"}},"recipient":{"type":"object","properties":{"name":{"maxLength":128,"type":"string"},"phone":{"maxLength":64,"type":"string"}}},"document_number":{"maxLength":64,"type":"string"}}}},"text/plain":{"schema":{"type":"object","required":["front_image","back_image"],"properties":{"front_image":{"maxLength":8000000,"type":"string"},"back_image":{"maxLength":8000000,"type":"string"},"shipment_ids":{"maxItems":100,"type":"array","items":{"minLength":1,"maxLength":64,"type":"string"}},"recipient":{"type":"object","properties":{"name":{"maxLength":128,"type":"string"},"phone":{"maxLength":64,"type":"string"}}},"document_number":{"maxLength":64,"type":"string"}}}}}},"responses":{"200":{}}}},"/api/v1/shipments/{shipment_id}":{"get":{"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"shipment_id","required":true,"description":"发货单号（物流轨迹里也是它），从发货单列表拿到。只能查本渠道自己的单。"}],"operationId":"getApiV1ShipmentsByShipment_id","summary":"发货单详情（带归属校验）","tags":["发货与物流"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/shipments/{shipment_id}/tracking":{"get":{"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"shipment_id","required":true,"description":"发货单号（物流轨迹里也是它），从发货单列表拿到。只能查本渠道自己的单。"}],"operationId":"getApiV1ShipmentsByShipment_idTracking","summary":"物流轨迹（澳邮 Auexpress；默认关闭，需申请开通）","tags":["发货与物流"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/reservations":{"get":{"parameters":[{"schema":{"anyOf":[{"const":"AU","type":"string"},{"const":"AUSYD2","type":"string"},{"const":"AUSYD1","type":"string"},{"const":"CN","type":"string"},{"const":"CHNZJ1","type":"string"}]},"in":"query","name":"warehouse_code","required":true,"description":"仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。"},{"schema":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"in":"query","name":"start_date","required":false,"description":"起始日期，格式 YYYY-MM-DD（含）。"},{"schema":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"in":"query","name":"end_date","required":false,"description":"截止日期，格式 YYYY-MM-DD（含）。"},{"schema":{"anyOf":[{"const":"reserved","type":"string"},{"const":"cancelled","type":"string"}]},"in":"query","name":"status","required":false,"description":"状态过滤（选填），多个用逗号分隔。批发订单：draft 未审核 / confirmed 已审核 / cancelled 作废；锁单：reserved 锁定中 / cancelled 已作废。不传则不过滤（锁单默认 reserved + cancelled）。响应里 status 是同一套词，status_raw 是上游原值。"}],"operationId":"getApiV1Reservations","summary":"本渠道锁单 / 预留库存列表（默认 reserved + cancelled；status= 只看一种）","tags":["锁单"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/reservations/{reservation_id}":{"get":{"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"reservation_id","required":true,"description":"锁单单据号，从锁单列表拿到。只能查 / 改本渠道自己的单。"}],"operationId":"getApiV1ReservationsByReservation_id","summary":"锁单详情（带归属校验）","tags":["锁单"],"security":[{"bearer":[]}],"responses":{"200":{}}},"patch":{"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"reservation_id","required":true,"description":"锁单单据号，从锁单列表拿到。只能查 / 改本渠道自己的单。"}],"operationId":"patchApiV1ReservationsByReservation_id","summary":"调整锁单明细（写；带归属校验）","tags":["锁单"],"security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["lines"],"properties":{"lines":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","required":["sku","quantity"],"properties":{"sku":{"minLength":1,"maxLength":64,"type":"string","description":"SKU / 条码——**具体到颜色和尺码**的那一层，如 OB0021611。查整个款请改用 product_code。"},"quantity":{"minimum":0,"maximum":99999,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"maximum":99999,"type":"integer"}],"description":"件数，正整数，如 2。锁单调整 / 购物车里传 0 表示去掉这一行。"}}},"description":"明细数组，每项 { sku, quantity }。至少一项；quantity=0 在调整锁单 / 购物车时表示去掉这一行。"},"note":{"maxLength":500,"type":"string","description":"备注（选填，最长 500 字）。"}}}},"multipart/form-data":{"schema":{"type":"object","required":["lines"],"properties":{"lines":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","required":["sku","quantity"],"properties":{"sku":{"minLength":1,"maxLength":64,"type":"string"},"quantity":{"minimum":0,"maximum":99999,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"maximum":99999,"type":"integer"}]}}}},"note":{"maxLength":500,"type":"string"}}}},"text/plain":{"schema":{"type":"object","required":["lines"],"properties":{"lines":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","required":["sku","quantity"],"properties":{"sku":{"minLength":1,"maxLength":64,"type":"string"},"quantity":{"minimum":0,"maximum":99999,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"maximum":99999,"type":"integer"}]}}}},"note":{"maxLength":500,"type":"string"}}}}}},"responses":{"200":{}}}},"/api/v1/carts/{account}":{"get":{"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"account","required":true,"description":"购物车所属账号（OMS 网站的登录账号，如 100470admin）。"}],"operationId":"getApiV1CartsByAccount","summary":"查某账号购物车","tags":["购物车"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/carts/{account}/lines":{"put":{"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"account","required":true,"description":"购物车所属账号（OMS 网站的登录账号，如 100470admin）。"}],"operationId":"putApiV1CartsByAccountLines","summary":"添加 / 更新购物车条目（幂等）","tags":["购物车"],"security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["lines"],"properties":{"lines":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"object","required":["sku","quantity"],"properties":{"sku":{"minLength":1,"maxLength":64,"type":"string","description":"SKU / 条码——**具体到颜色和尺码**的那一层，如 OB0021611。查整个款请改用 product_code。"},"quantity":{"minimum":0,"maximum":99999,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"maximum":99999,"type":"integer"}],"description":"件数，正整数，如 2。锁单调整 / 购物车里传 0 表示去掉这一行。"}}},"description":"明细数组，每项 { sku, quantity }。至少一项；quantity=0 在调整锁单 / 购物车时表示去掉这一行。"}}}},"multipart/form-data":{"schema":{"type":"object","required":["lines"],"properties":{"lines":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"object","required":["sku","quantity"],"properties":{"sku":{"minLength":1,"maxLength":64,"type":"string"},"quantity":{"minimum":0,"maximum":99999,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"maximum":99999,"type":"integer"}]}}}}}}},"text/plain":{"schema":{"type":"object","required":["lines"],"properties":{"lines":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"object","required":["sku","quantity"],"properties":{"sku":{"minLength":1,"maxLength":64,"type":"string"},"quantity":{"minimum":0,"maximum":99999,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"maximum":99999,"type":"integer"}]}}}}}}}}},"responses":{"200":{}}}},"/api/v1/carts/{account}/lines/{sku}":{"delete":{"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"account","required":true,"description":"购物车所属账号（OMS 网站的登录账号，如 100470admin）。"},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"sku","required":true,"description":"SKU / 条码——**具体到颜色和尺码**的那一层，如 OB0021611。查整个款请改用 product_code。"}],"operationId":"deleteApiV1CartsByAccountLinesBySku","summary":"按 SKU 移除购物车条目","tags":["购物车"],"security":[{"bearer":[]}],"responses":{"200":{}}}},"/api/v1/carts/{account}/products/{product_code}":{"delete":{"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"account","required":true,"description":"购物车所属账号（OMS 网站的登录账号，如 100470admin）。"},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"product_code","required":true,"description":"款号——**一个款**（含全部色码 / 尺码变体），如 OB002。查单个变体请改用 sku。查价格时可用逗号分隔多个。"}],"operationId":"deleteApiV1CartsByAccountProductsByProduct_code","summary":"按款号移除购物车里这一款的全部 SKU","tags":["购物车"],"security":[{"bearer":[]}],"responses":{"200":{}}}}}}