oTMS logo 开放平台
Documentation Help
订单导入
订单导出/追踪
提送货点导入
提送货点删除
卡车和司机导入
订单分配司机
运输单导入
运输单删除
订单外部追踪
订单召回
订单分享链接
订单拆分
承运商导出
H5订单链接
订单更新
订单分配
订单撤销
运输单分配车辆
订单事件推送
运输单事件推送
价格文件匹配

价格文件匹配

通过价格文件匹配接口，可以将外部系统中的订单与oTMS的价格文件匹配并计算价格。

配置说明

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

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

接口说明

公共参数

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

请求参数

字段名 位置 是否必填 描述 Schema
body body 是 价格文件匹配请求 BuyingTariffSuggestionRequest

响应参数

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

详细描述

BuyingSuggestion

字段名 类型 是否必填 描述 示例
orderId string 否 订单的标识符。与请求中订单的标识符对应
success boolean 否 订单是否匹配到了价格文件
suggestions array[SuggestedRate] 否 订单计算出的价格列表
responseCodes array[string] 否 返回码列表。包含了匹配过程中的一些信息

BuyingTariffSuggestionRequest

字段名 类型 是否必填 描述 示例
version string 否 请求的版本号
login string 否 用户名。用于 API 调用者身份认证。如果请求头中的Authorization不为空，则该值会被忽略。
password string 否 密码。用于 API 调用者身份认证。如果请求头中的Authorization不为空，则该值会被忽略。
orders array[OrderForSuggestion] 否 需要计算价格的订单列表。一次请求最多可以导入100条订单
options SuggestionOptions 否 计算价格及返回结果过程中使用的一些选项

BuyingTariffSuggestionResponse

字段名 类型 是否必填 描述 示例
version string 是 响应版本号
responseCode string 否 全局的反馈代码
successOrderCount integer (int32) 否 成功匹配到了价格文件的订单数量
matchedTariffs array[SuggestedTariff] 否 匹配到的所有价格文件的列表。只有当请求中开启了返回价格文件的选项时才会返回
buyingSuggestions array[BuyingSuggestion] 否 计算出的价格列表。每个订单一条记录

CargoDetailsForSuggestion

字段名 类型 是否必填 描述 示例
quantity integer (int32) 否 货物的数量。默认为0
volume number 否 货物总体积。单位为立方米。默认为0
weight number 否 货物总重量。单位为公斤。默认为0
insurance number 否 总投保价值。默认为0
loadingMeter integer (int32) 否 卡车的装载米数。默认为0

CustomFieldsForSuggestion

字段名 类型 是否必填 描述 示例
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 number 否 自定义小数字段1 -- 精确到18位数、6位小数
customNum2 number 否 自定义小数字段2 -- 精确到18位数、6位小数
customNum3 number 否 自定义小数字段3 -- 精确到18位数、6位小数
customNum4 number 否 自定义小数字段4 -- 精确到18位数、6位小数
customNum5 number 否 自定义小数字段5 -- 精确到18位数、6位小数
customNum6 number 否 自定义小数字段6 -- 精确到18位数、6位小数
customNum7 number 否 自定义小数字段7 -- 精确到18位数、6位小数
customNum8 number 否 自定义小数字段8 -- 精确到18位数、6位小数
customNum9 number 否 自定义小数字段9 -- 精确到18位数、6位小数
customNum10 number 否 自定义小数字段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的逻辑名

OrderDestinationForSuggestion

字段名 类型 是否必填 描述 示例
companyName string 否 该地点的名称
province string 否 地点所在省。省，市，邮编至少需要填一项
town string 否 地点所在市。省，市，邮编至少需要填一项
county string 否 地点所在的区/县
zipcode string 否 地点的邮政编码。省，市，邮编至少需要填一项
address string 否 地点的详细地址
loading boolean 否 该地点是否适用装货/卸货费。默认为否
externalId string 否 该地点的外部代码

OrderForSuggestion

