物流公司 API 文档
- 基础路径
/api/v1- ICAMS API
- API 0.3.0
- OpenAPI
- OpenAPI 3.1.0
接口目录
接口认证
调用物流公司接口时,在 x-api-key 请求头发送 API Key。各接口所需的权限见下方说明。
将 ICAMS_ORIGIN 设为部署地址,将 ICAMS_API_KEY 设为你的密钥。以下请求可以验证密钥并查看已授予的权限。
curl "$ICAMS_ORIGIN/api/v1/partner/session" \
-H "x-api-key: $ICAMS_API_KEY"使用 Accept-Language 请求头选择 zh-CN 或 en 错误文案。错误代码与语言无关。
接口参考
get/api/v1/health检查应用是否在线
响应
200应用可响应请求
application/json$ref: '#/components/schemas/HealthResponse'响应头
X-Request-Id:
$ref: '#/components/headers/RequestId'get/api/v1/health/ready检查 PostgreSQL 是否可用
响应
200数据库连接正常
application/json$ref: '#/components/schemas/HealthResponse'响应头
X-Request-Id:
$ref: '#/components/headers/RequestId'503数据库未配置或暂不可用
application/json$ref: '#/components/schemas/ErrorResponse'响应头
X-Request-Id:
$ref: '#/components/headers/RequestId'get/api/v1/openapi获取 OpenAPI 规范
响应
200YAML 格式的 OpenAPI 规范
application/yamltype: stringget/api/v1/partner/session验证 API Key 并读取公司名称与权限
响应
200当前 API Key 对应的公司与权限
application/jsonallOf:
- $ref: '#/components/schemas/Envelope'
- properties:
data:
type: object
required:
- companyId
- companyName
- scopes
properties:
companyId:
type: string
format: uuid
companyName:
type: string
scopes:
type: array
items:
enum:
- COURIERS_READ
- ORDERS_READ
- ORDERS_WRITE
- REIMBURSEMENTS_WRITE
- REIMBURSEMENTS_REVIEW
- SETTLEMENTS_WRITE其他状态码参数有误(400)、Key 无效(401)、Scope 不足(403)、订单不存在(404)、状态冲突(409)、飞人不可用(422)、限流(429)或服务暂不可用(500/503)。
application/json$ref: '#/components/schemas/ErrorResponse'响应头
X-Request-Id:
$ref: '#/components/headers/RequestId'get/api/v1/partner/couriers查询已注册的飞人
需要 COURIERS_READ。返回飞人 ID 和姓名。使用 q 时还会返回匹配飞人已生成的编码。
请求参数
offsetquery可选type: integer minimum: 0 maximum: 100000 default: 0limitquery可选type: integer minimum: 1 maximum: 100 default: 25qquery可选按姓名或飞人编码前缀查找。
type: string maxLength: 100
响应
200飞人列表
其他状态码参数有误(400)、Key 无效(401)、Scope 不足(403)、订单不存在(404)、状态冲突(409)、飞人不可用(422)、限流(429)或服务暂不可用(500/503)。
application/json$ref: '#/components/schemas/ErrorResponse'响应头
X-Request-Id:
$ref: '#/components/headers/RequestId'get/api/v1/partner/reimbursement-items查询本公司的报销项目目录
需要 ORDERS_WRITE。返回的项目 ID 可在创建订单时按顺序提交。
响应
200本公司的报销项目列表
application/jsonallOf:
- $ref: '#/components/schemas/Envelope'
- properties:
data:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
nameEn:
type:
- string
- 'null'
unitEnabled:
type: boolean
unit:
type:
- string
- 'null'
description:
type:
- string
- 'null'
descriptionEn:
type:
- string
- 'null'其他状态码参数有误(400)、Key 无效(401)、Scope 不足(403)、订单不存在(404)、状态冲突(409)、飞人不可用(422)、限流(429)或服务暂不可用(500/503)。
application/json$ref: '#/components/schemas/ErrorResponse'响应头
X-Request-Id:
$ref: '#/components/headers/RequestId'get/api/v1/partner/orders查询本公司订单
需要 ORDERS_READ。
请求参数
offsetquery可选type: integer minimum: 0 maximum: 100000 default: 0limitquery可选type: integer minimum: 1 maximum: 100 default: 25submittedquery可选为 true 时只查询有已提交报销单的订单。
type: booleanorderCodequery可选type: string minLength: 1 maxLength: 100externalIdquery可选旧版订单编码筛选参数。
type: string minLength: 1 maxLength: 100
响应
200订单列表
其他状态码参数有误(400)、Key 无效(401)、Scope 不足(403)、订单不存在(404)、状态冲突(409)、飞人不可用(422)、限流(429)或服务暂不可用(500/503)。
application/json$ref: '#/components/schemas/ErrorResponse'响应头
X-Request-Id:
$ref: '#/components/headers/RequestId'post/api/v1/partner/orders创建订单
需要 ORDERS_WRITE。新格式订单进入 PENDING_TRANSPORT。省略 courierIds 或传空数组可先保存订单,之后再指派飞人。订单编码在同一公司内唯一,相同内容重试返回已有记录,内容冲突返回 409。
请求体 必填
application/jsononeOf:
- $ref: '#/components/schemas/CreateOrder'
- $ref: '#/components/schemas/LegacyCreateOrder'响应
200订单明细
201订单明细
其他状态码参数有误(400)、Key 无效(401)、Scope 不足(403)、订单不存在(404)、状态冲突(409)、飞人不可用(422)、限流(429)或服务暂不可用(500/503)。
application/json$ref: '#/components/schemas/ErrorResponse'响应头
X-Request-Id:
$ref: '#/components/headers/RequestId'get/api/v1/partner/orders/{id}查看本公司订单及报销和结算明细
需要 ORDERS_READ。
请求参数
idpath必填type: string format: uuid
响应
200订单明细
其他状态码参数有误(400)、Key 无效(401)、Scope 不足(403)、订单不存在(404)、状态冲突(409)、飞人不可用(422)、限流(429)或服务暂不可用(500/503)。
application/json$ref: '#/components/schemas/ErrorResponse'响应头
X-Request-Id:
$ref: '#/components/headers/RequestId'put/api/v1/partner/orders/{id}/reimbursement-items设置订单的报销项目
需要 REIMBURSEMENTS_WRITE。订单开始运输和创建报销单之前可整体替换,空数组可清空。相同配置可安全重试。
请求参数
idpath必填type: string format: uuid
请求体 必填
application/jsontype: object
additionalProperties: false
required:
- items
properties:
items:
type: array
maxItems: 20
items:
type: object
additionalProperties: false
required:
- name
properties:
name:
type: string
minLength: 1
maxLength: 80
maxAmount:
$ref: '#/components/schemas/MoneyInput'响应
200订单明细
其他状态码参数有误(400)、Key 无效(401)、Scope 不足(403)、订单不存在(404)、状态冲突(409)、飞人不可用(422)、限流(429)或服务暂不可用(500/503)。
application/json$ref: '#/components/schemas/ErrorResponse'响应头
X-Request-Id:
$ref: '#/components/headers/RequestId'patch/api/v1/partner/orders/{id}/status更新本公司订单运输进度
需要 ORDERS_WRITE,仅可更新本公司订单。旧版 OPEN 订单须先设为 PENDING_TRANSPORT。随后按 IN_TRANSIT、COMPLETED 顺序流转。开始运输前须指派至少一名飞人。提交相同状态可安全重试。
请求参数
idpath必填type: string format: uuid
请求体 必填
application/jsontype: object
additionalProperties: false
required:
- status
properties:
status:
enum:
- PENDING_TRANSPORT
- IN_TRANSIT
- COMPLETED响应
200订单明细
其他状态码参数有误(400)、Key 无效(401)、Scope 不足(403)、订单不存在(404)、状态冲突(409)、飞人不可用(422)、限流(429)或服务暂不可用(500/503)。
application/json$ref: '#/components/schemas/ErrorResponse'响应头
X-Request-Id:
$ref: '#/components/headers/RequestId'post/api/v1/partner/orders/{id}/cancel取消本公司的待接单订单
需要 ORDERS_WRITE。重复取消返回已有结果。
请求参数
idpath必填type: string format: uuid
响应
200订单明细
其他状态码参数有误(400)、Key 无效(401)、Scope 不足(403)、订单不存在(404)、状态冲突(409)、飞人不可用(422)、限流(429)或服务暂不可用(500/503)。
application/json$ref: '#/components/schemas/ErrorResponse'响应头
X-Request-Id:
$ref: '#/components/headers/RequestId'patch/api/v1/partner/orders/{id}/assignment指派或调整本公司订单的飞人
需要 ORDERS_WRITE。待运输且尚未填写报销单的订单可以指派或调整飞人。
请求参数
idpath必填type: string format: uuid
请求体 必填
application/jsontype: object
additionalProperties: false
required:
- courierIds
properties:
courierIds:
allOf:
- $ref: '#/components/schemas/CreateOrder/properties/courierIds'
- minItems: 1响应
200订单明细
其他状态码参数有误(400)、Key 无效(401)、Scope 不足(403)、订单不存在(404)、状态冲突(409)、飞人不可用(422)、限流(429)或服务暂不可用(500/503)。
application/json$ref: '#/components/schemas/ErrorResponse'响应头
X-Request-Id:
$ref: '#/components/headers/RequestId'patch/api/v1/partner/orders/{id}/reimbursement审核本公司订单的报销单
需要 REIMBURSEMENTS_REVIEW。提交报销单当前版本号。订单有多张已提交报销单时须指定 reportId。审核失败时必须填写审核说明。
请求参数
idpath必填type: string format: uuid
请求体 必填
application/jsontype: object
required:
- revision
- decision
- reviewNote
properties:
reportId:
type: string
format: uuid
revision:
type: integer
minimum: 0
decision:
enum:
- APPROVED
- REJECTED
reviewNote:
type: string
maxLength: 500响应
200订单明细
其他状态码参数有误(400)、Key 无效(401)、Scope 不足(403)、订单不存在(404)、状态冲突(409)、飞人不可用(422)、限流(429)或服务暂不可用(500/503)。
application/json$ref: '#/components/schemas/ErrorResponse'响应头
X-Request-Id:
$ref: '#/components/headers/RequestId'get/api/v1/partner/orders/{id}/settlement查询待打款金额及指定飞人的收款信息
需要 SETTLEMENTS_WRITE。订单须已完成,报销须审核通过,且提交报销单的飞人须完成收款设置。历史共用报销单可从已指派飞人中选择收款人。订单有多张已提交报销单时须指定 reportId。
请求参数
idpath必填type: string format: uuidreportIdquery可选type: string format: uuidpayeeIdquery必填type: string format: uuid
响应
200收款信息与各币种应付金额
application/jsonallOf:
- $ref: '#/components/schemas/Envelope'
- properties:
data:
type: object
required:
- payment
- totals
- includeServiceFee
properties:
includeServiceFee:
type: boolean
payment:
type: object
properties:
method:
enum:
- BANK_CARD
- ALIPAY
account:
type: string
bankName:
type:
- string
- 'null'
currency:
type: string
totals:
type: array
items:
$ref: '#/components/schemas/CurrencyTotal'其他状态码参数有误(400)、Key 无效(401)、Scope 不足(403)、订单不存在(404)、状态冲突(409)、飞人不可用(422)、限流(429)或服务暂不可用(500/503)。
application/json$ref: '#/components/schemas/ErrorResponse'响应头
X-Request-Id:
$ref: '#/components/headers/RequestId'post/api/v1/partner/orders/{id}/settlement物流公司确认线下打款并结算飞人
需要 SETTLEMENTS_WRITE。订单完成且报销通过审核后可确认打款。订单有多张已提交报销单时须指定 reportId。服务费计入首笔结算。对同一报销单使用相同收款飞人和凭证重试会返回原结算。凭证冲突返回 409。
请求参数
idpath必填type: string format: uuid
请求体 必填
application/jsontype: object
additionalProperties: false
required:
- payeeId
- reference
properties:
reportId:
type: string
format: uuid
includeServiceFee:
type: boolean
description: 可回传预览返回的值。服务费计入状态变化时会返回 409。
payeeId:
type: string
format: uuid
reference:
type: string
minLength: 1
maxLength: 100multipart/form-datatype: object
additionalProperties: false
required:
- payeeId
- reference
properties:
reportId:
type: string
format: uuid
includeServiceFee:
type: boolean
description: 可回传预览返回的值。服务费计入状态变化时会返回 409。
payeeId:
type: string
format: uuid
reference:
type: string
minLength: 1
maxLength: 100
paymentProof:
type: string
format: binary
description: 可选的打款凭证图片,最大 5 MB。响应
200订单明细
其他状态码参数有误(400)、Key 无效(401)、Scope 不足(403)、订单不存在(404)、状态冲突(409)、飞人不可用(422)、限流(429)或服务暂不可用(500/503)。
application/json$ref: '#/components/schemas/ErrorResponse'响应头
X-Request-Id:
$ref: '#/components/headers/RequestId'get/api/v1/partner/settlements/{id}/payment-proof查看打款凭证图片
需要 SETTLEMENTS_WRITE,仅可查看本公司的结算凭证。使用结算记录 ID 查询。图片以 JPEG 格式返回。
请求参数
idpath必填type: string format: uuid
响应
200打款凭证图片
image/jpeg其他状态码参数有误(400)、Key 无效(401)、Scope 不足(403)、订单不存在(404)、状态冲突(409)、飞人不可用(422)、限流(429)或服务暂不可用(500/503)。
application/json$ref: '#/components/schemas/ErrorResponse'响应头
X-Request-Id:
$ref: '#/components/headers/RequestId'数据模型
Envelope
type: object
required:
- requestId
- data
properties:
requestId:
type: string
format: uuidMoneyInput
type: string
pattern: ^(0|[1-9][0-9]{0,8})(\.[0-9]{1,2})?$
examples:
- '12.30'Money
type: string
pattern: ^(0|[1-9][0-9]*)\.[0-9]{2}$Courier
type: object
required:
- id
- name
properties:
id:
type: string
format: uuid
name:
type: string
code:
type: string
description: 查询时返回已生成的飞人编码。CreateOrder
type: object
additionalProperties: false
required:
- orderCode
- departureAirport
- destinationAirport
- cargoQuantity
properties:
orderCode:
type: string
minLength: 1
maxLength: 100
courierIds:
type: array
maxItems: 100
uniqueItems: true
items:
type: string
format: uuid
departureAirport:
type: string
pattern: ^[A-Za-z]{3}$
examples:
- PVG
destinationAirport:
type: string
pattern: ^[A-Za-z]{3}$
examples:
- NRT
cargoQuantity:
type: integer
minimum: 1
maximum: 1000000
notes:
type: string
maxLength: 500
default: ''
reimbursementItemIds:
description: 从本公司目录勾选的项目 ID,按订单填报顺序提交。与非空 reimbursementItems 互斥。
type: array
minItems: 1
maxItems: 20
uniqueItems: true
items:
type: string
format: uuid
reimbursementItems:
type: array
maxItems: 20
default: []
items:
type: object
additionalProperties: false
required:
- name
properties:
name:
type: string
minLength: 1
maxLength: 80
maxAmount:
$ref: '#/components/schemas/MoneyInput'
serviceFee:
$ref: '#/components/schemas/MoneyInput'
default: '0'
serviceFeeCurrency:
allOf:
- $ref: '#/components/schemas/CurrencyInput'
description: 服务费大于零时必填。LegacyCreateOrder
description: 旧版单飞人建单格式,继续进入 OPEN,由公司设为 PENDING_TRANSPORT 或取消。
type: object
additionalProperties: false
required:
- courierId
- externalId
- description
properties:
courierId:
type: string
format: uuid
externalId:
type: string
minLength: 1
maxLength: 100
description:
type: string
minLength: 1
maxLength: 500
serviceFee:
$ref: '#/components/schemas/MoneyInput'
default: '0'CurrencyInput
type: string
enum:
- USD
- CNY
- HKDCurrency
type:
- string
- 'null'
pattern: ^[A-Z]{3}$
description: 历史记录可能返回其他原有币种,缺少币种时为空。
examples:
- USD
- CNY
- HKDNullableMoney
anyOf:
- $ref: '#/components/schemas/Money'
- type: 'null'Order
type: object
required:
- id
- orderCode
- companyId
- companyName
- couriers
- courierIds
- departureAirport
- destinationAirport
- cargoQuantity
- notes
- status
- reimbursementItems
- reimbursement
- settlement
properties:
id:
type: string
format: uuid
orderCode:
type: string
externalId:
type: string
description: 旧版订单编码字段。
companyId:
type: string
format: uuid
companyName:
type: string
couriers:
type: array
items:
$ref: '#/components/schemas/Courier'
courierIds:
type: array
items:
type: string
format: uuid
courierId:
type: string
format: uuid
description: 仅在单飞人订单中返回。
courierName:
type: string
description: 仅在单飞人订单中返回。
departureAirport:
type:
- string
- 'null'
destinationAirport:
type:
- string
- 'null'
cargoQuantity:
type:
- integer
- 'null'
minimum: 1
notes:
type: string
description:
type: string
description: 旧版订单备注字段。
status:
enum:
- OPEN
- PENDING_TRANSPORT
- IN_TRANSIT
- COMPLETED
- CANCELLED
serviceFee:
$ref: '#/components/schemas/Money'
serviceFeeCurrency:
$ref: '#/components/schemas/Currency'
createdAt:
type: string
format: date-time
acceptedAt:
type:
- string
- 'null'
format: date-time
submittedAt:
type:
- string
- 'null'
format: date-time
reimbursementItems:
$ref: '#/components/schemas/ReimbursementItems'
items:
$ref: '#/components/schemas/ReimbursementItems'
reimbursements:
type: array
items:
$ref: '#/components/schemas/Reimbursement'
settlements:
type: array
items:
$ref: '#/components/schemas/Settlement'
reimbursement:
description: 仅有一张可见报销单时返回该记录。
anyOf:
- $ref: '#/components/schemas/Reimbursement'
- type: 'null'
settlement:
anyOf:
- $ref: '#/components/schemas/Settlement'
- type: 'null'ReimbursementItems
type: array
items:
type: object
required:
- id
- name
- maxAmount
properties:
id:
type: string
format: uuid
name:
type: string
nameEn:
type:
- string
- 'null'
unitEnabled:
type:
- boolean
- 'null'
unit:
type:
- string
- 'null'
description:
type:
- string
- 'null'
descriptionEn:
type:
- string
- 'null'
position:
type: integer
minimum: 0
maxAmount:
$ref: '#/components/schemas/NullableMoney'Reimbursement
type: object
required:
- id
- courierId
- courierName
- status
- revision
- note
- reviewNote
- submittedAt
- lines
- settlement
properties:
id:
type: string
format: uuid
courierId:
type:
- string
- 'null'
format: uuid
courierName:
type:
- string
- 'null'
submittedAt:
type:
- string
- 'null'
format: date-time
settlement:
anyOf:
- $ref: '#/components/schemas/Settlement'
- type: 'null'
status:
enum:
- DRAFT
- UNDER_REVIEW
- REJECTED
- APPROVED
- SETTLED
revision:
type: integer
minimum: 0
note:
type:
- string
- 'null'
reviewNote:
type:
- string
- 'null'
lines:
type: array
items:
type: object
required:
- id
- itemName
- quantity
- amount
- currency
- note
properties:
id:
type: string
format: uuid
itemName:
type: string
quantity:
type: integer
minimum: 1
amount:
$ref: '#/components/schemas/Money'
currency:
$ref: '#/components/schemas/Currency'
note:
type:
- string
- 'null'Settlement
type: object
required:
- id
- payeeId
- paymentReference
- hasPaymentProof
- serviceFee
- reimbursement
- total
- currencyTotals
- createdAt
properties:
id:
type: string
format: uuid
reimbursementId:
type:
- string
- 'null'
format: uuid
payeeId:
type:
- string
- 'null'
format: uuid
paymentReference:
type:
- string
- 'null'
hasPaymentProof:
type: boolean
serviceFee:
$ref: '#/components/schemas/NullableMoney'
reimbursement:
$ref: '#/components/schemas/NullableMoney'
total:
$ref: '#/components/schemas/NullableMoney'
currencyTotals:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/CurrencyTotal'
createdAt:
type: string
format: date-timeCurrencyTotal
HealthResponse
type: object
required:
- data
- requestId
properties:
data:
type: object
required:
- status
properties:
status:
type: string
enum:
- ok
- ready
requestId:
type: string
format: uuidErrorResponse
type: object
required:
- error
- requestId
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
message:
type: string
requestId:
type: string
format: uuid