oTMS logo 开放平台
Documentation Help

价格文件匹配

通过价格文件匹配接口,可以将外部系统中的订单与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工具