字段名 类型 是否必填 描述 示例
orderId string 是 订单的标识符。在单次请求中必须是唯一的。返回中的信息是按这个值对应的
clientCode string 否 订单客户的代码。该字段仅针对SP账户，且对SP账户是必填的
origin OrderOriginForSuggestion 是 订单的起始点
destination OrderDestinationForSuggestion 是 订单的目的地
branch string 否 订单所属的地区
packageType string 否 订单的包装类型。默认为A
cargoType string 否 订单的货物类型。默认为1
transportMode TransportModeForSuggestion 是 订单的运输方式相关信息
customFields CustomFieldsForSuggestion 否 订单的自定义字段
timeSchedule TimeScheduleForSuggestion 是 订单的提货/送货时间
cargoDetails CargoDetailsForSuggestion 是 订单的货物信息。用于计算价格

OrderOriginForSuggestion

字段名 类型 是否必填 描述 示例
companyName string 否 该地点的名称
province string 否 地点所在省。省，市，邮编至少需要填一项
town string 否 地点所在市。省，市，邮编至少需要填一项
county string 否 地点所在的区/县
zipcode string 否 地点的邮政编码。省，市，邮编至少需要填一项
address string 否 地点的详细地址
loading boolean 否 该地点是否适用装货/卸货费。默认为否
externalId string 否 该地点的外部代码

SuggestedLane

字段名 类型 是否必填 描述 示例
laneOrigin SuggestedLaneOrigin 否 线路的起始点
laneDestination SuggestedLaneDestination 否 线路的目的地

SuggestedLaneDestination

字段名 类型 是否必填 描述 示例
province string 否 地点所在的省
town string 否 地点所在的市
county string 否 地点所在的区/县
zipcode string 否 地点的邮编。可能会包含“*”，代表适用任何数字
name string 否 地点名称
externalId string 否 地点外部代码

SuggestedLaneOrigin

字段名 类型 是否必填 描述 示例
province string 否 地点所在的省
town string 否 地点所在的市
county string 否 地点所在的区/县
zipcode string 否 地点的邮编。可能会包含“*”，代表适用任何数字
name string 否 地点名称
externalId string 否 地点外部代码

SuggestedRate

字段名 类型 是否必填 描述 示例
matchingLane SuggestedLane 否 计算价格时使用的线路
rate number 否 计算出的价格
leadtime integer (int32) 否 线路的运输时间
tariffSequence integer (int32) 否 价格文件的序列数。与响应中价格文件列表中的序列数对应
rateDetails SuggestedRateDetails 否 价格明细。只有当请求中开启了返回价格明细的选项时才会返回
matchedByCustomFields boolean 否 匹配该价格文件时是否使用了自定义字段
matchedByDefaultLane boolean 否 该条线路是否为默认线路

SuggestedRateDetails

字段名 类型 是否必填 描述 示例
baseRate number 否 干线运输费用
baseRateDesc string 否 干线运输费用描述
otherRate number 否 价格文件中定义的其他费用1和其他费用2的总和
otherRateDesc string 否 其他费用的描述
pickupFee number 否 提货费
pickupFeeState string 否 提货费的计算状态。可能为即时计算、未计算、已计算
deliveryFee number 否 送货费
deliveryFeeState string 否 送货费的计算状态。可能为即时计算、未计算、已计算
loadingFee number 否 装货/卸货费
extraPointFee number 否 额外提货点费用及额外送货点费用的总和
tariffTransportType string 否 价格文件中定义的运输类型
unitRate number 否 单位价格
quantity number 否 计费数量
loadingUnitRate number 否 装货费单位价格
unloadingUnitRate number 否 卸货费单位价格
minimumFee number 否 最小费用
useMinimumFee boolean 否 价格是否是最小费用
insuranceFee number 否 保费

SuggestedTariff

字段名 类型 是否必填 描述 示例
sequence integer (int32) 否 价格文件的序列数。在单次请求-响应的过程中是唯一的。用于在计算出的价格中对应价格文件
tariffName string 否 价格文件的名称
tariffTransportType string 否 价格文件中定义的运输类型
vendor SuggestedVendor 否 价格文件对应的承运商

SuggestedVendor

字段名 类型 是否必填 描述 示例
vendorName string 否 承运商名称
vendorShortCode string 否 承运商代码

SuggestionOptions

