oTMS logo 开放平台
Documentation Help

价格文件匹配

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

配置说明

oTMS同时在生产环境和测试环境中提供Web Service接口,其中测试环境用于集成测试。两种环境下都需要由oTMS系统管理员分配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 调用者身份认证。
password string 密码。用于 API 调用者身份认证。
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
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 该地点是否适用装货/卸货费。默认为否

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 该地点是否适用装货/卸货费。默认为否

SuggestedLane

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

SuggestedLaneDestination

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

SuggestedLaneOrigin

字段名 类型 是否必填 描述 示例
province string 地点所在的省
town string 地点所在的市
county string 地点所在的区/县
zipcode 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 价格文件中定义的运输类型

SuggestedTariff

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

SuggestedVendor

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

SuggestionOptions

字段名 类型 是否必填 描述 示例
suggestionMode string 选择价格的方式。可以按最低价格或最短运输时间。默认按最低价格
includeTariffAndVendorInfo boolean 返回中是否需要包含价格文件及承运商的信息。默认为否
includeRateDetails boolean 返回中是否需要包含详细的价格明细。默认为否
truckSizeStrictMatching boolean 在匹配oTMS预定义的车辆核载量时是否开启严格验证。默认为否
locationStrictMatching boolean 在匹配oTMS的邮编时是否开启严格验证。默认为否

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