Order Import

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.

Call Limitations

Currently, the call limit for this interface is set to a maximum of 40 requests per second per company.

Request

Header Params

Authorization

string

optional

Basic Authorization. If not empty, this value will be used for authentication. Otherwise, the username and password in the request body will be used.

Default:

Body Params application/xml

version

string

required

Version number of the request. Current version is 0.1

string

optional

Username for API caller authentication. Ignored if Authorization header is not empty.

password

string

optional

Password for API caller authentication. Ignored if Authorization header is not empty.

source

string

optional

orders

array[object (ImportedOrder) {40}]

required

List of orders to be imported. Up to 100 orders can be imported in one request

sequence

integer <int32>

required

Sequence number

clientCode

string

optional

oTMS offline customer company code (applicable for carrier account)

clientReferenceNumber

string

optional

System order identifier from the calling system

importId

string

optional

index

integer <int32>

optional

branch

string

optional

Region name in region settings

erpNumber

string

optional

Unique order number in external systems

orderNumber

string

optional

oTMS order number. If erpNumber is provided, the oTMS order number is considered invalid.

orderRemarks

string

optional

Additional order remarks.
Note: This field will not be displayed in “Order Details” or “Order Edit”.

allowUpdate

boolean

optional

Whether to allow updating orders. When marked as true, it allows updating existing orders. Default is false.

Default:

false

policyNumber

string

optional

Policy number

shipFrom

object (ImportedLocation)

optional

shipTo

object (ImportedLocation)

optional

timeSchedule

object (ImportedTimeSchedule)

required

orderLines

array[object (ImportedOrderLine) {7}]

optional

List of cargo/product details, which may be hidden

concealOrderLines

boolean

optional

Whether to hide cargo/product details from carriers, true hides, false shows

Default:

false

rejectDraft

boolean

optional

Whether to enable strict validation mode. Orders judged incomplete/inconsistent by the system will be rejected if this setting is true, and orders will enter the draft box if it is false.

Default:

false

autoProcessMode

integer <int32>

optional

Subsequent processing mode for orders, default is 1, only import. Optional values:
1 - Only import
2 - Import and release
3 - Import, release, and assign to carrier
4 - Import, release, and assign to truck

dispatchBy

integer <int32>

optional

Price file selection mode, default is 1, lowest price, optional values:
1 - Lowest price
2 - Shortest transportation time.

toTruck

object (ImportedTruck)

optional

cargoDetails

object (ImportedCargoDetails)

required

transportMode

object (ImportedTransportMode)

required

revenue

object (ImportedRevenue)

optional

cost

object (ImportedRevenue)

optional

vendorCode

string

optional

Carrier's company code in oTMS. When autoProcessMode=3 is specified, cost and carrier can be filled out, and the order will be assigned to a specific carrier at the specified price.

tempThreshold

object (ImportedTemperature)

optional

portableDevice

object (ImportedPortableDevice)

optional

customFields

object (ImportedCustomFields)

optional

requireEpod

boolean

optional

Requires electronic proof of delivery. When marked as true, an electronic proof of delivery is mandatory; false means it is optional. Default is false.

Default:

false

businessType

string

optional

Order type

sellingTariffSelection

integer <int32>

optional

Sales price file selection. Optional values:
1 - Lowest price
2 - Shortest transportation time

deliveryCode

boolean

optional

Whether to enable receiving code

Default:

false

sendEpodSms

boolean

optional

Send EPOD information to the receiver

Default:

false

orderEpodUploadType

enum<string>

optional

Proof of delivery type, including the following constants:
PAPERY_POD - Paper electronic proof of delivery
EPOD - Automatically generated electronic proof of delivery

Allowed values:

PAPERY_PODEPOD

ignoreLeadTime

boolean

optional

When enabled, when importing orders matching price files, the transportation lead time verification between orders and price files will be ignored. Default is false.

Default:

false

container

object (ImportedContainer)

optional

transportDistance

number

optional

Transportation distance

result

object (LiteOrderImportResultDto)

optional

shipToExternalId

string

optional

Receiver external ID, this node is used with either shipTo or shipToExternalId, defined in oTMS basic data (for shipper accounts) or partners (for carrier accounts).

shipFromExternalId

string

optional

Shipper external ID, this node is used with either shipFrom or shipFromExternalId, defined in oTMS basic data (for shipper accounts) or partners (for carrier accounts).

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<orderImportRequest version="0.1" login="login" password="password">
    <orders>
        <order sequence="1">
            <clientReferenceNumber></clientReferenceNumber>
            <sellingTariffSelection></sellingTariffSelection>
            <autoProcessMode></autoProcessMode>
            <clientCode></clientCode>
            <erpNumber>241024001</erpNumber>
            <branch></branch>
            <allowUpdate>true</allowUpdate>
            <shipFrom>
                <companyName>1006</companyName>
                <province>Basilan</province>
                <town>Tuburan</town>
                <county></county>
                <address>Basilan Tuburan</address>
                <loading>false</loading>
                <contact>
                    <name>LIYUN</name>
                    <mobile>1234560</mobile>
                </contact>
            </shipFrom>
            <shipTo>
                <companyName>2006</companyName>
                <province>Sulu</province>
                <town>Talipao</town>
                <county></county>
                <address>Sulu Talipao</address>
                <matchingStrategy>1</matchingStrategy>
                <loading>false</loading>
                <xttSupport>true</xttSupport>
                <contact>
                    <name>wang</name>
                    <phone>159258369</phone>
                    <phoneAreaCode>21</phoneAreaCode>
                    <mobile>1232123001</mobile>
                </contact>
            </shipTo>
            <timeSchedule>
                <pickupDate>2024-10-19</pickupDate>
                <deliveryDate>2024-10-21</deliveryDate>             
            </timeSchedule>
            <rejectDraft>false</rejectDraft>
            <autoProcessMode>0</autoProcessMode>
            <dispatchBy>1</dispatchBy>
            <cargoDetails>
                <totalQuantity>30</totalQuantity>
                <totalWeight>600</totalWeight>
                <totalVolume>0.71</totalVolume>
                <totalInsurance>0</totalInsurance>
            </cargoDetails>
            <transportMode>
                <transportType>LTL</transportType>
                <customTruckType>ABCD3</customTruckType>
                <truckLength>15.5</truckLength>
            </transportMode>
            <orderLines>
                <orderLine>
                    <cargoDescription>
                        <productCode>1011</productCode>
                        <productName>wenju</productName>
                        <unitType>60</unitType>
                    </cargoDescription>
                    <quantity>30</quantity>
                    <weight>500</weight>
                    <volume>0.45</volume>
                </orderLine>
            </orderLines>
        </order>
    </orders>
