oTMS logo 开放平台
Documentation Help

订单外部追踪

订单外部追踪接口供客户系统接入并修改oTMS订单状态 (提货/送货) ,修改订单状态为送货的同时,支持上传Epod。客户系统发送包含oTMS订单名称等修改状态请求,可以支持多条订单同时请求但多条订单不支持上传Epod。支持送货状态下的订单单独上传EPOD (EPOD_UPLOAD) 操作。支持对订单进行投诉 (Exception_H) 操作,在投诉的同时可以选择上传附件,附件使用 BASE64编码。支持对订单进行记录在途事件 (Exception_B) 操作。支持对订单注册到达中转站 (AH) 或离开中转站 (LH) 操作。

版本号 文档 说明
0.1 当前版本文档

配置说明

oTMS同时在生产环境和测试环境中提供Web Service接口,其中测试环境用于集成测试。两种环境下都需要由oTMS系统管理员分配API帐号密码后方可使用。

注意: 请合理地调用公共接口。如果发现存在异常调用或者对我们系统性能造成影响等情况,会对API账号的调用进行限制,甚至停用。

目前对该接口的调用限制为每个公司每秒最多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节点信息。
3020event date格式错误(2016-8-8T12:12:12)。
3021缺少charge节点。
3022订单关单和超时。
3023订单的文件附件中缺少fileId或fileName。
3100上传Epod操作,Epod最大不能超过10M限制。
3101订单需要epod信息,但是没有找到epod信息。
3102Epod缺失,可能发生服务器内部错误。
3103Epod上传失败。
3104订单需要Epod信息,但是Epod节点内容为空。
3105不支持同时对多订单上传Epod。
3106Epod内容超过100KB限制。
3107货主不允许上传Epod。
3108订单是拆分订单,只有最后一段拆分子订单允许上传Epod。
3109Epod文件类型只能是jpg, jpeg, png, pdf, doc, docx, xls, xlsx, zip, rar。
3030订单所注册的异常总数超过限制。
3111货主不允许承运商在线更新订单。
3112赔偿订单不唯一。
3113赔偿订单已经进入账单中。
3114此赔偿类型目前不支持。
3115赔偿订单sku信息为空。
3116赔偿订单总数为空。
3117compensation 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拒绝货差系统错误。
3222Compensation objective节点信息错误。
3223truck plate不能为空。
3224hub不能为空。
3225event date不能为空。
3226拆分订单不支持注册AH或LH。
3227订单数超过最大数目。
3228拒收订单不唯一。
3229拒收原因不匹配。
3230拒收原因未激活。
3231订单行未匹配。
3237注册CP,只支持单个订单。
3238司机未找到。
3239车辆未找到。
3240已注册提货签到。
1073订单在账单中。
1106订单当前状态无法注册拒收。

API工具