字段名 类型 是否必填 描述 示例
suggestionMode string 否 选择价格的方式。可以按最低价格或最短运输时间。默认按最低价格。可选的值：
1 - 最低价格
2 - 最短运输时间
includeTariffAndVendorInfo boolean 否 返回中是否需要包含价格文件及承运商的信息。默认为否
includeRateDetails boolean 否 返回中是否需要包含详细的价格明细。默认为否
truckSizeStrictMatching boolean 否 在匹配oTMS预定义的车辆核载量时是否开启严格验证。默认为否
locationStrictMatching boolean 否 在匹配oTMS的邮编时是否开启严格验证。默认为否
matchByCustomFields boolean 否 在匹配价格文件时是否需要自定义字段匹配,默认为是
includeUnitRate boolean 否 返回中是否需要包含单位价格/计费数量。默认为否(开启该选项需先开启includeRateDetails)
forceVolumetricConversion boolean 否 计算价格时是否严格执行重抛比转换，若是则如果订单中重量和体积任一为0使得重抛比转换无法计算时将无法匹配对应的价格文件。默认为是

TimeScheduleForSuggestion

字段名 类型 是否必填 描述 示例
pickupDate string (date-time) 否 提货日期，包含该日的最晚工作时间 (中国标准时区) 。提、送货时间至少需提供一项
deliveryDate string (date-time) 否 送货日期，包含该日的最晚工作时间 (中国标准时区) 。提、送货时间至少需提供一项

TransportModeForSuggestion

字段名 类型 是否必填 描述 示例
transportTypes array[string] 是 订单适用的运输类型列表
truckType string 否 订单适用的卡车类型。默认为2
truckDefinition TruckDefinitionForSuggestion 否 订单适用的卡车详细信息

TruckDefinitionForSuggestion

字段名 类型 是否必填 描述 示例
truckLength number 是 卡车车长
truckMtCapacity number 否 卡车装载 (吨) 。必须在oTMS预定义的值中选择
truckCbmCapacity number 否 卡车装载 (立方米) 。必须在oTMS预定义的值中选择

报文示例

请求示例

<buyingTariffSuggestionRequest version="0.1" login="login" password="password">
	<orders>
		<order>
			<orderId>order01</orderId>
			<clientCode>CLIENT</clientCode>
			<origin>
				<province>上海</province>
				<town>上海</town>
				<county>嘉定区</county>
				<zipcode>201800</zipcode>
			</origin>
			<destination>
				<province>天津</province>
				<town>天津</town>
				<zipcode>300000</zipcode>
				<loading>true</loading>
			</destination>
			<branch>Shanghai</branch>
			<packageType>B</packageType>
			<cargoType>2</cargoType>
			<transportMode>
				<transportTypes>
					<transportType>FTL</transportType>
				</transportTypes>
				<truckType>1</truckType>
				<truckDefinition>
					<truckLength>7.2</truckLength>
					<truckMtCapacity>5</truckMtCapacity>
					<truckCbmCapacity>38</truckCbmCapacity>
				</truckDefinition>
			</transportMode>
			<customFields>
				<customText1>text1</customText1>
				<customText2>text2</customText2>
				<customNum1>500.00</customNum1>
				<customEnum1>option1</customEnum1>
			</customFields>
			<timeSchedule>
				<pickupDate>2016-05-20T18:00:00</pickupDate>
				<deliveryDate>2009-05-23T18:00:00</deliveryDate>
			</timeSchedule>
			<cargoDetails>
				<quantity>10</quantity>
				<volume>100.00</volume>
				<weight>100.00</weight>
				<insurance>1000.00</insurance>
				<loadingMeter>3</loadingMeter>
			</cargoDetails>
		</order>
		<order>
			<orderId>order02</orderId>
			<clientCode>CLIENT</clientCode>
			<origin>
				<province>上海</province>
				<town>上海</town>
				<county>嘉定区</county>
				<zipcode>201800</zipcode>
			</origin>
			<destination>
				<province>天津</province>
				<town>天津</town>
				<zipcode>300000</zipcode>
				<loading>true</loading>
			</destination>
			<packageType>A</packageType>
			<cargoType>1</cargoType>
			<transportMode>
				<transportTypes>
					<transportType>LTL</transportType>
					<transportType>EXPRESS</transportType>
				</transportTypes>
				<truckType>0</truckType>
			</transportMode>
			<timeSchedule>
				<pickupDate>2016-05-21T18:00:00</pickupDate>
				<deliveryDate>2009-05-24T18:00:00</deliveryDate>
			</timeSchedule>
			<cargoDetails>
				<quantity>10</quantity>
				<volume>100.00</volume>
				<weight>100.00</weight>
				<insurance>1000.00</insurance>
				<loadingMeter>3</loadingMeter>
			</cargoDetails>
		</order>
	</orders>
	<options>
		<suggestionMode>2</suggestionMode>
		<includeTariffAndVendorInfo>false</includeTariffAndVendorInfo>
		<includeRateDetails>false</includeRateDetails>
		<truckSizeStrictMatching>false</truckSizeStrictMatching>
		<locationStrictMatching>false</locationStrictMatching>
	</options>
