订单外部追踪
订单外部追踪接口供客户系统接入并修改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 | 订单当前状态无法注册拒收。 |