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编码

Attachments

字段名 类型 是否必填 描述 示例
attachment array[Attachment] 附件内容

ExternalDiscrepancyDto

字段名 类型 是否必填 描述 示例
productCode string 货物代码
productName string 货物名称
unit string 货物单位
unitPrice number (double) 订单行的货差信息
damage integer (int32) 货物破损数量
shortage integer (int32) 货物缺失数量
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所需车牌号
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 - 特殊费用
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 integer (int32) 货物/产品破损的数量
shortageQuantity integer (int32) 货物/产品短少的数量
damageUnitPrice number 货物/产品破损的单价
shortageUnitPrice number 货物/产品短少的单价

ImportedOrderLineRejection

字段名 类型 是否必填 描述 示例
productCode string 货物/产品代码
productName string 货物/产品名称
productUnit string 货物/产品单位
rejection integer (int32) 货物/产品拒收的数量

ImportedOrderRejection

字段名 类型 是否必填 描述 示例
comments string 拒收说明
reason string 拒收原因
totalRejection integer (int32) 总拒收数量
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订单关单和超时。
3100上传Epod操作,Epod最大不能超过5M限制。
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订单行未匹配。
1073订单在账单中。
1106订单当前状态无法注册拒收。

API工具