API文档

REST API 参考与示例

本页提供认证、常用查询与写入示例，便于快速集成。

GET /v1/inventory/replenishments

智能补货建议，基于销售、在途与安全库存。

GET /v1/inventory/replenishments?sku=SKU-001 HTTP/1.1
Host: https://www.chimefieldus.com
Authorization: Bearer <YOUR_TOKEN>

PUT /v1/inventory/safety-stock

设置安全库存。

PUT /v1/inventory/safety-stock HTTP/1.1
Host: https://www.chimefieldus.com
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>

{ "sku": "SKU-001", "warehouse": "WH-A", "safetyStock": 50 }

POST /v1/inventory/stocktakes

创建盘点作业。

POST /v1/inventory/stocktakes HTTP/1.1
Host: https://www.chimefieldus.com
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>

{ "warehouse": "WH-A", "items": [ { "sku": "SKU-001", "counted": 118 } ] }

POST /v1/shipments

创建发货单，支持多渠道物流。

POST /v1/shipments HTTP/1.1
Host: https://www.chimefieldus.com
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>

{ "orderId": "ord_20251101001", "channel": "zto", "address": {"country": "CN"} }

GET /v1/orders/exceptions

查询异常订单（缺货、地址异常、支付异常等）。

GET /v1/orders/exceptions?page=1&page_size=20 HTTP/1.1
Host: https://www.chimefieldus.com
Authorization: Bearer <YOUR_TOKEN>

POST /v1/orders/{orderId}/request-review

智能邀评：向买家发送评价邀请（按平台策略）。

POST /v1/orders/ord_20251101001/request-review HTTP/1.1
Host: https://www.chimefieldus.com
Authorization: Bearer <YOUR_TOKEN>

GET /v1/products/{productId}

获取单个产品详情。

{
  "id": "prd_001",
  "sku": "SKU-001",
  "name": "Wireless Mouse",
  "category": "Electronics",
  "attributes": { "color": "black", "weight": "120g" },
  "images": [ "https://cdn.example.com/sku-001-1.jpg" ]
}
响应字段
  • attributes — 自定义属性字典
  • images[] — 图片地址数组

POST /v1/products

创建产品。

POST /v1/products HTTP/1.1
Host: https://www.chimefieldus.com
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>

{ "sku": "SKU-002", "name": "Keyboard", "category": "Electronics" }
请求参数
  • sku — SKU 编码，必填且唯一
  • name — 产品名称，必填
  • category — 分类，必填
  • attributes — 可选，自定义属性对象

PUT /v1/products/{productId}

更新产品信息。只更新提交的字段。

PUT /v1/products/prd_001 HTTP/1.1
Host: https://www.chimefieldus.com
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>

{ "name": "Wireless Mouse Pro", "attributes": { "color": "black" } }

POST /v1/products/bulk-upload

批量上新与批量属性/图片提交。支持文件或 JSON。

POST /v1/products/bulk-upload HTTP/1.1
Host: https://www.chimefieldus.com
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>

{ "items": [ { "sku": "SKU-100", "name": "Bundle A" } ] }

POST /v1/products/{productId}/sync

多平台商品信息同步。

POST /v1/products/prd_001/sync?channel=mercado HTTP/1.1
Host: https://www.chimefieldus.com
Authorization: Bearer <YOUR_TOKEN>
请求参数
  • channel — 平台标识，如 mercado/shopify/aliexpress

认证

使用 Bearer Token 进行认证，将令牌置于 Authorization 请求头中。

GET /v1/me HTTP/1.1
Host: https://www.chimefieldus.com
Authorization: Bearer <YOUR_TOKEN>

通用请求头

名称 示例 说明
Authorization Bearer <TOKEN> 身份认证
Content-Type application/json 请求体为 JSON 时必填
Accept-Language en / zh-CN 返回多语言字段时的偏好

产品管理

多平台商品信息同步、智能定价、全生命周期管理

GET /v1/products

按页获取产品列表。支持关键字与分类过滤。

