提送货点导入
通过提送货点导入接口,可以将不同外部系统如ERP系统、WMS系统的提送货点数据进行批量的导入或者更新。
版本号 | 文档 | 说明 |
---|---|---|
0.1 | 当前版本文档 |
oTMS同时在生产环境和测试环境中提供Web Service接口,其中测试环境用于集成测试。两种环境下都需要由oTMS系统管理员分配API帐号密码后方可使用。
注意: 请合理地调用公共接口。如果发现存在异常调用或者对我们系统性能造成影响等情况,会对API账号的调用进行限制,甚至停用。
目前对该接口的调用限制为每个公司每秒最多10个请求
注意: 请合理地调用公共接口。如果发现存在异常调用或者对我们系统性能造成影响等情况,会对API账号的调用进行限制,甚至停用。
目前对该接口的调用限制为每个公司每秒最多10个请求
目前对该接口的调用限制为每个公司每秒最多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} | |
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 | 其他错误。 |