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/jobSheetImport application/xml application/xml
沙箱环境 PUT https://demo.otms.cn/ws/jobSheetImport application/xml application/xml

请求参数

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

响应参数

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

详细描述

ImportedCargoDetails

字段名 类型 是否必填 描述 示例
totalQuantity integer (int32) 所有运输单位的数量,不能为负数
totalWeight number 所有运输货物的总重量,单位为公斤,不能为负数
totalVolume number 所有运输货物的总体积,单位为立方米,不能为负数
totalInsurance number 所有运输货物的总投保价值,不能为负数
cargoType integer (int32) 货物类型,考虑到oTMS用户存在共识的运输订单交易的性质。包括如下常量:
1 - 普通货物
2 - 温控货物
3 - 危险品
4 - 危险品和温控货物
packageType string 包装类型,oTMS根据运输用途将货物外包装分为4种,考虑到oTMS用户存在共识的运输订单交易的性质,如果订单包括不同的包装类型请用最高的那个。包括如下常量:
A - 散箱,可堆叠,人工装卸货。已有的卡车容量可以被充分利用,运输提供商不需要特别的装货设备
B - 托盘或者木箱,可堆叠,需叉车装卸货。通常卡车利用率高,可以双重叠加托盘,运输提供商需要叉车装卸货
C - 托盘,木箱或不规则形状,不可堆叠,需叉车装卸货。卡车不能被充分利用,建议货物各方根据LDM而不是CBM/MT来协定零担价格
D - 不允许配货,包车运输。这些货主创建的只能整车收费 (根据卡车尺寸付款) 的订单无论大小都是整车装运
E - 保温箱,可堆叠,人工装卸货

ImportedJobSheet

字段名 类型 是否必填 描述 示例
sequence integer (int32) 序列数
clientCode string oTMS线下客户公司代码 (承运商帐户适用)
clientReferenceNumber string 调用的系统订单标识符
branch string 地区设置中的地区名称
externalShipmentID string 运输单的外部单号,全局唯一
cargoDetails ImportedCargoDetails 包括工作单中的尺寸等货物具体参数
transportMode ImportedTransportMode 包括工作单中的货运信息
jobSheetOrders array[ImportedJobSheetOrder] 待导入运输单的订单集合
vendorCode string 承运商公司代码 (自动分配)
cost number 运输单总价 (自动分配)
autoDispatch boolean 是否需对运输单进行自动分配

ImportedJobSheetOrder

字段名 类型 是否必填 描述 示例
clientCode string oTMS线下客户公司代码 (承运商帐户适用)
clientReferenceNumber string 调用的系统订单标识符
orderNumber string 内部系统的唯一订单号
erpNumber string 外部系统的唯一的订单号,与orderNumber二选一,优先
sequence integer (int32) 订单的顺序编号

ImportedTransportMode

字段名 类型 是否必填 描述 示例
transportType string 货物运输类型,包括如下常量:
FTL - 整车
LTL - 零担
AIR - 空运
EXPRESS - 快递
RAIL - 铁路
WATER - 水运
truckType string 必需的卡车类型,包括如下常量:
0 - 敞篷车
1 - 厢式车
2 - 任意
3 - 轿运车
4 - 油罐车
5 - 飞翼车
6 - 高栏车
7 - 平板车
8 - 罐车
9 - 冷藏车
transportRemarks string 运输模式的备注
loadingMeter integer (int32) 卡车的装载米数
truckLength number 车长。如果存在,必须从已经定义好的值中选择,按公司分别设置。oTMS定义了全局支持的车长,如果车长不能被oTMS匹配到,会返回错误代码1006。
truckCbmCapacity number 卡车装载 (立方米) 。如果存在,必须从已经定义好的值中选择,按车长对应装载 (立方米) 。oTMS定义了全局支持的车长和对应的装载 (吨/立方米) ,如果装载 (立方米) 不能被 oTMS 匹配到,会返回错误代码1006。
truckMtCapacity number 卡车装载 (吨) 。如果存在,必须从已经定义好的值中选择,按车长对应装载 (吨) 。oTMS定义了全局支持的车长和对应的装载 (吨/立方米) ,如果装载 (吨) 不能被oTMS匹配到,会返回错误代码1007。

JobSheetImportRequest

字段名 类型 是否必填 描述 示例
version string 请求的版本号。当前版本号为0.1
login string 用户名。用于 API 调用者身份认证。如果请求头中的Authorization不为空,则该值会被忽略。
password string 密码。用于 API 调用者身份认证。如果请求头中的Authorization不为空,则该值会被忽略。
jobSheets array[ImportedJobSheet] 待导入的运输单列表。一次请求最多可以导入100条运输单

