# Ever API

> EverAU 批发渠道接口：库存、订单、代发、Webhook。一套认证、限流和错误码，基地址 https://connect.everugg.net.au。

认证：先用渠道号 + 口令换 token（`POST https://connect.everugg.net.au/api/v1/auth/token`，请求体 `{"channel_code":"…","secret":"…"}`），之后每次请求带 `Authorization: Bearer <token>`（不认 `?token=`）；没有凭证可用公共沙箱 `sandbox` / `sandbox`（演示数据，动不了真库存）。响应只看 HTTP 状态码：2xx 正文 `{ data }`，4xx / 5xx 正文 `{ error: { code, message, hint, request_id, doc_url } }`。参数与字段一律 snake_case，仓码用 `GET /api/v1/warehouses` 里的（AU / AUSYD2 / AUSYD1 / CN / CHNZJ1）。限流按开销计点，看响应头 `RateLimit-*`；日常库存同步请用 `/stock/changes` 增量口，全量只在首次或游标失效时拉。

其他语言: [zh-CN](https://connect.everugg.net.au/llms.txt?lang=zh) · [en](https://connect.everugg.net.au/llms.txt?lang=en) · [ko](https://connect.everugg.net.au/llms.txt?lang=ko)

## 指南

- [Ever API · 客户上手](https://connect.everugg.net.au/start.md?lang=zh): 三步跑通第一条调用。出错了每条响应里都带修复提示，看不懂再翻错误目录。

## 认证

- [换取访问令牌：client_credentials（client_id = 渠道号，client_secret = 口令）或 password（username = OMS 登录账号，password = OMS 密码）→ Bearer access_token](https://connect.everugg.net.au/reference/post-api-v1-auth-token.md?lang=zh): `POST /api/v1/auth/token`
- [当前 token 的身份：账号、渠道、能用的仓、权限、业务开关（OMS 账号登录的给 OMS 档案；渠道口令的给仓白名单与网关 scope）](https://connect.everugg.net.au/reference/get-api-v1-me.md?lang=zh): `GET /api/v1/me`

## 仓库与库存

- [仓库清单：仓码、名称、国家、所属公司、合计视图 / 实体仓、能否发货、币种](https://connect.everugg.net.au/reference/get-api-v1-warehouses.md?lang=zh): `GET /api/v1/warehouses`
- [某仓库存：不带筛选 = 整仓（可 page / page_size 分页，响应头 X-Stock-Version 给增量同步用）；sku= 一个变体；product_code= 一款全部变体](https://connect.everugg.net.au/reference/get-api-v1-warehouses-warehouse-code-stock.md?lang=zh): `GET /api/v1/warehouses/{warehouse_code}/stock`
- [库存变更（增量）](https://connect.everugg.net.au/reference/get-api-v1-warehouses-warehouse-code-stock-changes.md?lang=zh): `GET /api/v1/warehouses/{warehouse_code}/stock/changes`

## 产品

- [某仓产品列表（按款号去重，含价格；search 按款号 / 品名搜）](https://connect.everugg.net.au/reference/get-api-v1-products.md?lang=zh): `GET /api/v1/products`
- [款号查产品详情（图片 / 描述 / 价格 + 全部变体 skus）](https://connect.everugg.net.au/reference/get-api-v1-products-product-code.md?lang=zh): `GET /api/v1/products/{product_code}`
- [SKU 查变体详情（单对象）](https://connect.everugg.net.au/reference/get-api-v1-skus-sku.md?lang=zh): `GET /api/v1/skus/{sku}`
- [代发系统在售产品列表（分页）](https://connect.everugg.net.au/reference/get-api-v1-dropship-products.md?lang=zh): `GET /api/v1/dropship-products`

## 价格

- [本渠道的产品价格（分页；product_code 可逗号分隔多个）](https://connect.everugg.net.au/reference/get-api-v1-prices.md?lang=zh): `GET /api/v1/prices`

## 批发订单

- [你这个账号可用的发货方式（自取 / 自送 / 快递…）](https://connect.everugg.net.au/reference/get-api-v1-shipping-methods.md?lang=zh): `GET /api/v1/shipping-methods`
- [你这个账号可选的物流公司](https://connect.everugg.net.au/reference/get-api-v1-carriers.md?lang=zh): `GET /api/v1/carriers`
- [你在 OMS 里存的收货地址簿](https://connect.everugg.net.au/reference/get-api-v1-addresses.md?lang=zh): `GET /api/v1/addresses`
- [创建批发订单（默认只建草稿，auto_confirm=true 才提交审核）](https://connect.everugg.net.au/reference/post-api-v1-orders.md?lang=zh): `POST /api/v1/orders` · 写操作
- [按日期区间查本渠道批发订单；可再按 client_order_number 收窄](https://connect.everugg.net.au/reference/get-api-v1-orders.md?lang=zh): `GET /api/v1/orders`
- [批发订单详情（带归属校验）](https://connect.everugg.net.au/reference/get-api-v1-orders-order-id.md?lang=zh): `GET /api/v1/orders/{order_id}`
- [作废批发订单（连同它占住的配货一起释放）](https://connect.everugg.net.au/reference/delete-api-v1-orders-order-id.md?lang=zh): `DELETE /api/v1/orders/{order_id}` · 写操作
- [配货预览：逐行给出能配多少 / 欠多少 / 预售几时到货，以及应付金额与余额是否够](https://connect.everugg.net.au/reference/post-api-v1-orders-order-id-allocation-preview.md?lang=zh): `POST /api/v1/orders/{order_id}/allocation-preview` · 写操作
- [提交批发订单（提交后不能再改明细）](https://connect.everugg.net.au/reference/post-api-v1-orders-order-id-submit.md?lang=zh): `POST /api/v1/orders/{order_id}/submit` · 写操作

## 代发订单

- [创建代发订单：一单一个 SKU；收件人（澳新地址要 state / city / postal_code）；shipping normal / express；auto_confirm=true 才提交配货（提交后不能改）](https://connect.everugg.net.au/reference/post-api-v1-dropship-orders.md?lang=zh): `POST /api/v1/dropship-orders` · 写操作
- [代发订单列表：按仓 + 日期区间；或按 client_order_number / serial_number 直接找](https://connect.everugg.net.au/reference/get-api-v1-dropship-orders.md?lang=zh): `GET /api/v1/dropship-orders`
- [代发订单汇总列表（分页）](https://connect.everugg.net.au/reference/get-api-v1-dropship-orders-summary.md?lang=zh): `GET /api/v1/dropship-orders/summary`
- [代发订单详情（带归属校验）](https://connect.everugg.net.au/reference/get-api-v1-dropship-orders-dropship-order-id.md?lang=zh): `GET /api/v1/dropship-orders/{dropship_order_id}`
- [作废代发明细（连同它占住的配货一起释放）](https://connect.everugg.net.au/reference/delete-api-v1-dropship-orders-dropship-order-id.md?lang=zh): `DELETE /api/v1/dropship-orders/{dropship_order_id}` · 写操作
- [代发预配：逐条给出能不能配齐、缺多少、预售几时到货、要付多少](https://connect.everugg.net.au/reference/post-api-v1-dropship-orders-allocation-preview.md?lang=zh): `POST /api/v1/dropship-orders/allocation-preview` · 写操作
- [提交代发（提交后不能改）](https://connect.everugg.net.au/reference/post-api-v1-dropship-orders-submit.md?lang=zh): `POST /api/v1/dropship-orders/submit` · 写操作
- [释放这条代发明细占住的预配库存（预配之后决定不提交时用）](https://connect.everugg.net.au/reference/delete-api-v1-dropship-orders-dropship-order-id-allocation.md?lang=zh): `DELETE /api/v1/dropship-orders/{dropship_order_id}/allocation` · 写操作

## 发货与物流

- [本渠道发货单列表](https://connect.everugg.net.au/reference/get-api-v1-shipments.md?lang=zh): `GET /api/v1/shipments`
- [上传收件人证件影像 ⚠️ 终端消费者身份证正反面（PII）](https://connect.everugg.net.au/reference/post-api-v1-shipments-identity-documents.md?lang=zh): `POST /api/v1/shipments/identity-documents` · 写操作
- [发货单详情（带归属校验）](https://connect.everugg.net.au/reference/get-api-v1-shipments-shipment-id.md?lang=zh): `GET /api/v1/shipments/{shipment_id}`
- [物流轨迹（澳邮 Auexpress；默认关闭，需申请开通）](https://connect.everugg.net.au/reference/get-api-v1-shipments-shipment-id-tracking.md?lang=zh): `GET /api/v1/shipments/{shipment_id}/tracking`

## 锁单

- [本渠道锁单 / 预留库存列表（默认 reserved + cancelled；status= 只看一种）](https://connect.everugg.net.au/reference/get-api-v1-reservations.md?lang=zh): `GET /api/v1/reservations`
- [锁单详情（带归属校验）](https://connect.everugg.net.au/reference/get-api-v1-reservations-reservation-id.md?lang=zh): `GET /api/v1/reservations/{reservation_id}`
- [调整锁单明细（写；带归属校验）](https://connect.everugg.net.au/reference/patch-api-v1-reservations-reservation-id.md?lang=zh): `PATCH /api/v1/reservations/{reservation_id}` · 写操作

## 对账

- [你的账户余额（澳洲 / 中国 / 新西兰，开了哪个给哪个）](https://connect.everugg.net.au/reference/get-api-v1-balances.md?lang=zh): `GET /api/v1/balances`
- [交易流水（充值 / 扣款 / 退款），带每笔之后的账户余额；amount_total 是这批的合计](https://connect.everugg.net.au/reference/get-api-v1-transactions.md?lang=zh): `GET /api/v1/transactions`
- [月度账单（按仓、按月，含是否已付）](https://connect.everugg.net.au/reference/get-api-v1-bills.md?lang=zh): `GET /api/v1/bills`
- [退款单（批发 / 代发，含审核状态与原因）](https://connect.everugg.net.au/reference/get-api-v1-refunds.md?lang=zh): `GET /api/v1/refunds`
- [运费单（承运商、运单号、箱数、金额）](https://connect.everugg.net.au/reference/get-api-v1-freight-bills.md?lang=zh): `GET /api/v1/freight-bills`

## 购物车

- [查某账号购物车](https://connect.everugg.net.au/reference/get-api-v1-carts-account.md?lang=zh): `GET /api/v1/carts/{account}`
- [添加 / 更新购物车条目（幂等）](https://connect.everugg.net.au/reference/put-api-v1-carts-account-lines.md?lang=zh): `PUT /api/v1/carts/{account}/lines` · 写操作
- [按 SKU 移除购物车条目](https://connect.everugg.net.au/reference/delete-api-v1-carts-account-lines-sku.md?lang=zh): `DELETE /api/v1/carts/{account}/lines/{sku}` · 写操作
- [按款号移除购物车里这一款的全部 SKU](https://connect.everugg.net.au/reference/delete-api-v1-carts-account-products-product-code.md?lang=zh): `DELETE /api/v1/carts/{account}/products/{product_code}` · 写操作

## Feeds

- [取商品 feed（Google Merchant 规格，同时就是批量导出）：有现成的先给你，旧了后台重拼；一次没拼过则回 202 并开始拼](https://connect.everugg.net.au/reference/get-api-v1-feeds-products.md?lang=zh): `GET /api/v1/feeds/products`
- [看 feed 拼到哪了：在拼 / 好了 / 失败（带原因），以及最新一份的行数与毛病](https://connect.everugg.net.au/reference/get-api-v1-feeds-products-status.md?lang=zh): `GET /api/v1/feeds/products/status`

## 参考资料

- [错误码目录](https://connect.everugg.net.au/reference/errors.md?lang=zh): 错误响应里的 `error.code` 是稳定的，按它编程判断，别解析文案。`error.docUrl` 指到这一行。
- [数据模型](https://connect.everugg.net.au/reference/ontology.md?lang=zh): 这门生意的领域模型：实体、字段、关系。只列对外可见的字段。机器读的 JSON-LD 在 `/ontology`。
- [接入你的 AI（MCP）](https://connect.everugg.net.au/reference/mcp.md?lang=zh): 你的 AI（Claude Desktop、Cursor 或自己写的 agent）用你的 token 直连网关，工具清单按你的权限裁剪——接进 AI 不会让权限变大。
- [变更日志](https://connect.everugg.net.au/changelog.md?lang=zh): 只记客户看得见的变化：端点、参数、响应形状、错误码、限流、认证。版本号在每个响应的 `X-API-Version` 头里。

## 工具

- [CLI](https://connect.everugg.net.au/cli.md?lang=zh): 命令行工具，给程序员、脚本和会敲命令的 AI；安装： `curl -fsSL https://connect.everugg.net.au/cli/install.sh | sh`
- [MCP](https://connect.everugg.net.au/reference/mcp.md?lang=zh): 你的 AI（Claude Desktop、Cursor 或自己写的 agent）用你的 token 直连网关，工具清单按你的权限裁剪——接进 AI 不会让权限变大。

## 机器可读

- [OpenAPI](https://connect.everugg.net.au/swagger/json?lang=zh): OpenAPI 规格（JSON）
- [领域本体（JSON-LD）](https://connect.everugg.net.au/ontology)
- [A2A 名片](https://connect.everugg.net.au/.well-known/agent-card.json)
- MCP: `https://connect.everugg.net.au/mcp`

## Optional

- [完整版（全部页面合成一个文件）](https://connect.everugg.net.au/llms-full.txt?lang=zh)