Order Update

PUT

/ws/orderUpdate

Order Update

Order Update Interface

Through the Order Update Interface, large volumes of orders from different external systems, such as ERP systems and WMS systems, can be updated in bulk. The maximum number of orders that can be updated in a single request is 100.

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 20 requests per second per company.

Request

Header Params

Authorization

string

optional

Basic Authorization. If not empty, this value will be used for identity authentication with priority. Otherwise, the username and password in the request message 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 the Authorization header is not empty.

password

string

optional

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

orders

array[object (UpdatedOrder) {27}]

required

List of orders to be updated. A single request can update up to 100 orders.

sequence

integer <int32>

required

Sequence number

clientCode

string

optional

oTMS offline customer company code (for carrier accounts)

clientReferenceNumber

string

optional

Identifier of the system calling the order

importId

string

optional

index

integer <int32>

optional

branch

string

optional

Region name in the regional settings

erpNumber

string

optional

Unique order number in the external system

orderNumber

string

optional

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

orderRemarks

string

optional

Additional order remarks

policyNumber

string

optional

Policy number

shipFrom

object (UpdatedLocation)

optional

shipTo

object (UpdatedLocation)

optional

timeSchedule

object (UpdatedTimeSchedule)

optional

orderLines

array[object (UpdatedOrderLine) {7}]

optional

List of cargo/product details, which may be hidden. If there are updates to the order lines, all order lines of the order must be provided.

>= 0 items<= 10000 items

concealOrderLines

boolean

optional

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

Default:

false

rejectDraft

boolean

optional

Whether to enable strict validation mode. Orders deemed incomplete/inconsistent by the system will be rejected if this setting is true, otherwise orders will go into the draft box

Default:

false

cargoDetails

object (UpdatedCargoDetails)

optional

transportMode

object (UpdatedTransportMode)

optional

revenue

object (UpdatedRevenue)

optional

cost

object (UpdatedRevenue)

optional

tempThreshold

object (UpdatedTemperature)

optional

customFields

object (UpdatedCustomFields)

optional

requireEpod

boolean

optional

Require electronic return receipt. When marked as true, an electronic return receipt is mandatory, false means it is optional.

Default:

false

businessType

string

optional

Order type

container

object (UpdatedContainer)

optional

transportDistance

number

optional

Transport distance

result

object (OrderImportResult)

optional

onlyUpdateCustomFiled

boolean

optional

Indicates whether to update only custom fields of the order or order lines

Default:

false

Example

<?xml version="1.0" encoding="UTF-8"?>
<orderUpdateRequest version="0.1" login="login" password="password">
    <orders>
        <order sequence="1">
            <branch></branch>
            <columnName></columnName>
            <orderNumber>AXDHBMAV009887</orderNumber>
            <allowUpdate>true</allowUpdate>
            <cargoDetails>
                <totalWeight>900</totalWeight>
                <totalVolume>3</totalVolume>
                <cargoType>1</cargoType>
            </cargoDetails>            
            <orderLines>
                <orderLine>
                    <cargoDescription>
                        <productCode>1211</productCode>
                        <productName>wenju</productName>
                        <unitType>2</unitType>
                    </cargoDescription>
                    <customFields>
                        <customText5></customText5>
                        <customText38>12.00</customText38>
                        <customText46>LC00151</customText46>
                        <customText50>2022-10-25</customText50>
                        <customText55>Y151-1802</customText55>
                    </customFields>
                    <quantity>50</quantity>
                    <weight>900</weight>
                    <volume>3</volume>
                    <remarks></remarks>
                </orderLine>
            </orderLines>
        </order>
    </orders>
</orderUpdateRequest>

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request PUT 'https://login.otms.com/ws/orderUpdate' \
--header 'Authorization;' \
--header 'Content-Type: application/xml' \
--data-raw '<?xml version="1.0" encoding="UTF-8"?>
<orderUpdateRequest version="0.1" login="login" password="password">
    <orders>
        <order sequence="1">
            <branch></branch>
            <columnName></columnName>
            <orderNumber>AXDHBMAV009887</orderNumber>
            <allowUpdate>true</allowUpdate>
            <cargoDetails>
                <totalWeight>900</totalWeight>
                <totalVolume>3</totalVolume>
                <cargoType>1</cargoType>
            </cargoDetails>            
            <orderLines>
                <orderLine>
                    <cargoDescription>
                        <productCode>1211</productCode>
                        <productName>wenju</productName>
                        <unitType>2</unitType>
                    </cargoDescription>
                    <customFields>
                        <customText5></customText5>
                        <customText38>12.00</customText38>
                        <customText46>LC00151</customText46>
                        <customText50>2022-10-25</customText50>
                        <customText55>Y151-1802</customText55>
                    </customFields>
                    <quantity>50</quantity>
                    <weight>900</weight>
                    <volume>3</volume>
                    <remarks></remarks>
                </orderLine>
            </orderLines>
        </order>
    </orders>
</orderUpdateRequest>'

Responses

🟢200成功

application/xml

Successful operation

Body

version

string

required

Version number of the response

responseCode

string

optional

Global feedback code

processedOrders

