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}