oTMS-openapi en
  1. oTMS API
oTMS-openapi en
  • oTMS API
    • Order Import
      PUT
    • orderOutbound
      POST
    • shipPointImport
      PUT
    • Delete delivery point
      DELETE
    • Order Assignment to Driver
      POST
    • TruckAndDriverImport
      PUT
    • Assign Driver to Order
      POST
    • Job Sheet Import
      PUT
    • Delete Job Sheet
      PUT
    • Order Recall
      POST
    • Share Link
      PUT
    • Carrier Export
      POST
    • Order Update
      PUT
    • Order Dispatch
      POST
    • Order Revoke
      PUT
    • Order Rating
      POST
    • Order Handover Creation
      PUT
    • Oorder Custom Update
      POST
    • Price File Matching
      POST
    • Order cost update
      POST
    • Shipper/Receiver export
      POST
    • Job Sheet Outbound
      POST
    • Job Sheet Recall
      PUT
    • TruckPosition
      POST
    • GPS Device
      POST
    • Jobsheet To Driver
      PUT
    • TrackandTrace
      POST
    • H5 Link
      PUT
  1. oTMS API

Price File Matching

POST
/ws/tariff/tariffSuggestion/v0/buying
Price File Matching

Price File Matching Interface#

Through the Price File Matching Interface, orders from external systems can be matched with oTMS price files to calculate prices.

Configuration Instructions#

oTMS provides Web Service interfaces in both production and testing environments, where the testing environment is primarily used for integration testing. In both environments, API account credentials must be assigned by the oTMS system administrator before they can be used.

Important Notes#

Please use the public interfaces reasonably. If abnormal calls or any issues affecting system performance are detected, we will impose restrictions on the API account calls, or even deactivate them.

Request