string

optional

Number of orders processed

orders

array[object (UpdateResult) {7}]

optional

List of processed orders

sequence

integer <int32>

optional

Sequence number

erpNumber

string

optional

ERP order number

orderNumber

string

optional

oTMS order number

updateStatus

string

optional

DRAFT - Order is in draft state after update
UPDATED - Order was successfully updated
FAILED - Order update failed
NOT UPDATED - No changes were made to the order

strResponseCodes

array[string]

optional

Array of string response codes

errorColumnName

string

optional

Name of the column where the error occurred

strErrorMsgs

array[string]

optional

Array of error messages

Error code prompt

object

optional

Single request feedback code

7000

string

optional

customer code not found.

7001

string

optional

is an invalid data type.

7002

string

optional

branch not recognized, or user permissions do not match.

7003

string

optional

The matching result for order is not unique.

7004

string

optional

user's regional permissions do not match.

7005

string

optional

order that attempted to update was not imported through the import interface. Update rejected.

7006

string

optional

Order does not belong to the company.

7007

string

optional

does not allow updating the quantity, weight, volume, and insured value of split orders.

7008

string

optional

Orders with received receipts are not allowed to be updated.

7009

string

optional

Order does not exist.

7010

string

optional

Orders with a shortage are not allowed to be updated.

7011

string

optional

region does not exist.

7012

string

optional

delivery time data is invalid.

7013

string

optional

The delivery time data for is invalid.

7014

string

optional

shipFromExternalId shipper external code not found.

7015

string

optional

shipToExternalId recipient external code not found.

7016

string

optional

shipper must provide an email or phone number to subscribe to external order tracking.

7017

string

optional

The recipient must provide an email or phone number to subscribe to external order tracking.

7018

string

optional

The external code of the shipper is duplicated.

7019

string

optional

The recipient's external code is duplicated.

7020

string

optional

The pickup address and delivery address are the same.

7021

string

optional

incomplete transportation information (1. lack of transportation mode, 2. lack of truck type for less than truckload/full truckload transportation mode, 3. lack of vehicle length for full truckload transportation mode).

7022

string

optional

TruckType vehicle type does not match.

7023

string

optional

TruckType vehicle type matching result is not unique.

7024

string

optional

Product category is invalid.

7025

string

optional

lacks information on goods/products. At least one of the externalId or cargoDescription must be provided in the order details.

7026

string

optional

externalId goods (products) external code not found.

7027

string

optional

Duplicate external code for goods (products).

7028

string

optional

The low temperature threshold for temperature alarm shall not exceed the high temperature threshold.

7029

string

optional

The type of goods in order does not support temperature alarms.

7030

string

optional

The packaging type of order does not require a temperature controlled box.

7031

string

optional

The recipient's oTMS postal code only matches the township.

7032

string

optional

The recipient's postal code only matches the 6-digit postal code.

7033

string

optional

The recipient's oTMS postal code does not match.

7034

string

optional

The recipient's oTMS postal code matches the 6-digit and township.

7035

string

optional

The recipient's oTMS postal code only matches the district or county.

7036

string

optional

shipper's oTMS postal code matches to township.

7037

string

optional

The shipper's oTMS postal code only matches the 6-digit postal code.

7038

string

optional

shipper's oTMS postal code does not match.

7039

string

optional

The shipper's oTMS postal code matches both the 6-digit and township codes.

7040

string

optional

shipper's oTMS postal code only matches with district/county.

7041

string

optional

The weight or volume of order 7041 exceeds the company's limit.

7042

string

optional

Invalid temperature control box number.

7043

string

optional

custom fields cannot be recognized - it is possible that the company has already cancelled the custom fields. The order cannot be updated.

7044

string

optional

Undefined custom field enumeration values. The order cannot be updated.

7045

string

optional

Custom fields not enabled, will ignore updating custom fields in orders.

7046

string

optional

Order is missing mandatory custom fields. The order cannot be updated.

7047

string

optional

Reject draft status orders. When rejectDraft is true, incomplete orders will be rejected instead of entering the draft box.

7048

string

optional

order details are missing mandatory custom fields. The order cannot be updated.

7049

string

optional

Invalid order type.

7050

string

optional

The cargo information for order is incomplete.

7051

string

optional

When updating orders through erpNumber, the carrier account must provide a client code.

7052

string

optional

The price file for order does not match.

7053

string

optional

order information is incomplete.

7054

string

optional

order optimization in progress, update rejected.

7100

string

optional

other errors.

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<orderUpdateResponse version="0.1">
    <responseCode></responseCode>
    <processedOrders>1</processedOrders>
    <orders>
        <order sequence="1">
            <erpNumber>241108001</erpNumber>
            <orderNumber>AXDHBMAV009887</orderNumber>
            <updateStatus>UPDATED</updateStatus>
            <responseCodes/>
        </order>
    </orders>
</orderUpdateResponse>

Carrier Export

Order Dispatch

Order Update

Order Update Interface#

Configuration Instructions#

Important Notes#

Call Limitations#

Request

Request samples

Responses

Order Update Interface

Configuration Instructions

Important Notes

Call Limitations