oTMS logo 开放平台
Documentation Help
订单导入
订单导出/追踪
提送货点导入
提送货点删除
卡车和司机导入
订单分配司机
运输单导入
运输单删除
订单外部追踪
订单召回
订单分享链接
订单拆分
承运商导出
H5订单链接
订单更新
订单分配
订单撤销
运输单分配车辆
订单事件推送
订单评分
车辆信息
订单交接创建
运输单事件推送
温度和位置推送
获取授权码
获取令牌
获取用户信息
获取登录通行证
承运商获取条形码
价格文件匹配
订单自定义字段更新
小程序二维码生成
订单费用更新
收发货方基础数据导出
运输单导出/追踪
运输单召回
文件上传
拒收查询
收货码查询

提送货点导入

通过提送货点导入接口，可以将不同外部系统如ERP系统、WMS系统的提送货点数据进行批量的导入或者更新。

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

配置说明

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

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

目前对该接口的调用限制为每个公司每秒最多10个请求

接口说明

公共参数

环境 HTTP请求方法 HTTPS请求地址 请求主体MIME类型 响应主体MIME类型
正式环境 PUT https://login.otms.cn/ws/shipPointImport application/xml application/xml
沙箱环境 PUT https://demo.otms.cn/ws/shipPointImport application/xml application/xml

请求参数

字段名 位置 是否必填 描述 Schema
body body 是 提送货点导入请求 ShipPointImportRequest
Authorization header Basic Authorization。如果不为空，则优先使用该值作身份认证。否则使用请求报文中的用户名与密码 string

响应参数

状态码 描述 响应模型
200 successful operation ShipPointImportResponse

详细描述

ImportedContactPerson

字段名 类型 是否必填 描述 示例
name string 否 联系人的姓名
phone string 否 固定电话。固定电话与手机号码二者必须填一个。正则表达式: \d{6,10}(-[0-9]{1,5})?
phoneAreaCode string 否 区号。若固定电话不为空，则必填。正则表达式: \d{1,4}
mobile string 否 手机号码。固定电话与手机号码二者必须填一个。正则表达式: \d{11}
email string 否 邮箱，必须是符合网络标准的有效邮箱

ImportedShipPoint

字段名 类型 是否必填 描述 示例
sequence integer (int32) 是 序列数
clientCode string 否 oTMS线下客户公司代码 (承运商帐户适用)
clientReferenceNumber string 否 调用的系统订单标识符
type string 是 提送货点类型。可以取下列值：
0 - 提货点
1 - 送货点
2 - 集散中心
companyName string 是 提送货点名称
nationalCenter boolean 否 国家级配送中心。默认值是false
regionalCenter boolean 否 区域配送中心。默认值是false
myLocation string 否 所属地区
selectType string 是 地区选择类型，默认值是2 - 仅限总部，可以取下列值：
1 - 所有地区
2 - 仅限总部
3 - 指定地区
selectedLocations array[string] 否 可用地区。如selectType为3则必须填写
externalId string 否 外部识别码
province string 否 省
town string 否 市
county string 否 区县
address string 否 地址
shippingId string 否 区域代码
zipcode string 否 6位数邮政编码
updateZipcode boolean 否 是否更新省市区、邮编信息。默认值是false
contact ImportedContactPerson 否 联系信息
loading boolean 否 装卸费。默认值是false
supportXtt boolean 否 XTT支持标记。默认值是false
supportSms boolean 否 是否发送短信通知标记。默认值是false
remark string 否 备注
driverOperateRadius string 否 可操作距离
latitude number (double) 否 纬度
longitude number (double) 否 经度
notifyDistancePercentage string 否 中途距离。对于导入提货点信息，该数据被忽略
notifyRadius string 否 进圈距离
customFields ImportedShipPointCustomFields 否 自定义字段。这适用于启用并且正确配置了自定义字段的公司。
workingDays array[ImportedWorkingDay] 否 工作日
nonWorkingDays array[ImportedWorkingDay] 否 非工作日
fullUpdate boolean 否 是否做全量更新，若为否，则请求中留空的字段将不会被更新。默认为否

