323 lines
15 KiB
YAML
323 lines
15 KiB
YAML
openapi: 3.0.3
|
||
info:
|
||
title: 柏悦头程订单 API
|
||
description: 业务成功和失败均使用 HTTP 200；仅响应体 code 为字符串 "200" 时表示成功，其他 code 表示失败。
|
||
version: 1.3.0
|
||
security:
|
||
- bearerAuth: []
|
||
paths:
|
||
/api/platform/v1/orders:
|
||
get:
|
||
summary: 平台统一订单列表
|
||
description: >-
|
||
统一返回七态产品主状态、下一步动作及测量/预装/装柜/派送摘要，需要 platform:order:list。
|
||
有入库单时同时返回 inboundId、inboundVersion、loadingVersion、pickingVersion；inboundVersion
|
||
才是 C04 loading/complete 的 expectedVersion，loadingVersion 当前等于 pickingVersion（兼容别名）。
|
||
tenantId 省略时跨全部客户；mainStatus 省略时按订单创建时间分页，指定 PENDING_REVIEW 时由 Order 查询，
|
||
指定其他主状态时由 Firstleg 精确分页。旧 /orders/first-leg 接口保持兼容。
|
||
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 时成功}
|
||
'403': {description: 需要平台身份和 platform:order:list 权限}
|
||
/api/platform/v1/orders/{orderId}:
|
||
get:
|
||
summary: 平台统一订单详情
|
||
description: 合并 Order 与 Firstleg 时间线并按发生时间升序返回；平台可见内部备注。
|
||
parameters:
|
||
- $ref: '#/components/parameters/UnifiedOrderId'
|
||
- $ref: '#/components/parameters/UnifiedTenantId'
|
||
responses:
|
||
'200': {description: 成功或业务失败，按响应体 code 判断}
|
||
'403': {description: 需要平台身份和 platform:order:list 权限}
|
||
/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 判断}
|
||
'403': {description: 需要 merchant:order:list 权限}
|
||
/api/merchant/v1/orders/{orderId}:
|
||
get:
|
||
summary: 客户统一订单详情
|
||
description: 仅返回登录客户所属订单及客户可见时间线，不返回平台内部备注。
|
||
parameters:
|
||
- $ref: '#/components/parameters/UnifiedOrderId'
|
||
responses:
|
||
'200': {description: 成功或业务失败，按响应体 code 判断}
|
||
'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}
|
||
post:
|
||
summary: 创建订单草稿
|
||
parameters:
|
||
- $ref: '#/components/parameters/IdempotencyKey'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema: {type: object}
|
||
responses:
|
||
'200': {description: 成功或业务失败，按响应体 code 判断}
|
||
/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: {type: object}
|
||
responses:
|
||
'200': {description: 成功或业务失败，按响应体 code 判断}
|
||
'403': {description: 需要 platform:order:create 权限}
|
||
/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: {type: object}
|
||
responses:
|
||
'200': {description: 成功或业务失败，按响应体 code 判断}
|
||
'403': {description: 需要 platform:order:edit 权限}
|
||
components:
|
||
securitySchemes:
|
||
bearerAuth:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: JWT
|
||
parameters:
|
||
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
|
||
schema:
|
||
type: string
|
||
enum: [PENDING_REVIEW, WAIT_MEASURE, INBOUNDED, WAIT_SPLIT, LOADING, LOADED, DELIVERED]
|
||
UnifiedInboundCode:
|
||
{name: inboundCode, in: query, required: false, schema: {type: string, maxLength: 64}}
|
||
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}
|