Body Params application/xml
version
string 
optional
Version number of the request
login
string 
optional
Username. Used for API caller authentication. If the Authorization header is not empty, this value will be ignored.
password
string 
optional
Password. Used for API caller authentication. If the Authorization header is not empty, this value will be ignored.
orders
array[object (OrderForSuggestion) {11}] 
optional
List of orders for which prices need to be calculated. Up to 100 orders can be imported in one request
orderId
string 
required
Identifier of the order. Must be unique within a single request. Information in the response corresponds to this value
clientCode
string 
optional
Code of the order's customer. This field is only applicable to SP accounts and is mandatory for them
origin
object (OrderOriginForSuggestion) 
required
destination
object (OrderDestinationForSuggestion) 
required
branch
string 
optional
Region to which the order belongs
packageType
enum<string> 
optional
Package type of the order. Defaults to TYPE_A
Allowed values:
TYPE_ATYPE_BTYPE_CTYPE_DTYPE_E
cargoType
enum<string> 
optional
Cargo type of the order. Defaults to TYPE_1
Allowed values:
TYPE_1TYPE_1_1TYPE_1_2TYPE_2TYPE_3TYPE_3_1TYPE_4
transportMode
object (TransportModeForSuggestion) 
required
customFields
object (CustomFieldsForSuggestion) 
optional
timeSchedule
object (TimeScheduleForSuggestion) 
required
cargoDetails
object (CargoDetailsForSuggestion) 
required
options
object (SuggestionOptions) 
optional
suggestionMode
enum<string> 
optional
Method for selecting prices. Can be based on the lowest price or shortest transportation time. Default is the lowest price. Possible values:
1 - Lowest Price
2 - Shortest Transportation Time
Allowed values:
LOWEST_RATESHORTEST_LEADTIMESORT_BY_RATESORT_BY_LEADTIMELATEST_TARIFF
includeTariffAndVendorInfo
boolean 
optional
Whether to include price file and carrier information in the response. Default is no
Default:
false
includeRateDetails
boolean 
optional
Whether to include detailed price information in the response. Default is no
Default:
false
truckSizeStrictMatching
boolean 
optional
Whether to enable strict validation when matching predefined truck capacity in oTMS. Default is no
Default:
false
locationStrictMatching
boolean 
optional
Whether to enable strict validation when matching postcodes in oTMS. Default is no
Default:
false
matchByCustomFields
boolean 
optional
Whether to require custom field matching when matching price files. Default is yes
Default:
false
includeUnitRate
boolean 
optional
Whether to include unit price/chargeable quantity in the response. Default is no (this option requires enabling includeRateDetails first)
Default:
false
forceVolumetricConversion
boolean 
optional
Whether to enforce volumetric conversion strictly during price calculation. If set, the calculation will fail if either weight or volume is 0, preventing volumetric conversion. Default is yes
Default:
false
Example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<buyingTariffSuggestionRequest version="0.1" login="login" password="password">
	<orders>
		<order>
			<orderId></orderId>
			<clientCode></clientCode>
			<origin>
				<province>ACEH</province>
				<town>ACEH SELATAN</town>
				<county>KLUET UTARA</county>
			</origin>
			<destination>
				<province>ACEH</province>
				<town>ACEH TENGGARA</town>
				<county>LAWE ALA</county>
				<loading>false</loading>
			</destination>
			<packageType>A</packageType>
			<cargoType>1</cargoType>
			<transportMode>
				<transportTypes>
					<transportType>LTL</transportType>
				</transportTypes>
				<truckType>2</truckType>
			</transportMode>
			<timeSchedule>
				<pickupDate>2024-10-05T18:00:00</pickupDate>
				<deliveryDate>2024-10-08T18:00:00</deliveryDate>
			</timeSchedule>
			<cargoDetails>
				<quantity>100</quantity>
				<volume>100</volume>
				<weight>1000</weight>
				<insurance></insurance>
				<loadingMeter></loadingMeter>
			</cargoDetails>
		</order>
	</orders>
	<options>
		<suggestionMode>1</suggestionMode>
		<includeTariffAndVendorInfo>false</includeTariffAndVendorInfo>
		<includeRateDetails>false</includeRateDetails>
		<truckSizeStrictMatching>false</truckSizeStrictMatching>
		<locationStrictMatching>false</locationStrictMatching>	
	</options>
</buyingTariffSuggestionRequest>

Request samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://login.otms.com/ws/tariff/tariffSuggestion/v0/buying' \
--header 'Content-Type: application/xml' \
--data-raw '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<buyingTariffSuggestionRequest version="0.1" login="login" password="password">
	<orders>
		<order>
			<orderId></orderId>
			<clientCode></clientCode>
			<origin>
				<province>ACEH</province>
				<town>ACEH SELATAN</town>
				<county>KLUET UTARA</county>
			</origin>
			<destination>
				<province>ACEH</province>
				<town>ACEH TENGGARA</town>
				<county>LAWE ALA</county>
				<loading>false</loading>
			</destination>
			<packageType>A</packageType>
			<cargoType>1</cargoType>
			<transportMode>
				<transportTypes>
					<transportType>LTL</transportType>
				</transportTypes>
				<truckType>2</truckType>
			</transportMode>
			<timeSchedule>
				<pickupDate>2024-10-05T18:00:00</pickupDate>
				<deliveryDate>2024-10-08T18:00:00</deliveryDate>
			</timeSchedule>
			<cargoDetails>
				<quantity>100</quantity>
				<volume>100</volume>
				<weight>1000</weight>
				<insurance></insurance>
				<loadingMeter></loadingMeter>
			</cargoDetails>
		</order>
	</orders>
	<options>
		<suggestionMode>1</suggestionMode>
		<includeTariffAndVendorInfo>false</includeTariffAndVendorInfo>
		<includeRateDetails>false</includeRateDetails>
		<truckSizeStrictMatching>false</truckSizeStrictMatching>
		<locationStrictMatching>false</locationStrictMatching>	
	</options>
</buyingTariffSuggestionRequest>'

