订单外部追踪
订单外部追踪接口供客户系统接入并修改oTMS订单状态 (提货/送货) ,修改订单状态为送货的同时,支持上传Epod。客户系统发送包含oTMS订单名称等修改状态请求,可以支持多条订单同时请求但多条订单不支持上传Epod。支持送货状态下的订单单独上传EPOD (EPOD_UPLOAD) 操作。支持对订单进行投诉 (Exception_H) 操作,在投诉的同时可以选择上传附件,附件使用 BASE64编码。支持对订单进行记录在途事件 (Exception_B) 操作。支持对订单注册到达中转站 (AH) 或离开中转站 (LH) 操作。
| 版本号 | 文档 | 说明 |
|---|---|---|
| 0.1 | 当前版本文档 |
oTMS同时在生产环境和测试环境中提供Web Service接口,其中测试环境用于集成测试。两种环境下都需要由oTMS系统管理员分配API帐号密码后方可使用。
注意: 请合理地调用公共接口。如果发现存在异常调用或者对我们系统性能造成影响等情况,会对API账号的调用进行限制,甚至停用。
目前对该接口的调用限制为每个公司每秒最多30个请求
注意: 请合理地调用公共接口。如果发现存在异常调用或者对我们系统性能造成影响等情况,会对API账号的调用进行限制,甚至停用。
目前对该接口的调用限制为每个公司每秒最多30个请求
目前对该接口的调用限制为每个公司每秒最多30个请求
公共参数
| 环境 | HTTP请求方法 | HTTPS请求地址 | 请求主体MIME类型 | 响应主体MIME类型 |
|---|---|---|---|---|
| 正式环境 | POST | https://login.otms.cn/ws/externalTrackandTrace | application/xml | application/xml |
| 沙箱环境 | POST | https://demo.otms.cn/ws/externalTrackandTrace | application/xml | application/xml |
请求参数
| 字段名 | 位置 | 是否必填 | 描述 | Schema |
|---|---|---|---|---|
| Authorization | header | Basic Authorization。如果不为空,则优先使用该值作身份认证。否则使用请求报文中的用户名与密码 | string | |
| body | body | 是 | 订单查询请求中包含用以筛选订单的查询条件。 | ExternalTrackAndTraceRequest |
响应参数
| 状态码 | 描述 | 响应模型 |
|---|---|---|
| 200 | successful operation | ExternalTrackAndTraceResponse |
Attachment
| 字段名 | 类型 | 是否必填 | 描述 | 示例 |
|---|---|---|---|---|
| fileName | string | 是 | 文件名 | |
| content | string | 是 | 文件Base64编码 | |
| fileId | string | 是 | 文件地址,调用文件上传接口获得。仅注册在途事件使用 |
Attachments
| 字段名 | 类型 | 是否必填 | 描述 | 示例 |
|---|---|---|---|---|
| attachment | array[Attachment] | 否 | 附件内容 |
ExternalDiscrepancyDto
| 字段名 | 类型 | 是否必填 | 描述 | 示例 |
|---|---|---|---|---|
| productCode | string | 否 | 货物代码 | |
| productName | string | 否 | 货物名称 | |
| unit | string | 否 | 货物单位 | |
| unitPrice | number (double) | 否 | 订单行的货差信息 | |
| damage | number | 否 | 货物破损数量 | |
| shortage | number | 否 | 货物缺失数量 | |
| orderLineId | integer (int64) | 否 | 订单行Id | |
| sequence | integer (int32) | 否 | 请求序列号 | |
| quantity | integer (int32) | 否 | 数量 |
ExternalEpodInfo
| 字段名 | 类型 | 是否必填 | 描述 | 示例 |
|---|---|---|---|---|
| fileName | string | 是 | 上传epod的文件名 | |
| content | string | 是 | Epod文件经过BASE64编码之后的字符 |
ExternalEpods
| 字段名 | 类型 | 是否必填 | 描述 | 示例 |
|---|---|---|---|---|
| externalEpodInfos | array[ExternalEpodInfo] | 否 | - |
ExternalOrderException
| 字段名 | 类型 | 是否必填 | 描述 | 示例 |
|---|---|---|---|---|
| discrepancyOperationType | string | 否 | 货差操作类型,包括如下常量: REGISTER - 新注册货损货差 UPDATE - 更新货损报告 REJECT - 撤销货损报告 |
|
| remark | string | 否 | 异常描述 | |
| claimTo | string | 否 | 投诉异常对象类型,包括如下常量: CLIENT VENDOR |
|
| eventDate | string | 否 | 事件发生时间 | |
| eventReason | string | 否 | 在途事件发生原因/赔偿原因类型/货差类型 | |
| charge | number | 否 | 注册特殊费用金额 | |
| truckPlate | string | 否 | 注册AH/LH/CP所需车牌号 | |
| driverMobile | string | 否 | 注册CP所需司机手机号 | |
| hub | string | 否 | 注册AH/LH所需中转站名称 | |
| boxes | integer (int32) | 否 | 注册AH/LH所需扫描箱数 | |
| attachments | Attachments | 否 | 上传的附件 | |
| compensation | ImportedOrderCompensation | 否 | 上传的赔偿 | |
| rejection | ImportedOrderRejection | 否 | 上传的拒收 | |
| orderLines | array[ExternalDiscrepancyDto] | 否 | 订单行破损丢失信息 | |
| discrepancies | array[ExternalDiscrepancyDto] | 否 | SKU破损丢失信息 |
ExternalOrderInfo
| 字段名 | 类型 | 是否必填 | 描述 | 示例 |
|---|---|---|---|---|
| eventDate | string (date-time) | 否 | 订单更新时间 | |
| latitude | number (double) | 否 | 订单更新坐标维度 | |
| longitude | number (double) | 否 | 订单更新坐标经度 |
ExternalOrderQueries
| 字段名 | 类型 | 是否必填 | 描述 | 示例 |
|---|---|---|---|---|
| query | ExternalOrderQuery | 是 | 订单请求查询条件 |
ExternalOrderQuery
| 字段名 | 类型 | 是否必填 | 描述 | 示例 |
|---|---|---|---|---|
| attribute | string | 是 | 查询条件的属性名。可以取下列值: orderNumber - oTMS订单号 erpNumber - ERP单号 |
|
| eq | string | 否 | - | |
| ge | string | 否 | 属性值大于或等于该值 | |
| le | string | 否 | 属性值小于或等于该值 | |
| in | In | 否 | 属性值包含于该列表中。不支持日期/时间类型的属性 | |
| lk | string | 否 | 属性值模糊匹配该值 |
ExternalTrackAndTraceRequest
| 字段名 | 类型 | 是否必填 | 描述 | 示例 |
|---|---|---|---|---|
| version | string | 否 | 请求的版本号 | |
| login | string | 否 | 用户名。用于 API 调用者身份认证。如果请求头中的Authorization不为空,则该值会被忽略。 | |
| password | string | 否 | 密码。用于 API 调用者身份认证。如果请求头中的Authorization不为空,则该值会被忽略。 | |
| operation | string | 是 | 订单更新状态类型。可选的值: PICKUP - 提货 DELIVERY - 送货 EXCEPTION_H - 投诉 EXCEPTION_B - 在途事件 EXCEPTION_G1 - 特殊费用 EVENT_CP - 提货签到 EPOD_UPLOAD - 上传EPOD CARGO_DISCREPANCY - 货差 COMPENSATION - 赔偿 AH - 到达中转站 LH - 离开中转站 REJECT - 拒收 |
|
| externalOrderQueries | ExternalOrderQueries | 是 | 订单请求查询条件 | |
| externalOrderInfo | ExternalOrderInfo | 否 | 订单更新内容 | |
| externalEpods | ExternalEpods | 否 | 需要上传的Epod | |
| externalOrderException | ExternalOrderException | 否 | 注册异常/事件 |
ExternalTrackAndTraceResponse
| 字段名 | 类型 | 是否必填 | 描述 | 示例 |
|---|---|---|---|---|
| succeedCount | integer (int32) | 否 | 成功数量 | |
| results | Results | 否 | 操作结果 |
ImportedOrderCompensation
| 字段名 | 类型 | 是否必填 | 描述 | 示例 |
|---|---|---|---|---|
| compensationBasis | string | 是 | 索赔类型,包括如下常量: INSURANCE DISCREPANCY NONE |
|
| compensationType | string | 是 | 索赔方式,包括如下常量: TOTAL SKU |
|
| driverPhoneNumber | string | 否 | 司机手机号 | |
| compensationObjective | integer (int32) | 否 | 索赔对象,包括如下常量: 0 - 客户 1 - 承运商 2 - 司机 |
|
| totalCompensation | number | 否 | 索赔总额 | |
| orderLineCompensations | array[ImportedOrderLineCompensation] | 否 | Sku 赔偿信息 |
ImportedOrderLineCompensation
| 字段名 | 类型 | 是否必填 | 描述 | 示例 |
|---|---|---|---|---|
| productCode | string | 是 | 货物/产品代码 | |
| productName | string | 是 | 货物/产品名称 | |
| productUnit | string | 是 | 货物/产品单位 | |
| damageQuantity | number | 否 | 货物/产品破损的数量 | |
| shortageQuantity | number | 否 | 货物/产品短少的数量 | |
| damageUnitPrice | number | 否 | 货物/产品破损的单价 | |
| shortageUnitPrice | number | 否 | 货物/产品短少的单价 |
ImportedOrderLineRejection
| 字段名 | 类型 | 是否必填 | 描述 | 示例 |
|---|---|---|---|---|
| productCode | string | 否 | 货物/产品代码 | |
| productName | string | 是 | 货物/产品名称 | |
| productUnit | string | 否 | 货物/产品单位 | |
| rejection | number | 是 | 货物/产品拒收的数量 |
ImportedOrderRejection
| 字段名 | 类型 | 是否必填 | 描述 | 示例 |
|---|---|---|---|---|
| comments | string | 否 | 拒收说明 | |
| reason | string | 否 | 拒收原因 | |
| totalRejection | number | 否 | 总拒收数量 | |
| orderLineRejections | array[ImportedOrderLineRejection] | 否 | Sku 拒收信息 |
In
| 字段名 | 类型 | 是否必填 | 描述 | 示例 |
|---|---|---|---|---|
| value | array[string] | 是 | 属性值 |
Result
| 字段名 | 类型 | 是否必填 | 描述 | 示例 |
|---|---|---|---|---|
| sequence | integer (int32) | 否 | 操作结果序列号 | |
| orderNumber | string | 否 | 订单号 | |
| erpNumber | string | 否 | erp单号 | |
| productCode | string | 否 | 货物代码 | |
| productName | string | 否 | 货物名称 | |
| status | string | 否 | 状态 | |
| epodStatus | string | 否 | 上传的epod状态 | |
| epodErrCode | string | 否 | 上传epod错误码 | |
| errCode | string | 否 | 错误码 | |
| attachmentStatus | string | 否 | 上传附件状态 | |
| attachmentErrCode | string | 否 | 上传附件错误码 |
Results
| 字段名 | 类型 | 是否必填 | 描述 | 示例 |
|---|---|---|---|---|
| result | array[Result] | 否 | 操作结果信息 |
请求示例
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!--投诉异常H请求报文-->
<externalTrackAndTraceRequest version="0.1" login="username" password="password">
<operation>EXCEPTION_H</operation>
<externalOrderQueries>
<externalOrderQuery>
<attribute>orderNumber</attribute>
<eq>SH00105072660</eq>
</externalOrderQuery>
</externalOrderQueries>
<externalOrderException>
<remark>posse-SH00105072660</remark>
<claimTo>CLIENT</claimTo>
<attachments>
<attachment>
<fileName>test.jpg</fileName>
<content>/9j/4AAQSkZJRgATV+CaXYp5IOfrRRWhB//2Q==</content>
</attachment>
</attachments>
</externalOrderException>
</externalTrackAndTraceRequest>
响应示例
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!--投诉异常响应报文 (含附件:投诉成功,附件上传失败) -->
<externalTrackAndTraceResponse>
<succeedCount>1</succeedCount>
<results>
<result sequence="1">
<orderNumber>KY99000015</orderNumber>
<status>SUCCEED</status>
<attachmentStatus>FAILED</attachmentStatus>
<attachmentErrCode>3016</attachmentErrCode>
</result>
</results>
</externalTrackAndTraceResponse>
全局反馈代码
| 反馈代码 | 说明 |
| 0 | 客户验证失败。 |
单个请求反馈代码
| 反馈代码 | 说明 |
| 3001 | 订单状态错误。提货操作,订单必须已经被分配。送达操作,订单必须被提货。 |
| 3002 | 订单的提货或送货操作只有此订单所有者有权限。 |
| 3003 | 订单已经被分配给承运商,不允许进行提货/送货操作。 |
| 3004 | 订单被拆分,不允许提货/送货。 |
| 3005 | 不能够找到任何订单。 |
| 3006 | 订单送达失败。 |
| 3007 | 订单注册异常失败。 |
| 3008 | 请求信息缺少externalOrderException节点信息。 |
| 3009 | 请求缺少remark节点信息。 |
| 3010 | 请求缺少claimTo节点。 |
| 3011 | 订单状态错误(非pickup)。 |
| 3012 | 不能投诉货主。 |
| 3013 | 不能投诉承运商。 |
| 3014 | 不能转换操作节点,无效的操作类型。 |
| 3015 | 如果存在附件信息,fileName和content信息不能为空。 |
| 3016 | 如果存在附件信息,fileType只能是jpg, jpeg, png, pdf, doc, docx, xls, xlsx, zip, rar。 |
| 3017 | 如果存在附件信息,文件需要小于50M。 |
| 3018 | 上传附件时发生未知错误。 |
| 3019 | 缺少eventDate节点信息。 |
| 3020 | event date格式错误(2016-8-8T12:12:12)。 |
| 3021 | 缺少charge节点。 |
| 3022 | 订单关单和超时。 |
| 3023 | 订单的文件附件中缺少fileId或fileName。 |
| 3100 | 上传Epod操作,Epod最大不能超过10M限制。 |
| 3101 | 订单需要epod信息,但是没有找到epod信息。 |
| 3102 | Epod缺失,可能发生服务器内部错误。 |
| 3103 | Epod上传失败。 |
| 3104 | 订单需要Epod信息,但是Epod节点内容为空。 |
| 3105 | 不支持同时对多订单上传Epod。 |
| 3106 | Epod内容超过100KB限制。 |
| 3107 | 货主不允许上传Epod。 |
| 3108 | 订单是拆分订单,只有最后一段拆分子订单允许上传Epod。 |
| 3109 | Epod文件类型只能是jpg, jpeg, png, pdf, doc, docx, xls, xlsx, zip, rar。 |
| 3030 | 订单所注册的异常总数超过限制。 |
| 3111 | 货主不允许承运商在线更新订单。 |
| 3112 | 赔偿订单不唯一。 |
| 3113 | 赔偿订单已经进入账单中。 |
| 3114 | 此赔偿类型目前不支持。 |
| 3115 | 赔偿订单sku信息为空。 |
| 3116 | 赔偿订单总数为空。 |
| 3117 | compensation type,basis, objective三节点中存在空值。 |
| 3118 | 订单不能被分配给司机或线下承运商。 |
| 3119 | 订单链包含splitByLeg和splitByQuantity,但是不被支持。 |
| 3201 | 注册C/D,只支持单个订单。 |
| 3202 | 注册C/D,丢失ExternalOrderException节点。 |
| 3203 | 注册C/D,备注remark不能为空。 |
| 3204 | 注册C/D,货物信息为空。 |
| 3205 | 注册C/D,损坏damage不能为负数。 |
| 3206 | 注册C/D,短少shortage不能为负数。 |
| 3207 | 注册C/D,损坏damage和短少shortage不能都为0。 |
| 3208 | 注册C/D,SKU差异信息的单位重量需要填写。 |
| 3209 | 注册C/D,订单行信息的货物名字不能为空。 |
| 3210 | 订单当前Milestone不支持注册C/D。 |
| 3211 | 订单注册货差的客户禁止承运商注册C/D。 |
| 3212 | 注册货差不支持拆单类型为HUB。 |
| 3213 | 更新C/D不能够找到指定的订单差异OrderDiscrepancy。 |
| 3214 | 订单没有订单行,不能注册C/D。 |
| 3215 | 注册C/D,订单行信息不匹配订单中的订单行信息。 |
| 3216 | 注册C/D,订单行信息不能支持匹配多个订单行。 |
| 3217 | 注册C/D,破损damage和短少shortage的总数超过了订单行能够注册的数量。 |
| 3218 | 注册C/D,系统错误。 |
| 3219 | 注册C/D,DiscrepancyOperationType需要填写。 |
| 3220 | 拒绝货差不能够找到指定的订单差异OrderDiscrepancy。 |
| 3221 | 拒绝货差系统错误。 |
| 3222 | Compensation objective节点信息错误。 |
| 3223 | truck plate不能为空。 |
| 3224 | hub不能为空。 |
| 3225 | event date不能为空。 |
| 3226 | 拆分订单不支持注册AH或LH。 |
| 3227 | 订单数超过最大数目。 |
| 3228 | 拒收订单不唯一。 |
| 3229 | 拒收原因不匹配。 |
| 3230 | 拒收原因未激活。 |
| 3231 | 订单行未匹配。 |
| 3237 | 注册CP,只支持单个订单。 |
| 3238 | 司机未找到。 |
| 3239 | 车辆未找到。 |
| 3240 | 已注册提货签到。 |
| 1073 | 订单在账单中。 |
| 1106 | 订单当前状态无法注册拒收。 |