</buyingTariffSuggestionRequest>

响应示例

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<buyingTariffSuggestionResponse version="0.1">
    <successOrderCount>1</successOrderCount>
    <matchedTariffs/>
    <buyingSuggestions>
        <buyingSuggestion>
            <orderId>order02</orderId>
            <success>true</success>
            <suggestions>
                <suggestion>
                    <matchingLane>
                        <laneOrigin>
                            <province>上海市</province>
                            <zipcode>20\*\*\*\*</zipcode>
                        </laneOrigin>
                        <laneDestination>
                            <province>天津市</province>
                            <zipcode>30\*\*\*\*</zipcode>
                        </laneDestination>
                    </matchingLane>
                    <rate>2059.00</rate>
                    <leadtime>72</leadtime>
                    <matchedByCustomFields>false</matchedByCustomFields>
                    <matchedByDefaultLane>false</matchedByDefaultLane>
                </suggestion>
                <suggestion>
                    <matchingLane>
                        <laneOrigin>
                            <province>上海市</province>
                            <zipcode>20\*\*\*\*</zipcode>
                        </laneOrigin>
                        <laneDestination>
                            <province>天津市</province>
                            <zipcode>30\*\*\*\*</zipcode>
                        </laneDestination>
                    </matchingLane>
                    <rate>2059.00</rate>
                    <leadtime>72</leadtime>
                    <matchedByCustomFields>false</matchedByCustomFields>
                    <matchedByDefaultLane>false</matchedByDefaultLane>
                </suggestion>
                <suggestion>
                    <matchingLane>
                        <laneOrigin>
                            <province>上海市</province>
                            <zipcode>20\*\*\*\*</zipcode>
                        </laneOrigin>
                        <laneDestination>
                            <province>天津市</province>
                            <zipcode>30\*\*\*\*</zipcode>
                        </laneDestination>
                    </matchingLane>
                    <rate>3000.00</rate>
                    <leadtime>72</leadtime>
                    <matchedByCustomFields>false</matchedByCustomFields>
                    <matchedByDefaultLane>false</matchedByDefaultLane>
                </suggestion>
            </suggestions>
            <responseCodes/>
        </buyingSuggestion>
        <buyingSuggestion>
            <orderId>order01</orderId>
            <success>false</success>
            <responseCodes>
                <responseCode>4005</responseCode>
            </responseCodes>
        </buyingSuggestion>
    </buyingSuggestions>
</buyingTariffSuggestionResponse>

错误码解释

全局反馈代码

反馈代码 说明
0调用者未通过验证
1不支持的请求版本

单个请求反馈代码

反馈代码 说明
4001无法用客户代码匹配到客户（仅针对SP用户）
4002未提供客户代码 (仅针对SP用户)
4005无法用地区名称匹配到地区
4010公司尚未开启自定义字段功能
4011某个自定义字段被忽略， 因为自定义字段配置中未打开该自定义字段
4012自定义枚举字段的选项无法用提供的逻辑名匹配
4015提货时间与送货时间未提供
4020请求中包含了运输类型“FTL”，因此卡车类型不能为“3”
4021请求中包含了运输类型“FTL”，因此车长不能为空
4022车长不是oTMS预定义的车长
4023请求中提供的车辆核载量信息无法在oTMS预定义的车辆核载量中找到匹配
4024请求中提供的车辆核载量信息在oTMS预定义的车辆核载量中匹配到多条
4030订单的提货点信息缺少
4031订单的提货点无法匹配到oTMS的邮编
4032订单的提货点匹配到了多个oTMS的邮编
4035订单的送货点信息缺少
4036订单的送货点无法匹配到oTMS的邮编
4037订单的送货点匹配到了多个oTMS的邮编
4099其他错误

API工具