Responses

🟢200成功
application/xml
Successful operation
Body
version
string 
required
Response version number
responseCode
string 
optional
Global feedback code
successOrderCount
integer <int32>
optional
Number of orders successfully matched to price files
matchedTariffs
array[object (SuggestedTariff) {4}] 
optional
List of all matched price files. Only returned if the option to return price files is enabled in the request
sequence
integer <int32>
optional
Sequence number of the price file. Unique within a single request-response process. Used to correspond the price file with the calculated price
tariffName
string 
optional
Name of the price file
tariffTransportType
enum<string> 
optional
Transport type defined in the price file
Allowed values:
FTLLTLAIREXPRESSRAILWATER
vendor
object (SuggestedVendor) 
optional
buyingSuggestions
array[object (BuyingSuggestion) {4}] 
optional
List of calculated prices. One record per order
orderId
string 
optional
Identifier of the order. Corresponds to the identifier of the order in the request
success
boolean 
optional
Whether the order was matched to a price file
Default:
false
suggestions
array[object (SuggestedRate) {7}] 
optional
List of calculated prices for the order
responseCodes
array[string]
optional
List of response codes. Contains some information about the matching process
Error code prompt
object 
optional
Single request feedback code
4001
string 
optional
cannot match customer with customer code (only for SP users)
4002
string 
optional
customer code not provided (only for SP users)
4005
string 
optional
cannot match region with region name
4010
string 
optional
company has not yet enabled the custom field function
4011
string 
optional
A custom field was ignored because it was not enabled in the custom field configuration
4012
string 
optional
The options for the custom enumeration field cannot be matched with the provided logical name
4015
string 
optional
pick-up time and delivery time not provided
4020
string 
optional
request contains the transport type 'FTL', therefore the truck type cannot be '3'
4021
string 
optional
request contains the transportation type 'FTL', therefore the vehicle length cannot be empty
4022
string 
optional
conductor is not a predefined conductor for oTMS
4023
string 
optional
The vehicle nuclear load information provided in the request cannot be found to match the predefined vehicle nuclear load in oTMS
4024
string 
optional
The vehicle nuclear load information provided in the request matches multiple items within the predefined vehicle nuclear load of oTMS
4030
string 
optional
The pickup point information for order is missing
4031
string 
optional
The pickup point for order cannot be matched to the postal code of oTMS
4032
string 
optional
The delivery point of order has been matched with multiple postal codes of oTMS
4035
string 
optional
The delivery point information for order is missing
4036
string 
optional
The delivery point for order cannot be matched to the postal code of oTMS
4037
string 
optional
The delivery point for order has been matched with multiple postal codes for oTMS
4099
string 
optional
Other errors
Example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<buyingTariffSuggestionResponse version="0.1">
    <successOrderCount>1</successOrderCount>
    <matchedTariffs/>
    <buyingSuggestions>
        <buyingSuggestion>
            <orderId></orderId>
            <success>true</success>
            <suggestions>
                <suggestion>
                    <matchingLane>
                        <laneOrigin>
                            <province>ACEH</province>
                            <town>ACEH SELATAN</town>
                            <county>KLUET UTARA</county>
                            <zipcode>23771</zipcode>
                        </laneOrigin>
                        <laneDestination>
                            <province>ACEH</province>
                            <town>ACEH TENGGARA</town>
                            <county>LAWE ALAS</county>
                            <zipcode>24661</zipcode>
                        </laneDestination>
                    </matchingLane>
                    <rate>1500.00</rate>
                    <leadtime>48</leadtime>
                    <matchedByCustomFields>false</matchedByCustomFields>
                    <matchedByDefaultLane>false</matchedByDefaultLane>
                </suggestion>
            </suggestions>
            <responseCodes/>
        </buyingSuggestion>
    </buyingSuggestions>
</buyingTariffSuggestionResponse>
Previous
Oorder Custom Update
Next
Order cost update
Built with