ImportedShipPointCustomFields

字段名 类型 是否必填 描述 示例
customText1 string 否 自定义文本字段1
customText2 string 否 自定义文本字段2
customText3 string 否 自定义文本字段3
customText4 string 否 自定义文本字段4
customText5 string 否 自定义文本字段5
customText6 string 否 自定义文本字段6
customText7 string 否 自定义文本字段7
customText8 string 否 自定义文本字段8
customText9 string 否 自定义文本字段9
customText10 string 否 自定义文本字段10
customText11 string 否 自定义文本字段11
customText12 string 否 自定义文本字段12
customText13 string 否 自定义文本字段13
customText14 string 否 自定义文本字段14
customText15 string 否 自定义文本字段15
customText16 string 否 自定义文本字段16
customText17 string 否 自定义文本字段17
customText18 string 否 自定义文本字段18
customText19 string 否 自定义文本字段19
customText20 string 否 自定义文本字段20
customText21 string 否 自定义文本字段21
customText22 string 否 自定义文本字段22
customText23 string 否 自定义文本字段23
customText24 string 否 自定义文本字段24
customText25 string 否 自定义文本字段25
customText26 string 否 自定义文本字段26
customText27 string 否 自定义文本字段27
customText28 string 否 自定义文本字段28
customText29 string 否 自定义文本字段29
customText30 string 否 自定义文本字段30
customText31 string 否 自定义文本字段31
customText32 string 否 自定义文本字段32
customText33 string 否 自定义文本字段33
customText34 string 否 自定义文本字段34
customText35 string 否 自定义文本字段35
customText36 string 否 自定义文本字段36
customText37 string 否 自定义文本字段37
customText38 string 否 自定义文本字段38
customText39 string 否 自定义文本字段39
customText40 string 否 自定义文本字段40
customText41 string 否 自定义文本字段41
customText42 string 否 自定义文本字段42
customText43 string 否 自定义文本字段43
customText44 string 否 自定义文本字段44
customText45 string 否 自定义文本字段45
customText46 string 否 自定义文本字段46
customText47 string 否 自定义文本字段47
customText48 string 否 自定义文本字段48
customText49 string 否 自定义文本字段49
customText50 string 否 自定义文本字段50
customText51 string 否 自定义文本字段51
customText52 string 否 自定义文本字段52
customText53 string 否 自定义文本字段53
customText54 string 否 自定义文本字段54
customText55 string 否 自定义文本字段55
customText56 string 否 自定义文本字段56
customText57 string 否 自定义文本字段57
customText58 string 否 自定义文本字段58
customText59 string 否 自定义文本字段59
customText60 string 否 自定义文本字段60
customText61 string 否 自定义文本字段61
customText62 string 否 自定义文本字段62
customText63 string 否 自定义文本字段63
customText64 string 否 自定义文本字段64
customText65 string 否 自定义文本字段65
customText66 string 否 自定义文本字段66
customText67 string 否 自定义文本字段67
customText68 string 否 自定义文本字段68
customText69 string 否 自定义文本字段69
customText70 string 否 自定义文本字段70
customText71 string 否 自定义文本字段71
customText72 string 否 自定义文本字段72
customText73 string 否 自定义文本字段73
customText74 string 否 自定义文本字段74
customText75 string 否 自定义文本字段75
customText76 string 否 自定义文本字段76
customText77 string 否 自定义文本字段77
customText78 string 否 自定义文本字段78
customText79 string 否 自定义文本字段79
customText80 string 否 自定义文本字段80
customNum1 string 否 自定义小数字段1 -- 精确到18位数、6位小数
customNum2 string 否 自定义小数字段2 -- 精确到18位数、6位小数
customNum3 string 否 自定义小数字段3 -- 精确到18位数、6位小数
customNum4 string 否 自定义小数字段4 -- 精确到18位数、6位小数
customNum5 string 否 自定义小数字段5 -- 精确到18位数、6位小数
customNum6 string 否 自定义小数字段6 -- 精确到18位数、6位小数
customNum7 string 否 自定义小数字段7 -- 精确到18位数、6位小数
customNum8 string 否 自定义小数字段8 -- 精确到18位数、6位小数
customNum9 string 否 自定义小数字段9 -- 精确到18位数、6位小数
customNum10 string 否 自定义小数字段10 -- 精确到18位数、6位小数
customEnum1 string 否 自定义字段中定义并激活的枚举变量1的逻辑名
customEnum2 string 否 自定义字段中定义并激活的枚举变量2的逻辑名
customEnum3 string 否 自定义字段中定义并激活的枚举变量3的逻辑名
customEnum4 string 否 自定义字段中定义并激活的枚举变量4的逻辑名
customEnum5 string 否 自定义字段中定义并激活的枚举变量5的逻辑名
customEnum6 string 否 自定义字段中定义并激活的枚举变量6的逻辑名
customEnum7 string 否 自定义字段中定义并激活的枚举变量7的逻辑名
customEnum8 string 否 自定义字段中定义并激活的枚举变量8的逻辑名
customEnum9 string 否 自定义字段中定义并激活的枚举变量9的逻辑名
customEnum10 string 否 自定义字段中定义并激活的枚举变量10的逻辑名