GET /v1/products?page=1&page_size=20&keyword=mouse HTTP/1.1
Host: https://www.chimefieldus.com
Authorization: Bearer <YOUR_TOKEN>
请求参数
  • page — 页码，从 1 开始
  • page_size — 每页数量，默认 20，最大 200
  • keyword — 关键字搜索，匹配 SKU/名称 等
  • category — 按分类过滤，可选
{
  "page": 1,
  "pageSize": 20,
  "total": 132,
  "items": [
    {
      "id": "prd_001",
      "sku": "SKU-001",
      "name": "Wireless Mouse",
      "category": "Electronics",
      "price": 19.99,
      "currency": "USD"
    }
  ]
}
响应字段
  • page — 当前页码
  • pageSize — 每页数量
  • total — 总记录数
  • items — 产品数组，每项包含 id, sku, name, category, price, currency

POST /v1/orders

创建新订单。系统将校验库存、计算金额，并返回订单号。

POST /v1/orders HTTP/1.1
Host: https://www.chimefieldus.com
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>

{
  "customerId": "cus_1001",
  "items": [
    { "sku": "SKU-001", "quantity": 2 }
  ],
  "shippingAddress": {
    "country": "US",
    "city": "LA",
    "address1": "Sunset Blvd 1"
  }
}
请求参数
  • customerId — 客户 ID，必填
  • items[] — 订单明细数组（sku, quantity）
  • shippingAddress — 收货地址对象（country, city, address1）
  • note — 备注，可选
{
  "orderId": "ord_20251101001",
  "status": "created",
  "amount": {
    "subtotal": 39.98,
    "tax": 0.00,
    "shipping": 5.00,
    "total": 44.98,
    "currency": "USD"
  }
}
响应字段
  • orderId — 订单号
  • status — 订单状态
  • amount — 金额信息（subtotal, tax, shipping, total, currency）

错误响应

请求失败时返回统一错误结构。

{
  "error": {
    "code": "invalid_parameter",
    "message": "pageSize must be between 1 and 200"
  }
}

限流

默认每分钟 600 次请求，超出将返回 429。

查询与分页约定

  • 分页参数：page（从1开始），page_size（默认20，最大200）
  • 排序：sort，如 sort=created_at desc 或 sort=name asc
  • 过滤：按字段精确匹配或关键字，如 keyword=mouse&category=Electronics
  • 幂等性：写入接口可传 Idempotency-Key 头避免重复提交

订单管理

集中管理、自动分配、全链路跟踪与异常预警

GET /v1/orders

按页获取订单列表，支持状态、时间范围筛选。

GET /v1/orders?page=1&page_size=20&status=created&from=2025-11-01&to=2025-11-02 HTTP/1.1
Host: https://www.chimefieldus.com
Authorization: Bearer <YOUR_TOKEN>
请求参数
  • page — 页码，从 1 开始
  • page_size — 每页数量，默认 20，最大 200
  • status — 订单状态过滤，如 created/shipped/completed/cancelled
  • from / to — 创建时间范围，YYYY-MM-DD
{
  "page": 1,
  "pageSize": 20,
  "total": 58,
  "items": [
    { "orderId": "ord_20251101001", "status": "created", "total": 44.98, "currency": "USD" }
  ]
}
响应字段
  • page, pageSize, total — 分页信息
  • items[] — 订单数组，含 orderId, status, total, currency

GET /v1/orders/{orderId}

获取订单详情。

{
  "orderId": "ord_20251101001",
  "status": "created",
  "customer": { "id": "cus_1001", "name": "ACME Retail" },
  "items": [ { "sku": "SKU-001", "name": "Wireless Mouse", "quantity": 2, "price": 19.99 } ],
  "amount": { "subtotal": 39.98, "tax": 0.00, "shipping": 5.00, "total": 44.98, "currency": "USD" }
}
响应字段
  • orderId, status — 订单基础信息
  • customer — 客户对象，含 id 与 name
  • items[] — 明细数组，含 sku/name/quantity/price
  • amount — 金额对象，含 subtotal/tax/shipping/total/currency

PATCH /v1/orders/{orderId}

更新订单状态（如发货、完成、取消）。

PATCH /v1/orders/ord_20251101001 HTTP/1.1
Host: https://www.chimefieldus.com
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>

{ "status": "shipped", "trackingNo": "SF123456789" }

{ "orderId": "ord_20251101001", "status": "shipped" }
请求参数
  • status — 目标状态，如 shipped/completed/cancelled
  • trackingNo — 物流单号，发货时可填

GET /v1/customers

按页获取客户列表。

GET /v1/customers?page=1&page_size=20&keyword=acme HTTP/1.1
Host: https://www.chimefieldus.com
Authorization: Bearer <YOUR_TOKEN>
请求参数
  • page, page_size — 分页参数
  • keyword — 按名称/邮箱搜索，可选
{ "page": 1, "pageSize": 20, "total": 3, "items": [ { "id": "cus_1001", "name": "ACME Retail" } ] }

