oTMS logo 开放平台
Documentation Help

提送货点导入

通过提送货点导入接口,可以将不同外部系统如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] 非工作日

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
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工具