ImportedWorkingDay

字段名 类型 是否必填 描述 示例
date string (date-time) 否 日期
beginFrom string (date-time) 是 开始时间
endTo string (date-time) 是 结束时间
dayOfWeek string 否 星期，可选的值：
1 - 星期一
2 - 星期二
3 - 星期三
4 - 星期四
5 - 星期五
6 - 星期六
7 - 星期日
remarks string 否 备注

ResponseCode

字段名 类型 是否必填 描述 示例
code string 否 返回码

ShipPointImportRequest

字段名 类型 是否必填 描述 示例
version string 是 请求的版本号。当前版本号为0.1
login string 否 用户名。用于 API 调用者身份认证。如果请求头中的Authorization不为空，则该值会被忽略。
password string 否 密码。用于 API 调用者身份认证。如果请求头中的Authorization不为空，则该值会被忽略。
shipPoints array[ImportedShipPoint] 是 提送货点创建更新列表

ShipPointImportResponse

字段名 类型 是否必填 描述 示例
version string 是 响应版本号
responseCode string 否 全局的反馈代码
processedShipPoints string 否 处理的提送货点数量
shipPoints array[ShipPointResponse] 否 处理的提送货点列表

ShipPointResponse

字段名 类型 是否必填 描述 示例
sequence integer (int32) 否 序列数
clientReferenceNumber string 否 客户查询号，从收到的收发货点中获取。
importStatus string 否 收发货点导入状态，包括如下常量：
ADDED
UPDATED
REMOVED
FAILED
responseCodes array[ResponseCode] 否 订单响应代码列表，导入结果的详细说明，可能为空
responseCodeParameters object 否 -

报文示例

