899 lines
44 KiB
YAML
899 lines
44 KiB
YAML
openapi: 3.0.3
|
||
info:
|
||
title: 柏悦头程订单 API
|
||
description: 业务成功和失败均使用 HTTP 200；仅响应体 code 为字符串 "200" 时表示成功，其他 code 表示失败。
|
||
version: 1.6.0
|
||
security:
|
||
- bearerAuth: []
|
||
paths:
|
||
/api/platform/v1/orders/first-leg/inbound-code-policy:
|
||
get:
|
||
summary: 平台端查询全系统入仓码模式
|
||
description: 与客户下单端返回同一份全局策略，不按客户区分。
|
||
responses:
|
||
'200':
|
||
description: 查询成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
code: {type: string, example: '200'}
|
||
data: {$ref: '#/components/schemas/InboundCodePolicy'}
|
||
'403': {description: 需要平台订单列表、创建、编辑或提交权限之一}
|
||
/api/platform/v1/orders:
|
||
get:
|
||
summary: 平台统一订单列表
|
||
description: >-
|
||
统一返回七态产品主状态、下一步动作及测量/预装/装柜/派送摘要，需要 platform:order:list。
|
||
入仓码来源由全系统统一模式控制：AUTO 在订单提交时按物流渠道生成，格式为物流前缀+YYMMDD+当天全平台票序；
|
||
LEGACY_MANUAL 在草稿中录入旧系统入仓码。两种模式下入仓码一经提交均固定；有入库单时同时返回
|
||
inboundId、inboundVersion、loadingVersion、pickingVersion；inboundVersion
|
||
才是 C04 loading/complete 的 expectedVersion，loadingVersion 当前等于 pickingVersion（兼容别名）。
|
||
tenantId 省略时跨全部客户；mainStatus 省略时按订单创建时间分页，指定 PENDING_REVIEW 时由 Order 查询，
|
||
指定其他主状态时由 Firstleg 精确分页。旧 /orders/first-leg 接口保持兼容。
|
||
列表行同时返回 customerRemark（客户下单备注）、latestInternalNote（最新一条平台内部备注）和
|
||
relation（仅有关联时返回；PARENT 含 childCount，CHILD 含 rootOrderId、parentOrderId 与 splitSequence）。
|
||
parameters:
|
||
- {name: tenantId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
||
- $ref: '#/components/parameters/UnifiedKeyword'
|
||
- $ref: '#/components/parameters/UnifiedOrderNo'
|
||
- $ref: '#/components/parameters/UnifiedMainStatus'
|
||
- {name: customerId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
||
- {name: receivingWarehouseId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
||
- {name: destinationWarehouseId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
||
- $ref: '#/components/parameters/UnifiedInboundCode'
|
||
- $ref: '#/components/parameters/UnifiedInternalOrderStatus'
|
||
- $ref: '#/components/parameters/UnifiedExpectedArrivalDate'
|
||
- $ref: '#/components/parameters/UnifiedFeeReviewStatus'
|
||
- $ref: '#/components/parameters/UnifiedChannelName'
|
||
- $ref: '#/components/parameters/UnifiedContainerNo'
|
||
- $ref: '#/components/parameters/UnifiedCabinetNo'
|
||
- $ref: '#/components/parameters/UnifiedSailingDate'
|
||
- $ref: '#/components/parameters/UnifiedLoaded'
|
||
- $ref: '#/components/parameters/UnifiedFullContainer'
|
||
- $ref: '#/components/parameters/UnifiedMeasurementReviewStatus'
|
||
- $ref: '#/components/parameters/UnifiedFbaCode'
|
||
- $ref: '#/components/parameters/UnifiedCreatedFrom'
|
||
- $ref: '#/components/parameters/UnifiedCreatedTo'
|
||
- $ref: '#/components/parameters/UnifiedPage'
|
||
- $ref: '#/components/parameters/UnifiedSize'
|
||
responses:
|
||
'200':
|
||
description: 成功或业务失败，响应体 code 为字符串 200 时成功
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/UnifiedOrderPageEnvelope'}
|
||
'403': {description: 需要平台身份和 platform:order:list 权限}
|
||
/api/platform/v1/orders/{orderId}:
|
||
get:
|
||
summary: 平台统一订单详情
|
||
description: 合并 Order 与 Firstleg 时间线并按发生时间升序返回；所有状态直接返回 Order 创建时生成的 inboundCode；平台可见内部备注。
|
||
parameters:
|
||
- $ref: '#/components/parameters/UnifiedOrderId'
|
||
- $ref: '#/components/parameters/UnifiedTenantId'
|
||
responses:
|
||
'200':
|
||
description: 成功或业务失败，按响应体 code 判断
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/UnifiedOrderDetailEnvelope'}
|
||
'403': {description: 需要平台身份和 platform:order:list 权限}
|
||
/api/platform/v1/orders/{orderId}/internal-notes:
|
||
post:
|
||
summary: 添加订单内部备注
|
||
description: 添加仅平台内部可见的订单备注，需要 platform:order:note 权限。
|
||
parameters:
|
||
- $ref: '#/components/parameters/UnifiedOrderId'
|
||
- $ref: '#/components/parameters/UnifiedTenantId'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [content]
|
||
properties:
|
||
content: {type: string, minLength: 1, maxLength: 2000}
|
||
responses:
|
||
'200': {description: 备注添加成功或业务失败，按响应体 code 判断}
|
||
'403': {description: 需要 platform:order:note 权限}
|
||
/api/merchant/v1/orders:
|
||
get:
|
||
summary: 客户统一订单列表
|
||
description: >-
|
||
只按登录态客户隔离查询，需要 merchant:order:list；不接受目标客户参数。
|
||
有入库单时同时返回 inboundId、inboundVersion、loadingVersion、pickingVersion；inboundVersion
|
||
才是 C04 loading/complete 的 expectedVersion，loadingVersion 当前等于 pickingVersion（兼容别名）。
|
||
parameters:
|
||
- $ref: '#/components/parameters/UnifiedKeyword'
|
||
- $ref: '#/components/parameters/UnifiedOrderNo'
|
||
- $ref: '#/components/parameters/UnifiedMainStatus'
|
||
- {name: customerId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
||
- {name: receivingWarehouseId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
||
- {name: destinationWarehouseId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
||
- $ref: '#/components/parameters/UnifiedInboundCode'
|
||
- $ref: '#/components/parameters/UnifiedInternalOrderStatus'
|
||
- $ref: '#/components/parameters/UnifiedExpectedArrivalDate'
|
||
- $ref: '#/components/parameters/UnifiedFeeReviewStatus'
|
||
- $ref: '#/components/parameters/UnifiedChannelName'
|
||
- $ref: '#/components/parameters/UnifiedContainerNo'
|
||
- $ref: '#/components/parameters/UnifiedCabinetNo'
|
||
- $ref: '#/components/parameters/UnifiedSailingDate'
|
||
- $ref: '#/components/parameters/UnifiedLoaded'
|
||
- $ref: '#/components/parameters/UnifiedFullContainer'
|
||
- $ref: '#/components/parameters/UnifiedMeasurementReviewStatus'
|
||
- $ref: '#/components/parameters/UnifiedFbaCode'
|
||
- $ref: '#/components/parameters/UnifiedCreatedFrom'
|
||
- $ref: '#/components/parameters/UnifiedCreatedTo'
|
||
- $ref: '#/components/parameters/UnifiedPage'
|
||
- $ref: '#/components/parameters/UnifiedSize'
|
||
responses:
|
||
'200':
|
||
description: 成功或业务失败，按响应体 code 判断
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/UnifiedOrderPageEnvelope'}
|
||
'403': {description: 需要 merchant:order:list 权限}
|
||
/api/merchant/v1/orders/{orderId}:
|
||
get:
|
||
summary: 客户统一订单详情
|
||
description: 仅返回登录客户所属订单及客户可见时间线，不返回平台内部备注。
|
||
parameters:
|
||
- $ref: '#/components/parameters/UnifiedOrderId'
|
||
responses:
|
||
'200':
|
||
description: 成功或业务失败，按响应体 code 判断
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/UnifiedOrderDetailEnvelope'}
|
||
'403': {description: 需要 merchant:order:view 权限}
|
||
/api/merchant/v1/orders/first-leg:
|
||
get:
|
||
summary: 客户端入库订单聚合列表
|
||
description: 按当前登录客户分页返回订单、货物汇总、收货方快照及头程入仓编码，需要 merchant:order:list 权限；客户 ID 从 JWT 的 tenantId 兼容字段取得。
|
||
parameters:
|
||
- {name: keyword, in: query, required: false, schema: {type: string, maxLength: 64}}
|
||
- {name: orderNo, in: query, required: false, schema: {type: string, maxLength: 64}}
|
||
- {name: receivingWarehouseId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
||
- {name: channelName, in: query, required: false, schema: {type: string, maxLength: 128}}
|
||
- {name: customerContact, in: query, required: false, description: 客户名称、联系人或手机号, schema: {type: string, maxLength: 128}}
|
||
- {name: customerId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
||
- {name: status, in: query, required: false, schema: {type: string}}
|
||
- {name: operationStatus, in: query, required: false, description: 操作状态，优先于兼容参数 status, schema: {type: string}}
|
||
- {name: destinationType, in: query, required: false, schema: {type: string, maxLength: 32}}
|
||
- {name: destinationWarehouseId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
||
- {name: createdFrom, in: query, required: false, schema: {type: string, format: date-time}}
|
||
- {name: createdTo, in: query, required: false, schema: {type: string, format: date-time}}
|
||
- {name: page, in: query, required: false, schema: {type: integer, minimum: 1, default: 1}}
|
||
- {name: size, in: query, required: false, schema: {type: integer, minimum: 1, maximum: 200, default: 20}}
|
||
responses:
|
||
'200':
|
||
description: 成功或业务失败，响应体 code 为字符串 200 时成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
items: {type: array, items: {$ref: '#/components/schemas/FirstLegOrderSummary'}}
|
||
post:
|
||
summary: 创建订单草稿
|
||
parameters:
|
||
- $ref: '#/components/parameters/IdempotencyKey'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/FirstLegOrderDraft'}
|
||
responses:
|
||
'200': {description: 成功或业务失败，按响应体 code 判断}
|
||
/api/merchant/v1/orders/first-leg/batch:
|
||
post:
|
||
summary: 批量创建头程订单草稿
|
||
description: >-
|
||
一次请求为多个外层行创建草稿；每个数组元素对应一张草稿，元素内 cargoes
|
||
对应该行的多个产品明细。每项独立处理，允许部分成功；草稿仅校验渠道、目的仓、SKU
|
||
和箱数，提交审核前再执行完整货物与提货资料校验。最多 50 项。
|
||
parameters:
|
||
- $ref: '#/components/parameters/IdempotencyKey'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
minItems: 1
|
||
maxItems: 50
|
||
items: {$ref: '#/components/schemas/FirstLegBatchDraftItem'}
|
||
responses:
|
||
'200':
|
||
description: 批量处理完成；业务失败通过 items.errorCode 和 items.errorMessage 逐项返回
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/FirstLegBatchDraftResponse'}
|
||
'400': {description: 请求数组为空、超过 50 项或幂等键缺失}
|
||
'403': {description: 需要 merchant:order:create 权限}
|
||
/api/merchant/v1/orders/first-leg/inbound-code-policy:
|
||
get:
|
||
summary: 查询全系统入仓码模式
|
||
description: >-
|
||
返回订单服务当前统一运行模式。AUTO 表示提交时由新系统生成；LEGACY_MANUAL
|
||
表示两套系统并跑期间必须录入旧系统生成的入仓码。该策略不按客户区分。
|
||
responses:
|
||
'200':
|
||
description: 查询成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
code: {type: string, example: '200'}
|
||
data: {$ref: '#/components/schemas/InboundCodePolicy'}
|
||
'403': {description: 需要 merchant:order:list、merchant:order:create 或 merchant:order:edit 权限之一}
|
||
/api/merchant/v1/orders/first-leg/{id}/submit:
|
||
post:
|
||
summary: 提交订单
|
||
parameters:
|
||
- $ref: '#/components/parameters/OrderId'
|
||
- $ref: '#/components/parameters/IdempotencyKey'
|
||
responses:
|
||
'200': {description: 成功或业务失败，按响应体 code 判断}
|
||
/api/platform/v1/orders/first-leg:
|
||
get:
|
||
summary: 平台分页查询头程订单
|
||
description: tenantId 是目标客户 ID 的兼容参数名；省略时查询全部客户订单，传入时仅查询指定客户。
|
||
parameters:
|
||
- name: tenantId
|
||
in: query
|
||
required: false
|
||
description: 可选的目标客户筛选；tenantId 为历史兼容参数名
|
||
schema: {type: integer, format: int64, minimum: 1}
|
||
responses:
|
||
'200': {description: 查询成功或业务失败，按响应体 code 判断}
|
||
'403': {description: 需要 platform:order:list 权限和平台身份}
|
||
post:
|
||
summary: 平台代客创建订单草稿
|
||
parameters:
|
||
- $ref: '#/components/parameters/TenantId'
|
||
- $ref: '#/components/parameters/IdempotencyKey'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/FirstLegOrderDraft'}
|
||
responses:
|
||
'200': {description: 成功或业务失败，按响应体 code 判断}
|
||
'403': {description: 需要 platform:order:create 权限}
|
||
/api/platform/v1/orders/first-leg/tenant-statistics:
|
||
get:
|
||
tags: [Platform first-leg orders]
|
||
summary: 查询客户累计及本月运单数
|
||
description: 仅统计 submitted_at 非空的 MASTER 根运单，草稿和 CHILD 拆分单不计入；累计不受取消或驳回影响；月份按 Asia/Shanghai 半开区间计算。
|
||
parameters:
|
||
- {$ref: '#/components/parameters/TenantId'}
|
||
responses:
|
||
'200':
|
||
description: 成功；需要 platform:order:list 权限
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
code: {type: string, example: '200'}
|
||
data: {$ref: '#/components/schemas/TenantOrderStatisticsResponse'}
|
||
'403': {description: 需要平台身份和 platform:order:list 权限}
|
||
|
||
/api/platform/v1/orders/first-leg/tenant-counts:
|
||
get:
|
||
summary: 批量查询客户运单数
|
||
description: 按客户 ID 返回真实头程运单数量，tenantIds 为历史兼容参数名；最多 200 个客户。
|
||
parameters:
|
||
- name: tenantIds
|
||
in: query
|
||
required: true
|
||
schema: {type: array, maxItems: 200, items: {type: integer, format: int64}}
|
||
responses:
|
||
'200': {description: 查询成功或业务失败，按响应体 code 判断}
|
||
'403': {description: 需要 platform:order:list 权限}
|
||
/api/platform/v1/orders/first-leg/{id}/submit:
|
||
post:
|
||
summary: 平台代客提交指定订单
|
||
parameters:
|
||
- $ref: '#/components/parameters/OrderId'
|
||
- $ref: '#/components/parameters/TenantId'
|
||
- $ref: '#/components/parameters/IdempotencyKey'
|
||
responses:
|
||
'200': {description: 成功或业务失败，按响应体 code 判断}
|
||
'403': {description: 需要 platform:order:submit 权限}
|
||
/api/platform/v1/orders/first-leg/{id}:
|
||
put:
|
||
summary: 平台编辑指定订单草稿
|
||
parameters:
|
||
- $ref: '#/components/parameters/OrderId'
|
||
- $ref: '#/components/parameters/TenantId'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/FirstLegOrderDraft'}
|
||
responses:
|
||
'200': {description: 成功或业务失败，按响应体 code 判断}
|
||
'403': {description: 需要 platform:order:edit 权限}
|
||
/internal/order/v1/fulfillment-splits:
|
||
post:
|
||
summary: 创建父订单装柜拆分（Firstleg 内部）
|
||
parameters:
|
||
- $ref: '#/components/parameters/InternalToken'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema: { $ref: '#/components/schemas/FulfillmentSplitCreateRequest' }
|
||
responses:
|
||
'200': { description: 成功, content: { application/json: { schema: { $ref: '#/components/schemas/FulfillmentSplitResponse' } } } }
|
||
|
||
/internal/order/v1/fulfillment-splits/{tenantId}/{parentOrderId}:
|
||
get:
|
||
summary: 查询根订单、已完成分片与当前余量（Firstleg 内部）
|
||
parameters:
|
||
- $ref: '#/components/parameters/InternalToken'
|
||
- { name: tenantId, in: path, required: true, schema: { type: integer, format: int64 } }
|
||
- { name: parentOrderId, in: path, required: true, schema: { type: integer, format: int64 } }
|
||
responses:
|
||
'200': { description: 成功；返回原始箱数、累计已装和当前余量 }
|
||
'403': { description: 内部凭证无效 }
|
||
|
||
/api/platform/v1/orders/{orderId}/fulfillment-tree:
|
||
get:
|
||
summary: 查询父子订单与柜次数量摘要
|
||
parameters:
|
||
- { name: orderId, in: path, required: true, schema: { type: integer, format: int64 } }
|
||
- { name: tenantId, in: query, required: true, schema: { type: integer, format: int64 } }
|
||
responses: { '200': { description: 成功 }, '403': { description: 无权限 } }
|
||
|
||
/api/merchant/v1/orders/{orderId}/fulfillment-tree:
|
||
get:
|
||
summary: 查询我的父子订单与柜次数量摘要
|
||
parameters:
|
||
- { name: orderId, in: path, required: true, schema: { type: integer, format: int64 } }
|
||
responses: { '200': { description: 成功 }, '403': { description: 无权限 } }
|
||
|
||
/api/platform/v1/orders/container-bookings/{containerBookingId}/fulfillment-slices:
|
||
get:
|
||
summary: 平台按柜次查询全部订单分片
|
||
description: tenantId 可选；省略时跨客户汇总。响应不包含照片、锁码或内部审计字段。
|
||
parameters:
|
||
- {name: containerBookingId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
||
- {name: tenantId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
||
responses:
|
||
'200': {description: 成功；无分片时返回空数组}
|
||
'403': {description: 需要平台身份和 platform:order:list 权限}
|
||
/api/merchant/v1/orders/container-bookings/{containerBookingId}/fulfillment-slices:
|
||
get:
|
||
summary: 客户按柜次查询本客户订单分片
|
||
description: 客户范围来自登录态，不接受目标客户参数。
|
||
parameters:
|
||
- {name: containerBookingId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
||
responses:
|
||
'200': {description: 成功；无分片时返回空数组}
|
||
'403': {description: 需要 merchant:order:view 权限}
|
||
|
||
components:
|
||
securitySchemes:
|
||
bearerAuth:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: JWT
|
||
schemas:
|
||
TenantOrderStatisticsResponse:
|
||
type: object
|
||
required: [tenantId, totalSubmittedOrders, currentMonthSubmittedOrders, monthStart, nextMonthStart, zoneId, asOf]
|
||
properties:
|
||
tenantId: {type: string, pattern: '^[1-9][0-9]*$', description: Long 按字符串序列化以避免 JavaScript 精度丢失}
|
||
totalSubmittedOrders: {type: string, pattern: '^[0-9]+$', description: Long 按字符串序列化}
|
||
currentMonthSubmittedOrders: {type: string, pattern: '^[0-9]+$', description: Long 按字符串序列化}
|
||
monthStart: {type: string, format: date-time}
|
||
nextMonthStart: {type: string, format: date-time}
|
||
zoneId: {type: string, example: Asia/Shanghai}
|
||
asOf: {type: string, format: date-time}
|
||
UnifiedMainStatus:
|
||
type: string
|
||
enum: [PENDING_REVIEW, WAIT_MEASURE, INBOUNDED, WAIT_SPLIT, LOADING, LOADED, DELIVERED]
|
||
description: >-
|
||
统一订单七态产品主状态。WAIT_SPLIT 为正式待分柜状态，INBOUNDED 仅兼容存量已入库记录。
|
||
UnifiedOrderPageEnvelope:
|
||
type: object
|
||
properties:
|
||
code: {type: string, example: '200'}
|
||
message: {type: string}
|
||
data: {$ref: '#/components/schemas/UnifiedOrderPage'}
|
||
UnifiedOrderPage:
|
||
type: object
|
||
properties:
|
||
records: {type: array, items: {$ref: '#/components/schemas/UnifiedOrderRow'}}
|
||
page: {type: integer, format: int64, minimum: 1}
|
||
size: {type: integer, format: int64, minimum: 1}
|
||
total: {type: integer, format: int64, minimum: 0}
|
||
pages: {type: integer, format: int64, minimum: 0}
|
||
UnifiedOrderDetailEnvelope:
|
||
type: object
|
||
properties:
|
||
code: {type: string, example: '200'}
|
||
message: {type: string}
|
||
data: {$ref: '#/components/schemas/UnifiedOrderDetail'}
|
||
UnifiedOrderDetail:
|
||
type: object
|
||
properties:
|
||
summary: {$ref: '#/components/schemas/UnifiedOrderRow'}
|
||
order:
|
||
type: object
|
||
properties:
|
||
order: {type: object, description: Order 服务订单主实体}
|
||
cargoes: {type: array, items: {type: object}}
|
||
parties: {type: array, items: {type: object}}
|
||
internalNotes: {type: array, items: {type: object}, description: 客户详情始终为空数组}
|
||
statusHistory: {type: array, items: {type: object}}
|
||
timeline: {type: array, items: {$ref: '#/components/schemas/UnifiedOrderTimelineEvent'}}
|
||
UnifiedOrderRow:
|
||
type: object
|
||
properties:
|
||
orderId: {type: integer, format: int64}
|
||
tenantId: {type: integer, format: int64}
|
||
orderNo: {type: string}
|
||
mainStatus: {$ref: '#/components/schemas/UnifiedMainStatus'}
|
||
nextAction: {type: string, nullable: true}
|
||
relation: {$ref: '#/components/schemas/UnifiedOrderRelation'}
|
||
internalOrderStatus: {type: string, enum: [DRAFT, SUBMITTED, APPROVED, ACCEPTED, REJECTED, CANCELLED, PROCESSING, COMPLETED], nullable: true}
|
||
customerId: {type: integer, format: int64, nullable: true}
|
||
customerName: {type: string, nullable: true}
|
||
channelName: {type: string, nullable: true}
|
||
receivingWarehouseId: {type: integer, format: int64, nullable: true}
|
||
receivingWarehouseName: {type: string, nullable: true}
|
||
destinationWarehouseId: {type: integer, format: int64, nullable: true}
|
||
destinationWarehouseName: {type: string, nullable: true}
|
||
inboundId: {type: integer, format: int64, nullable: true}
|
||
inboundVersion: {type: integer, nullable: true, description: C04 loading/complete 的 expectedVersion}
|
||
inboundCode: {type: string, nullable: true}
|
||
expectedShipDate: {type: string, format: date, nullable: true}
|
||
totalPackageCount: {type: integer, nullable: true, description: 无入仓事实时为当前订单有效货物箱数合计；存在入仓业务单元后为该单元履约总箱数，拆分后不以父单原始箱数覆盖}
|
||
recommendedPalletType: {type: string, nullable: true, description: 当前无列表级权威事实时返回 null，不得返回固定托盘类型}
|
||
locationCodes: {type: string, nullable: true}
|
||
actualGrossWeightKg: {type: number, nullable: true, description: Firstleg 实测毛重；来源 actualGrossWeightKg，不以净重回退}
|
||
actualVolumeCbm: {type: number, nullable: true}
|
||
expectedArrivalAt: {type: string, format: date-time, nullable: true}
|
||
feeReviewStatus: {type: string, nullable: true, description: Firstleg 入仓费用审核快照；财务状态不在本字段表达}
|
||
companyName: {type: string, nullable: true}
|
||
businessType: {type: string, nullable: true}
|
||
pickupMethod: {type: string, nullable: true}
|
||
requestedPickupAt: {type: string, format: date-time, nullable: true, description: Customer-requested pickup appointment from the pickup snapshot}
|
||
taxMode: {type: string, nullable: true}
|
||
containerMode: {type: string, nullable: true}
|
||
customsInspection: {type: boolean, nullable: true}
|
||
destinationType: {type: string, nullable: true}
|
||
destinationCode: {type: string, nullable: true}
|
||
totalPalletCount: {type: integer, nullable: true}
|
||
chargeableWeightKg: {type: number, nullable: true, description: Firstleg confirmed billing snapshot chargeable weight in kilograms}
|
||
chargeableVolumeCbm: {type: number, nullable: true}
|
||
volumetricWeightKg: {type: number, nullable: true}
|
||
totalNetWeightKg: {type: number, nullable: true, description: 统一订单货物净重展示字段；严格来源 Firstleg actualNetWeightKg，不以毛重回退}
|
||
measurementCompletedAt: {type: string, format: date-time, nullable: true}
|
||
inboundCompletedAt: {type: string, format: date-time, nullable: true}
|
||
expressCompany: {type: string, nullable: true}
|
||
expressTrackingNo: {type: string, nullable: true}
|
||
createdBy: {type: string, nullable: true}
|
||
skuNos: {type: array, nullable: true, items: {type: string}}
|
||
totalQuantity: {type: integer, nullable: true}
|
||
shipmentId: {type: string, nullable: true}
|
||
referenceId: {type: string, nullable: true}
|
||
measurement: {$ref: '#/components/schemas/UnifiedMeasurementSummary'}
|
||
preload: {$ref: '#/components/schemas/UnifiedPreloadSummary'}
|
||
loading: {$ref: '#/components/schemas/UnifiedLoadingSummary'}
|
||
delivery: {$ref: '#/components/schemas/UnifiedDeliverySummary'}
|
||
transport: {$ref: '#/components/schemas/UnifiedTransportSummary'}
|
||
customerRemark: {type: string, nullable: true}
|
||
latestInternalNote: {type: string, nullable: true, description: 客户详情不返回平台内部备注}
|
||
createdAt: {type: string, format: date-time, nullable: true}
|
||
updatedAt: {type: string, format: date-time, nullable: true}
|
||
UnifiedOrderRelation:
|
||
type: object
|
||
nullable: true
|
||
properties:
|
||
role: {type: string, enum: [PARENT, CHILD]}
|
||
rootOrderId: {type: integer, format: int64, nullable: true}
|
||
parentOrderId: {type: integer, format: int64, nullable: true}
|
||
splitSequence: {type: integer, nullable: true}
|
||
childCount: {type: integer, nullable: true}
|
||
UnifiedMeasurementSummary:
|
||
type: object
|
||
nullable: true
|
||
properties:
|
||
reviewStatus: {type: string, nullable: true}
|
||
actualGrossWeightKg: {type: number, nullable: true, description: Firstleg 实测毛重；不得使用净重回退}
|
||
actualVolumeCbm: {type: number, nullable: true}
|
||
chargeableWeightKg: {type: number, nullable: true}
|
||
completedAt: {type: string, format: date-time, nullable: true}
|
||
UnifiedPreloadSummary:
|
||
type: object
|
||
nullable: true
|
||
properties:
|
||
status: {type: string, nullable: true}
|
||
version: {type: integer, nullable: true}
|
||
itemCount: {type: integer, nullable: true}
|
||
updatedAt: {type: string, format: date-time, nullable: true}
|
||
UnifiedLoadingSummary:
|
||
type: object
|
||
nullable: true
|
||
properties:
|
||
status: {type: string, nullable: true}
|
||
loadingVersion: {type: integer, nullable: true, description: 当前为 pickingVersion 兼容别名}
|
||
pickingVersion: {type: integer, nullable: true}
|
||
expectedCount: {type: integer, nullable: true}
|
||
pickedCount: {type: integer, nullable: true}
|
||
evidenceCount: {type: integer, nullable: true}
|
||
sealNo: {type: string, nullable: true}
|
||
updatedAt: {type: string, format: date-time, nullable: true}
|
||
UnifiedDeliverySummary:
|
||
type: object
|
||
nullable: true
|
||
properties:
|
||
status: {type: string, nullable: true}
|
||
completedAt: {type: string, format: date-time, nullable: true}
|
||
trackingNo: {type: string, nullable: true}
|
||
UnifiedTransportSummary:
|
||
type: object
|
||
nullable: true
|
||
properties:
|
||
containerNo: {type: string, nullable: true}
|
||
cabinetNo: {type: string, nullable: true}
|
||
vesselName: {type: string, nullable: true}
|
||
voyageNo: {type: string, nullable: true}
|
||
estimatedSailingAt: {type: string, format: date-time, nullable: true, description: 当前关联柜次预计开船时间}
|
||
actualSailingAt: {type: string, format: date-time, nullable: true, description: 当前关联柜次实际开船时间}
|
||
effectiveSailingAt: {type: string, format: date-time, nullable: true, description: 实际开船时间优先，否则预计开船时间}
|
||
effectiveSailingAtEstimated: {type: boolean, nullable: true}
|
||
estimatedPortArrivalAt: {type: string, format: date-time, nullable: true, description: 当前关联柜次预计到港时间}
|
||
actualPortArrivalAt: {type: string, format: date-time, nullable: true, description: 当前关联柜次实际到港时间}
|
||
effectivePortArrivalAt: {type: string, format: date-time, nullable: true, description: 实际到港时间优先，否则预计到港时间}
|
||
effectivePortArrivalAtEstimated: {type: boolean, nullable: true}
|
||
UnifiedOrderTimelineEvent:
|
||
type: object
|
||
properties:
|
||
source: {type: string}
|
||
eventType: {type: string}
|
||
mainStatus: {$ref: '#/components/schemas/UnifiedMainStatus'}
|
||
action: {type: string, nullable: true}
|
||
remark: {type: string, nullable: true}
|
||
operatorId: {type: integer, format: int64, nullable: true}
|
||
operatorName: {type: string, nullable: true}
|
||
occurredAt: {type: string, format: date-time, nullable: true}
|
||
FulfillmentSplitQuantityLine:
|
||
type: object
|
||
required: [sourceDetailId, packageCount]
|
||
properties:
|
||
sourceDetailId: {type: integer, format: int64, minimum: 1}
|
||
packageCount: {type: integer, minimum: 1}
|
||
FulfillmentSplitCreateRequest:
|
||
type: object
|
||
required: [tenantId, parentOrderId, sourceOrderId, loadingPlanId, containerBookingId,
|
||
sourcePackageCount, loadedPackageCount, remainingPackageCount, idempotencyKey, lines]
|
||
properties:
|
||
tenantId: {type: integer, format: int64, minimum: 1}
|
||
parentOrderId: {type: integer, format: int64, minimum: 1}
|
||
sourceOrderId: {type: integer, format: int64, minimum: 1}
|
||
loadingPlanId: {type: integer, format: int64, minimum: 1}
|
||
containerBookingId: {type: integer, format: int64, minimum: 1}
|
||
sourcePackageCount: {type: integer, minimum: 1}
|
||
loadedPackageCount: {type: integer, minimum: 1}
|
||
remainingPackageCount: {type: integer, minimum: 0}
|
||
expectedParentVersion: {type: integer, minimum: 0, description: 可选；省略时仍在父订单行锁下串行拆分}
|
||
idempotencyKey: {type: string, minLength: 1, maxLength: 128}
|
||
operationId: {type: string, maxLength: 64}
|
||
operatorName: {type: string, maxLength: 64}
|
||
lines:
|
||
type: array
|
||
minItems: 1
|
||
items: {$ref: '#/components/schemas/FulfillmentSplitQuantityLine'}
|
||
FulfillmentSplitChild:
|
||
type: object
|
||
properties:
|
||
orderId: {type: integer, format: int64}
|
||
orderNo: {type: string}
|
||
splitSequence: {type: integer, minimum: 1}
|
||
splitRole: {type: string, enum: [LOADED, REMAINDER]}
|
||
packageCount: {type: integer, minimum: 1}
|
||
sourceOrderId: {type: integer, format: int64}
|
||
loadingPlanId: {type: integer, format: int64}
|
||
containerBookingId: {type: integer, format: int64}
|
||
FulfillmentSplitResponse:
|
||
type: object
|
||
properties:
|
||
parentOrderId: {type: integer, format: int64}
|
||
parentOrderNo: {type: string}
|
||
parentVersion: {type: integer, minimum: 0}
|
||
loadedChild:
|
||
allOf: [{$ref: '#/components/schemas/FulfillmentSplitChild'}]
|
||
description: 新写入时指向承接本次实装的来源订单本身；历史双子单仍返回原已装子订单
|
||
remainderChild:
|
||
allOf: [{$ref: '#/components/schemas/FulfillmentSplitChild'}]
|
||
nullable: true
|
||
description: 未装数量大于0时唯一创建的余量子订单；全部装完时为空
|
||
sourcePackageCount: {type: integer, minimum: 1}
|
||
loadedPackageCount: {type: integer, minimum: 1}
|
||
remainingPackageCount: {type: integer, minimum: 0}
|
||
loadingPlanId: {type: integer, format: int64}
|
||
containerBookingId: {type: integer, format: int64}
|
||
idempotencyKey: {type: string}
|
||
FulfillmentSplitTree:
|
||
type: object
|
||
properties:
|
||
parentOrderId: {type: integer, format: int64}
|
||
parentOrderNo: {type: string}
|
||
parentVersion: {type: integer, minimum: 0}
|
||
children:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/FulfillmentSplitChild'}
|
||
allocatedPackageCount: {type: integer, minimum: 0, deprecated: true}
|
||
remainingPackageCount: {type: integer, minimum: 0, deprecated: true}
|
||
originalPackageCount: {type: integer, minimum: 0, description: 根订单最初箱数}
|
||
cumulativeLoadedPackageCount: {type: integer, minimum: 0, description: 所有已完成来源分片累计实装箱数}
|
||
currentRemainderPackageCount: {type: integer, minimum: 0, description: 当前唯一有效余量箱数}
|
||
PricingTaxMode:
|
||
type: string
|
||
enum: [TAX_INCLUDED, TAX_EXCLUDED]
|
||
description: 报价包税维度；独立于订单 taxMode 的买单/退税语义
|
||
FirstLegOrderDraft:
|
||
type: object
|
||
required: [pricingTaxMode, cargoes]
|
||
properties:
|
||
fulfillmentType:
|
||
type: string
|
||
enum: [STANDARD, ONE_CLICK_DROPSHIP]
|
||
default: STANDARD
|
||
description: 独立履约类型；省略为普通头程，不复用业务/计费 businessType
|
||
inboundCode:
|
||
type: string
|
||
maxLength: 40
|
||
pattern: '^[A-Za-z0-9._:-]+$'
|
||
description: 仅 LEGACY_MANUAL 模式填写的旧系统入仓码；AUTO 模式必须省略
|
||
pricingTaxMode: {$ref: '#/components/schemas/PricingTaxMode'}
|
||
cargoes:
|
||
type: array
|
||
minItems: 1
|
||
items: {$ref: '#/components/schemas/FirstLegOrderCargo'}
|
||
description: >-
|
||
订单保存请求中的完整字段以服务端 FirstLegOrderSaveRequest 为准；fulfillmentType
|
||
省略时固定为 STANDARD，一键代发必须显式传 ONE_CLICK_DROPSHIP，且不复用计费 businessType；pricingTaxMode
|
||
是新建和编辑订单的必填报价维度；customerId 不接受客户端指定，服务端始终使用认证企业 ID；
|
||
发货单位和收货单位仅通过 sender/receiver 保存业务快照。历史存量订单的响应字段仍允许为空。
|
||
InboundCodePolicy:
|
||
type: object
|
||
required: [mode, manualEntryRequired]
|
||
properties:
|
||
mode: {type: string, enum: [AUTO, LEGACY_MANUAL]}
|
||
manualEntryRequired: {type: boolean}
|
||
FirstLegBatchDraftItem:
|
||
type: object
|
||
required: [clientRowId, draft]
|
||
properties:
|
||
clientRowId:
|
||
type: string
|
||
maxLength: 128
|
||
description: 前端外层行标识；同一批次内必须唯一，用于幂等重试和结果关联
|
||
draft:
|
||
$ref: '#/components/schemas/FirstLegOrderDraft'
|
||
FirstLegBatchDraftResponse:
|
||
type: object
|
||
required: [total, succeeded, failed, items]
|
||
properties:
|
||
total: {type: integer, minimum: 0}
|
||
succeeded: {type: integer, minimum: 0}
|
||
failed: {type: integer, minimum: 0}
|
||
items:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/FirstLegBatchDraftResult'}
|
||
FirstLegBatchDraftResult:
|
||
type: object
|
||
required: [index, success]
|
||
properties:
|
||
index: {type: integer, minimum: 0}
|
||
clientRowId: {type: string}
|
||
success: {type: boolean}
|
||
orderId: {type: string, pattern: '^[1-9][0-9]*$'}
|
||
orderNo: {type: string}
|
||
inboundCode: {type: string, pattern: '^[A-Za-z0-9._:-]+$', example: ZBYHK2608140001, description: AUTO 模式为渠道前缀+业务日期+全局票序；LEGACY_MANUAL 模式为录入的旧系统入仓码；履约拆分的子订单追加 splitSequence 后缀}
|
||
errorCode: {type: string}
|
||
errorMessage: {type: string}
|
||
FirstLegOrderCargo:
|
||
type: object
|
||
required: [skuNo, packageCount]
|
||
properties:
|
||
skuNo: {type: string, maxLength: 64}
|
||
cargoName: {type: string, maxLength: 128}
|
||
cargoNameEn: {type: string, maxLength: 128}
|
||
productImageFileId: {type: string, pattern: '^[1-9][0-9]*$'}
|
||
hsCode: {type: string, maxLength: 20, description: 报关 HS CODE}
|
||
customsHsCode: {type: string, maxLength: 20, description: 清关 HS CODE}
|
||
lengthCm: {type: number, minimum: 0, description: 箱规长（厘米）}
|
||
widthCm: {type: number, minimum: 0, description: 箱规宽（厘米）}
|
||
heightCm: {type: number, minimum: 0, description: 箱规高（厘米）}
|
||
unitsPerPackage: {type: integer, minimum: 1, description: 每箱数量}
|
||
packageCount: {type: integer, minimum: 1, description: 箱数}
|
||
grossWeightKg: {type: number, exclusiveMinimum: true, minimum: 0, description: 总毛重}
|
||
volumeCbm: {type: number, exclusiveMinimum: true, minimum: 0, description: 总体积}
|
||
totalQuantity: {type: integer, minimum: 1, description: 总数量}
|
||
netWeightKg: {type: number, exclusiveMinimum: true, minimum: 0, description: 总净重}
|
||
unitDeclaredValue: {type: number, minimum: 0, description: 清关申报单价（USD）}
|
||
declaredValue: {type: number, minimum: 0, description: 清关申报金额（USD）}
|
||
material: {type: string, maxLength: 128}
|
||
usage: {type: string, maxLength: 128}
|
||
model: {type: string, maxLength: 64}
|
||
brand: {type: string, maxLength: 64}
|
||
productLengthCm: {type: number, minimum: 0}
|
||
productWidthCm: {type: number, minimum: 0}
|
||
productHeightCm: {type: number, minimum: 0}
|
||
shipmentId: {type: string, maxLength: 64}
|
||
referenceId: {type: string, maxLength: 64}
|
||
upcNo: {type: string, maxLength: 64}
|
||
cargoRemark: {type: string, maxLength: 500}
|
||
packageType: {type: string, maxLength: 32}
|
||
dangerousGoods: {type: boolean}
|
||
description: >-
|
||
原型货物明细字段。FBA 货物的 skuNo、upcNo、shipmentId、referenceId 由服务端按每条货物校验；
|
||
productImageFileId 必须属于当前登录客户。
|
||
FirstLegOrderSummary:
|
||
type: object
|
||
properties:
|
||
orderId: {type: string, pattern: '^[1-9][0-9]*$'}
|
||
orderNo: {type: string}
|
||
inboundId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true}
|
||
inboundCode: {type: string}
|
||
channelName: {type: string}
|
||
destinationWarehouseName: {type: string}
|
||
status: {type: string}
|
||
packageCount: {type: integer}
|
||
expressCompany: {type: string}
|
||
trackingNo: {type: string}
|
||
skuNos: {type: string, description: 多个 SKU 使用中文顿号分隔}
|
||
totalGrossWeightKg: {type: number}
|
||
totalNetWeightKg: {type: number}
|
||
totalVolumeCbm: {type: number}
|
||
totalQuantity: {type: integer}
|
||
remark: {type: string}
|
||
shipmentId: {type: string}
|
||
referenceId: {type: string}
|
||
pricingTaxMode: {$ref: '#/components/schemas/PricingTaxMode'}
|
||
ContainerSlice:
|
||
type: object
|
||
properties:
|
||
containerBookingId: {type: string}
|
||
tenantId: {type: string}
|
||
parentOrderId: {type: string}
|
||
parentOrderNo: {type: string}
|
||
childOrderId: {type: string}
|
||
childOrderNo: {type: string}
|
||
sourceOrderId: {type: string}
|
||
sourceOrderNo: {type: string}
|
||
splitRole: {type: string, enum: [LOADED, REMAINDER]}
|
||
packageCount: {type: integer}
|
||
loadingPlanId: {type: string}
|
||
parameters:
|
||
InternalToken:
|
||
name: X-Internal-Service-Token
|
||
in: header
|
||
required: true
|
||
schema: {type: string, minLength: 1}
|
||
UnifiedKeyword:
|
||
name: keyword
|
||
in: query
|
||
required: false
|
||
schema: {type: string, maxLength: 64}
|
||
UnifiedOrderNo:
|
||
name: orderNo
|
||
in: query
|
||
required: false
|
||
schema: {type: string, maxLength: 64}
|
||
UnifiedMainStatus:
|
||
name: mainStatus
|
||
in: query
|
||
required: false
|
||
description: 统一订单七态主状态筛选；WAIT_SPLIT 与存量兼容状态 INBOUNDED 独立查询
|
||
schema:
|
||
type: string
|
||
enum: [PENDING_REVIEW, WAIT_MEASURE, INBOUNDED, LOADING, LOADED, DELIVERED, WAIT_SPLIT]
|
||
UnifiedInboundCode:
|
||
{name: inboundCode, in: query, required: false, description: 订单创建时生成的入仓码，所有订单状态均可查询, schema: {type: string, maxLength: 40}}
|
||
UnifiedInternalOrderStatus:
|
||
name: internalOrderStatus
|
||
in: query
|
||
required: false
|
||
description: Order 内部生命周期状态；不是七态产品主状态
|
||
schema: {type: string, enum: [DRAFT, SUBMITTED, APPROVED, ACCEPTED, REJECTED, CANCELLED, PROCESSING, COMPLETED]}
|
||
UnifiedExpectedArrivalDate:
|
||
{name: expectedArrivalDate, in: query, required: false, schema: {type: string, format: date}}
|
||
UnifiedFeeReviewStatus:
|
||
name: feeReviewStatus
|
||
in: query
|
||
required: false
|
||
description: 当前最高版本入库费用审核状态；UNRECORDED 表示尚无费用记录
|
||
schema: {type: string, enum: [UNRECORDED, PENDING, APPROVED, REJECTED]}
|
||
UnifiedChannelName:
|
||
{name: channelName, in: query, required: false, schema: {type: string, maxLength: 128}}
|
||
UnifiedContainerNo:
|
||
{name: containerNo, in: query, required: false, schema: {type: string, maxLength: 64}}
|
||
UnifiedCabinetNo:
|
||
{name: cabinetNo, in: query, required: false, schema: {type: string, maxLength: 64}}
|
||
UnifiedSailingDate:
|
||
{name: sailingDate, in: query, required: false, schema: {type: string, format: date}}
|
||
UnifiedLoaded:
|
||
name: loaded
|
||
in: query
|
||
required: false
|
||
description: true 表示运输装载状态存在且不是 UNLOADED/PENDING；false 表示无该状态
|
||
schema: {type: boolean}
|
||
UnifiedFullContainer:
|
||
name: fullContainer
|
||
in: query
|
||
required: false
|
||
description: true 对应 FULL_CONTAINER，false 对应 LCL
|
||
schema: {type: boolean}
|
||
UnifiedMeasurementReviewStatus:
|
||
name: measurementReviewStatus
|
||
in: query
|
||
required: false
|
||
description: 测量审核状态；UNRECORDED 表示字段为空
|
||
schema: {type: string, enum: [UNRECORDED, PENDING, APPROVED, REJECTED]}
|
||
UnifiedFbaCode:
|
||
name: fbaCode
|
||
in: query
|
||
required: false
|
||
description: 兼容匹配订单货物 sku_no
|
||
schema: {type: string, maxLength: 64}
|
||
UnifiedCreatedFrom:
|
||
name: createdFrom
|
||
in: query
|
||
required: false
|
||
description: 无主状态或待审核筛选按订单创建时间；其他主状态按履约快照创建时间
|
||
schema: {type: string, format: date-time}
|
||
UnifiedCreatedTo:
|
||
name: createdTo
|
||
in: query
|
||
required: false
|
||
description: 无主状态或待审核筛选按订单创建时间；其他主状态按履约快照创建时间
|
||
schema: {type: string, format: date-time}
|
||
UnifiedPage:
|
||
name: page
|
||
in: query
|
||
required: false
|
||
schema: {type: integer, minimum: 1, default: 1}
|
||
UnifiedSize:
|
||
name: size
|
||
in: query
|
||
required: false
|
||
schema: {type: integer, minimum: 1, maximum: 200, default: 20}
|
||
UnifiedOrderId:
|
||
name: orderId
|
||
in: path
|
||
required: true
|
||
schema: {type: string, pattern: '^[1-9][0-9]*$'}
|
||
UnifiedTenantId:
|
||
name: tenantId
|
||
in: query
|
||
required: true
|
||
schema: {type: string, pattern: '^[1-9][0-9]*$'}
|
||
TenantId:
|
||
name: tenantId
|
||
in: query
|
||
required: true
|
||
schema: {type: integer, format: int64}
|
||
OrderId:
|
||
name: id
|
||
in: path
|
||
required: true
|
||
schema: {type: integer, format: int64}
|
||
IdempotencyKey:
|
||
name: Idempotency-Key
|
||
in: header
|
||
required: true
|
||
description: 同一客户和操作者重试同一请求时必须保持不变
|
||
schema: {type: string, minLength: 1, maxLength: 128}
|