JobSheetImportResponse

字段名 类型 是否必填 描述 示例
version string 响应版本号
responseCode string 全局的反馈代码
jobSheets array[JobSheetResponse] 处理的运输单列表

JobSheetOrderResponse

字段名 类型 是否必填 描述 示例
orderNumber string 订单号码
erpNumber string 订单外部单号
responseCodes array[ResponseCode] 订单响应代码列表,导入结果的详细说明,可能为空

JobSheetResponse

字段名 类型 是否必填 描述 示例
externalShipmentID string 运输单的外部单号
importStatus string 导入/分配状态,可取下列值:
IMPORTED
NOT IMPORTED
DISPATCHED
NOT DISPATCH
jobSheetOrdersResponse array[JobSheetOrderResponse] 运输单中各个订单的返回
responseCodes array[ResponseCode] 响应代码列表,导入结果的详细说明,可能为空
sequence integer (int32) 运输单序号

ResponseCode

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

报文示例

请求示例

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<jobSheetImportRequest version="0.1" login="login" password="password">
    <jobSheets>
        <importedJobSheet sequence="1122">
            <externalShipmentID>外部单号</externalShipmentID>
            <branch>Beijing DC</branch>
            <cargoDetails>
                <cargoType>1</cargoType>
                <packageType>A</packageType>
            </cargoDetails>
            <transportMode>
                <transportType>LTL</transportType>
                <truckType>0</truckType>
                <truckLength>1</truckLength>
                <truckCbmCapacity>44</truckCbmCapacity>
                <truckMtCapacity>5</truckMtCapacity>
            </transportMode>
            <autoDispatch>true</autoDispatch>
            <vendorCode>SH00108</vendorCode>
            <cost>100.1</cost>
            <jobSheetOrders>
                <jobSheetOrder>
                    <clientCode>SH00105</clientCode>
                    <orderNumber/>
                    <erpNumber>VCX000009</erpNumber>
                    <sequence>1</sequence>
                </jobSheetOrder>
                <jobSheetOrder>
                    <clientCode>SH00105</clientCode>
                    <orderNumber>SH00105091942</orderNumber>
                    <erpNumber/>
                    <sequence>2</sequence>
                </jobSheetOrder>
            </jobSheetOrders>
        </importedJobSheet>
    </jobSheets>
</jobSheetImportRequest>

响应示例

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<jobSheetImportResponse version="0.1">
    <responseCode>200</responseCode>
    <jobSheets>
        <jobSheet sequence="1122">
            <externalShipmentID>0825-01</externalShipmentID>
            <importStatus>DISPATCHED</importStatus>
            <jobSheetOrdersResponse>
                <jobSheetOrders>
                    <orderNumber>SH00105092157</orderNumber>
                    <responseCodes>
                        <responseCode>
                            <code>200</code>
                        </responseCode>
                    </responseCodes>
                </jobSheetOrders>
                <jobSheetOrders>
                    <orderNumber>SH00105092158</orderNumber>
                    <responseCodes>
                        <responseCode>
                            <code>200</code>
                        </responseCode>
                    </responseCodes>
                </jobSheetOrders>
            </jobSheetOrdersResponse>
            <responseCodes>
                <responseCode>
                    <code>200</code>
                </responseCode>
            </responseCodes>
        </jobSheet>
    </jobSheets>
</jobSheetImportResponse>

错误码解释

全局反馈代码

反馈代码 说明
0客户验证失败/没有运输单权限
1不支持的请求版本
2请求中的导入运输单数量超过限制

单个请求反馈代码

反馈代码 说明
1001请求参数不合法
1035运输单和订单的地区不匹配
1040参数 (branch) 对应的地区错误
1093参数 (cost) 不合法
1102导入运输单为空
1103导入运输单中订单列表为空
1104参数 (packageType) 不合法
1105参数 (cargoType) 不合法
1106订单状态不合法 (要求:已释放)
1107订单已存在运输单中
1108运输单导入失败
1109订单没有找到
1110车长不合法
1111订单总重量超过卡车容量
1112订单总体积超过卡车容量
1113订单参数 (clientCode) 为空
1114参数 (externalShipmentID) 重复,不能导入
1121改变订单状态失败
1122承运商没有找到
1125运输单自动分配失败
1126没有运输单自动分配权限
1100未知错误

API工具