请求示例

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<shipPointImportRequest version="0.1" login="username" password="password">
    <shipPoints>
        <shipPoint sequence="1">
            <clientReferenceNumber>sh00105001</clientReferenceNumber>
            <type>0</type>
            <companyName>Shanghai 001 co.,ltd.</companyName>
            <myLocation>Shanghai DC</myLocation>
            <selectType>3</selectType>
            <selectedLocations>
                <location>Shanghai DC</location>
                <location>Hangzhou DC</location>
            </selectedLocations>
            <externalId>11223344</externalId>
            <province>上海</province>
            <town>上海</town>
            <county/>
            <address>1606 Ganghui plaza</address>
            <zipcode>200020</zipcode>
            <contact>
                <name>Mr. Zhang</name>
                <phone>12345678</phone>
                <phoneAreaCode>021</phoneAreaCode>
                <mobile>13812345678</mobile>
                <email>peterzhang@testmail.com</email>
            </contact>
            <loading>true</loading>
            <supportXtt>true</supportXtt>
            <supportSms>true</supportSms>
            <remark/>
            <customFields>
                <customText1>sh</customText1>
                <customNum1>100</customNum1>
            </customFields>
        </shipPoint>
        <shipPoint sequence="2">
            <clientReferenceNumber>sh00105002</clientReferenceNumber>
            <type>1</type>
            <companyName>Hangzhou 001 co.,ltd.</companyName>
            <myLocation>Hangzhou DC</myLocation>
            <selectType>1</selectType>
            <externalId>22334455</externalId>
            <province>浙江</province>
            <town>杭州</town>
            <county/>
            <address>9999 Lian Hua Road</address>
            <zipcode>311010</zipcode>
            <contact>
                <name>Johnny</name>
                <phone>87654321</phone>
                <phoneAreaCode>0571</phoneAreaCode>
                <mobile>13887654321</mobile>
                <email>Johnny@testmail.com</email>
            </contact>
            <loading>false</loading>
            <supportXtt>true</supportXtt>
            <supportSms>true</supportSms>
            <remark/>
            <customFields>
                <customText1>hz</customText1>
                <customNum1>50</customNum1>
            </customFields>
        </shipPoint>
    </shipPoints>
</shipPointImportRequest>

响应示例

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<shipPointImportResponse version="0.1">
    <responseCode/>
    <processedShipPoints>2</processedShipPoints>
    <shipPoints>
        <shipPoint sequence="1">
            <clientReferenceNumber>sh00105001</clientReferenceNumber>
            <importStatus>UPDATED</importStatus>
            <responseCodes>
                <responseCode>
                    <code>1014</code>
                </responseCode>
                <responseCode>
                    <code>1031</code>
                </responseCode>
                <responseCode>
                    <code>1040</code>
                </responseCode>
            </responseCodes>
        </shipPoint>
        <shipPoint sequence="2">
            <clientReferenceNumber>sh00105002</clientReferenceNumber>
            <importStatus>UPDATED</importStatus>
            <responseCodes>
                <responseCode>
                    <code>1018</code>
                </responseCode>
                <responseCode>
                    <code>1031</code>
                </responseCode>
            </responseCodes>
        </shipPoint>
    </shipPoints>
</shipPointImportResponse>

错误码解释

全局反馈代码

反馈代码 说明
0客户验证失败。
1不支持的请求版本。
2请求中的提送货点数据过多。

单个请求反馈代码

反馈代码 说明
1000客户代码未找到。
1001无效的数据类型。
1002备用。
1009发货方外部代码重复。
1010收货方外部代码重复。
1013发货方oTMS邮政编码匹配到乡镇。
1014发货方oTMS邮政编码只与6位邮政编码匹配。
1015发货方oTMS邮政编码不匹配。
1016发货方oTMS邮政编码与6位和乡镇的都匹配。
1017收货方oTMS邮政编码只与乡镇匹配。
1018收货方邮政编码只与6位邮政编码匹配。
1019收货方oTMS邮政编码不匹配。
1020收货方oTMS邮政编码与6位和乡镇匹配。
1030自定义字段不能识别;公司设置已关闭自定义字段,或自定义字段设置错误。
1040地区不存在。
1043分公司未识别,或用户权限不匹配。
1045没有匹配的提送货点。
1046集散点外部代码重复。
1050不支持XTT--公司设置已关闭XTT选项。
1051选择XTT支持但未提供Email地址。
1052发货方oTMS邮政编码只与乡镇匹配。
1053收货方oTMS邮政编码只与乡镇匹配。
1055不支持短信通知--公司设置已关闭短信通知选项。
1056选择短信通知但未提供手机号码。
1060已禁用分公司--忽略分公司设置。
1100其他错误。

API工具