</orderImportRequest>

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request PUT 'https://login.otms.com/ws/orderImport' \
--header 'Authorization;' \
--header 'Content-Type: application/xml' \
--data-raw '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<orderImportRequest version="0.1" login="login" password="password">
    <orders>
        <order sequence="1">
            <clientReferenceNumber></clientReferenceNumber>
            <sellingTariffSelection></sellingTariffSelection>
            <autoProcessMode></autoProcessMode>
            <clientCode></clientCode>
            <erpNumber>241024001</erpNumber>
            <branch></branch>
            <allowUpdate>true</allowUpdate>
            <shipFrom>
                <companyName>1006</companyName>
                <province>Basilan</province>
                <town>Tuburan</town>
                <county></county>
                <address>Basilan Tuburan</address>
                <loading>false</loading>
                <contact>
                    <name>LIYUN</name>
                    <mobile>1234560</mobile>
                </contact>
            </shipFrom>
            <shipTo>
                <companyName>2006</companyName>
                <province>Sulu</province>
                <town>Talipao</town>
                <county></county>
                <address>Sulu Talipao</address>
                <matchingStrategy>1</matchingStrategy>
                <loading>false</loading>
                <xttSupport>true</xttSupport>
                <contact>
                    <name>wang</name>
                    <phone>159258369</phone>
                    <phoneAreaCode>21</phoneAreaCode>
                    <mobile>1232123001</mobile>
                </contact>
            </shipTo>
            <timeSchedule>
                <pickupDate>2024-10-19</pickupDate>
                <deliveryDate>2024-10-21</deliveryDate>             
            </timeSchedule>
            <rejectDraft>false</rejectDraft>
            <autoProcessMode>0</autoProcessMode>
            <dispatchBy>1</dispatchBy>
            <cargoDetails>
                <totalQuantity>30</totalQuantity>
                <totalWeight>600</totalWeight>
                <totalVolume>0.71</totalVolume>
                <totalInsurance>0</totalInsurance>
            </cargoDetails>
            <transportMode>
                <transportType>LTL</transportType>
                <customTruckType>ABCD3</customTruckType>
                <truckLength>15.5</truckLength>
            </transportMode>
            <orderLines>
                <orderLine>
                    <cargoDescription>
                        <productCode>1011</productCode>
                        <productName>wenju</productName>
                        <unitType>60</unitType>
                    </cargoDescription>
                    <quantity>30</quantity>
                    <weight>500</weight>
                    <volume>0.45</volume>
                </orderLine>
            </orderLines>
        </order>
    </orders>
</orderImportRequest>'

Responses

🟢200成功

application/xml

Successful operation

Body

version

string

required

Version number of the response

responseCode

array [object {2}]

optional

Global response code

string

required

Customer verification failed.

string

required

Unsupported request version.

processedOrders

string

optional

Number of orders processed

orders

array [object {8}]

optional

List of processed orders

sequence

integer <int32>

optional

Sequence number of the order

clientReferenceNumber

string

optional

Client reference number, obtained from the received order.
Note: This field will appear in the 'Notes' section of 'Order Details' or 'Order Edit'

importStatus

string

optional

Import status of the order, including the following constants:
NOT IMPORTED - Not imported
DRAFT - Draft (incomplete order information)
INBOX - Imported
RELEASED - Released
DISPATCHED - Dispatched

responseCodes

array [object {1}]

optional

List of response codes for the order, detailed explanation of the import result, may be empty

responseCodeParameters

object

optional

orderNumber

string

optional

New oTMS order number assigned by the system

erpNumber

string

optional

Unique order number in the external system

errorMsgs

array[string]

optional

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<orderImportResponse version="0.1">
    <responseCode></responseCode>
    <processedOrders>1</processedOrders>
    <orders>
        <order sequence="1">
            <clientReferenceNumber></clientReferenceNumber>
            <importStatus>INBOX</importStatus>
            <responseCodes>
                <responseCode>
                    <code>1017</code>
                </responseCode>
                <responseCode>
                    <code>1052</code>
                </responseCode>
            </responseCodes>
            <orderNumber>test002121</orderNumber>
        </order>
    </orders>
</orderImportResponse>

Configuration Instructions#

Important Notes#

Call Limitations#

Request

Request samples

Responses

Configuration Instructions

Important Notes

Call Limitations