POST /v1/customers

创建客户。

POST /v1/customers HTTP/1.1
Host: https://www.chimefieldus.com
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>

{ "name": "ACME Retail", "email": "buyer@acme.com" }
请求参数
  • name — 客户名称，必填
  • email — 邮箱，可选

库存管理

统一库存、智能补货、预警与盘点

GET /v1/inventory/stock

查询单个或多个 SKU 当前库存。

GET /v1/inventory/stock?sku=SKU-001&warehouse=WH-A HTTP/1.1
Host: https://www.chimefieldus.com
Authorization: Bearer <YOUR_TOKEN>
请求参数
  • sku — SKU 编码，支持多值
  • warehouse — 仓库编码，可选
{ "sku": "SKU-001", "warehouse": "WH-A", "onHand": 120, "reserved": 12 }

POST /v1/inventory/adjustments

新增库存调整单。

POST /v1/inventory/adjustments HTTP/1.1
Host: https://www.chimefieldus.com
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>

{ "sku": "SKU-001", "warehouse": "WH-A", "delta": 10, "reason": "cycle_count" }
请求参数
  • sku — SKU 编码，必填
  • warehouse — 仓库编码，必填
  • delta — 增减数量，正为入库，负为出库
  • reason — 调整原因，如 cycle_count/damage/loss

采购管理

供应商、采购计划、到货与质检

GET /v1/suppliers

按页获取供应商列表。

GET /v1/suppliers?page=1&page_size=20 HTTP/1.1
Host: https://www.chimefieldus.com
Authorization: Bearer <YOUR_TOKEN>

POST /v1/purchase-plans

创建采购计划。

POST /v1/purchase-plans HTTP/1.1
Host: https://www.chimefieldus.com
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>

{ "items": [ { "sku": "SKU-001", "quantity": 200 } ], "expectDate": "2025-11-20" }

POST /v1/inbounds/qc-results

提交质检结果。

POST /v1/inbounds/qc-results HTTP/1.1
Host: https://www.chimefieldus.com
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>

{ "po": "PO-2025110101", "passed": true, "defects": [] }

物流管理

多渠道物流、路径规划、轨迹追踪与时效分析

GET /v1/logistics/channels

查询可用物流渠道。

GET /v1/logistics/channels HTTP/1.1
Host: https://www.chimefieldus.com
Authorization: Bearer <YOUR_TOKEN>

POST /v1/logistics/rate-estimate

运费与时效预估。

POST /v1/logistics/rate-estimate HTTP/1.1
Host: https://www.chimefieldus.com
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>

{ "weight": 0.6, "destination": { "country": "US" } }

GET /v1/logistics/track

包裹/托运单轨迹查询。

GET /v1/logistics/track?trackingNo=SF123456789 HTTP/1.1
Host: https://www.chimefieldus.com
Authorization: Bearer <YOUR_TOKEN>

财务管理

多币种与汇率、利润与成本、发票与对账

GET /v1/finance/fx-rates

查询实时或历史汇率。

GET /v1/finance/fx-rates?base=USD&date=2025-11-01 HTTP/1.1
Host: https://www.chimefieldus.com
Authorization: Bearer <YOUR_TOKEN>

GET /v1/finance/profit-report

分业务线利润与费用分摊报表。

GET /v1/finance/profit-report?from=2025-11-01&to=2025-11-30 HTTP/1.1
Host: https://www.chimefieldus.com
Authorization: Bearer <YOUR_TOKEN>

POST /v1/finance/invoices

开具发票或记录外部发票。

POST /v1/finance/invoices HTTP/1.1
Host: https://www.chimefieldus.com
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>

{ "customerId": "cus_1001", "amount": 120.50, "currency": "USD" }

Webhooks 事件

订单状态变化、库存变更等事件将回调你的接收地址。

{
  "event": "order.shipped",
  "data": { "orderId": "ord_20251101001", "trackingNo": "SF123456789" },
  "sentAt": "2025-11-01T15:35:00Z"
}
如需沙箱环境或更详细的 OpenAPI 规格，请联系技术支持。
粤ICP备2025480941号
用户名 姓名 邮箱 密码 确认密码 角色 普通用户 经理 管理员 注册 原密码 新密码 确认新密码 密码不匹配