API 参考

6 个应用的端点。Base URL https://api.bodegito.com/v1 —— Beta：端点以 OpenAPI 快照为准。

Beta —— 本参考可能滞后于实时 OpenAPI 快照（/api/openapi.json），冲突时以快照为准。

通用约定

  • 分页：?page=&page_size=（默认 20，最大 200）。过滤：?filter[field]=value。排序：?sort=-created_at。
  • 信封：列表统一返回 {data, page, page_size, total}。写操作返回创建/更新后的资源。
  • 幂等：POST 端点支持 Idempotency-Key 请求头，webhook 与建单可安全重试。

WMS 仓储

GET/wms/inventory查库存（按 sku / 仓库 / 库位）filter[sku], filter[warehouse_id]
POST/wms/inventory/adjust库存调整（必填原因，记审计）sku, warehouse_id, qty_delta, reason
GET/wms/receipts入库单列表
POST/wms/receipts建入库单merchant_id, warehouse_id, lines[]
POST/wms/receipts/{id}/receive收货（组托盘、打 LPN 标签）lines[{sku, qty_received, pallet_id}]
GET/wms/shipments出库单列表
POST/wms/shipments建出库单merchant_id, warehouse_id, lines[]
POST/wms/shipments/{id}/ship发货（扣库存、打 packing list）
POST/wms/shipments/{id}/deliver确认送达（终态）delivered_at, signed_by
GET/wms/waves波次列表
POST/wms/waves/release释放波次（生成拣选任务）wave_id
GET/wms/loadsLoad 列表（零担/整车）
POST/wms/loads/{id}/shipLoad 发运（生成 VICS BOL）

OMS 订单

GET/oms/orders订单列表filter[status], filter[merchant_id]
POST/oms/orders建订单merchant_id, channel, lines[]
POST/oms/orders/{id}/release释放订单下发 WMS
GET/oms/inventory查 OMS 库存（独立模式）或 WMS 同步视图
POST/oms/inventory/adjust调整 OMS 库存（仅独立模式）
GET/oms/channels/connections渠道连接列表
POST/oms/channels/connections新建渠道连接channel, credentials, sync_scopes[]
POST/oms/channels/connections/{id}/test测试渠道连通性
GET/oms/product-mappings商品映射列表
POST/oms/product-mappings新建商品映射connection_id, channel_sku, oms_product_id
POST/oms/sync/inventory推送可售库存到渠道connection_id
POST/oms/sync/products推送商品信息到渠道connection_id, product_ids[]

Purchase 采购

GET/purchase/orders采购单列表filter[status], filter[merchant_id]
POST/purchase/orders建采购单vendor_id, merchant_id, lines[]
POST/purchase/orders/{id}/release下发 WMS（生成入库单）
GET/purchase/asnsASN 列表
POST/purchase/asns建 ASNpo_id, merchant_id, eta
GET/purchase/vendors供应商列表（全租户共享）
POST/purchase/vendors建供应商name, contact

YMS 堆场

GET/yms/appointments预约列表filter[date], filter[type]
POST/yms/appointments建预约carrier, plate, container_no, window_start, window_end
POST/yms/appointments/{id}/check-in闸口签到
POST/yms/gate-entries闸口进出登记plate, direction, appointment_id
GET/yms/movements移动任务列表
POST/yms/movements建移动任务trailer_id, to_location
POST/yms/movements/{id}/complete完成移动任务
GET/yms/yard-map堆场车位占用图

TMS 运输

GET/tms/orders运输订单列表
POST/tms/orders建运输订单（通常来自 WMS Load）load_id, origin, destination
POST/tms/orders/{id}/assign指派承运商carrier_id, rate
GET/tms/orders/{id}/tracking在途跟踪
POST/tms/orders/{id}/pod上传回单pod_files[]
GET/tms/carriers承运商列表
GET/tms/freight-bills运费账单（含按 merchant 分摊行）

Drayage 拖车

GET/drayage/orders拖车订单列表filter[merchant_id]
POST/drayage/orders建拖车订单merchant_id, container_no, pickup, delivery
POST/drayage/orders/{id}/complete完成（生成 WMS 入库单）
GET/drayage/containers集装箱跟踪
GET/drayage/containers/{no}/events集装箱事件时间线

创建一个订单

Request
POST /v1/oms/orders
{
  "merchant_id": "mch_acme",
  "channel": "shopify",
  "lines": [{ "sku": "ACME-WIDGET-01", "qty": 10 }]
}
Response
201 Created
{ "id": "so_9f31", "status": "draft",
  "merchant_id": "mch_acme", "lines": [...] }