shipPointImport

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 10 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 number is 0.1

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.

shipPoints

array[object (ImportedShipPoint) {31}]

required

List of pick-up and delivery points for creation or update

sequence

integer <int32>

required

Sequence number

clientCode

string

optional

oTMS offline customer company code (for carrier accounts)

clientReferenceNumber

string

optional

Identifier of the system order being called

type

enum<string>

required

Type of pickup and delivery point. Can take the following values:
0 - Pickup Point
1 - Delivery Point
2 - Hub

Allowed values:

PICKUP_POINTDELIVERY_POINTHUB

companyName

string

required

Name of the pickup and delivery point

nationalCenter

boolean

optional

National distribution center. Default value is false

Default:

false

regionalCenter

boolean

optional

Regional distribution center. Default value is false

Default:

false

myLocation

string

optional

Belongs to region

selectType

enum<string>

required

Region selection type, default value is 2 - HQ Only, can take the following values:
1 - All Regions
2 - HQ Only
3 - Specific Region

Allowed values:

ALLHQ_ONLYSELECTED

Default:

selectedLocations

array[string]

optional

Available locations. Must be filled if selectType is 3.

>= 0 items<= 500 items

externalId

string

optional

External identification code

province

string

optional

Province

town

string

optional

City

county

string

optional

District/County

address

string

optional

Address

shippingId

string

optional

Area code

zipcode

string

optional

6-digit postal code

Match pattern:

\d{6}

updateZipcode

boolean

optional

Whether to update provincial/city/district and postal code information. Default value is false

Default:

false

contact

object (ImportedContactPerson)

optional

boolean

optional

Loading fee. Default value is false

Default:

false

supportXtt

boolean

optional

XTT support flag. Default value is false

Default:

false

supportSms

boolean

optional

SMS notification flag. Default value is false

Default:

false

remark

string

optional

Remarks

driverOperateRadius

string

optional

Operable distance

latitude

number <double>

optional

Latitude

longitude

number <double>

optional

Longitude

notifyDistancePercentage

string

optional

Midway distance. This data is ignored when importing pick-up point information

notifyRadius

string

optional

Entry circle distance

customFields

object (ImportedShipPointCustomFields)

optional

workingDays

array[object (ImportedWorkingDay) {5}]

optional

Working days

nonWorkingDays

array[object (ImportedWorkingDay) {5}]

optional

Non-working days

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<shipPointImportRequest version="0.1" login="username" password="password">
    <shipPoints>
        <shipPoint sequence="1">
            <clientReferenceNumber>sh00105001</clientReferenceNumber>
            <type>0</type>
            <companyName>Shanghai 001 co.,ltd.</companyName>
            <myLocation>Shanghai DC</myLocation>
            <selectType>3</selectType>
            <selectedLocations>
                <location>Shanghai DC</location>
                <location>Hangzhou DC</location>
            </selectedLocations>
            <externalId>11223344</externalId>
            <province>shanghai</province>
            <town>shanghai</town>
            <county/>
            <address>1606 Ganghui plaza</address>
            <zipcode>200020</zipcode>
            <contact>
                <name>Mr. Zhang</name>
                <phone>12345678</phone>
                <phoneAreaCode>021</phoneAreaCode>
                <mobile>13812345678</mobile>
                <email>peterzhang@testmail.com</email>
            </contact>
            <loading>true</loading>
            <supportXtt>true</supportXtt>
            <supportSms>true</supportSms>
            <remark/>
            <customFields>
                <customText1>sh</customText1>
                <customNum1>100</customNum1>
            </customFields>
        </shipPoint>
        <shipPoint sequence="2">
            <clientReferenceNumber>sh00105002</clientReferenceNumber>
            <type>1</type>
            <companyName>Hangzhou 001 co.,ltd.</companyName>
            <myLocation>Hangzhou DC</myLocation>
            <selectType>1</selectType>
            <externalId>22334455</externalId>
            <province>zhejiang</province>
            <town>hangzhou</town>
            <county/>
            <address>9999 Lian Hua Road</address>
            <zipcode>311010</zipcode>
            <contact>
                <name>Johnny</name>
                <phone>87654321</phone>
                <phoneAreaCode>0571</phoneAreaCode>
                <mobile>13887654321</mobile>
                <email>Johnny@testmail.com</email>
            </contact>
            <loading>false</loading>
            <supportXtt>true</supportXtt>
            <supportSms>true</supportSms>
            <remark/>
            <customFields>
                <customText1>hz</customText1>
                <customNum1>50</customNum1>
            </customFields>
        </shipPoint>
    </shipPoints>
</shipPointImportRequest>

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request PUT 'https://login.otms.com/ws/shipPointImport' \
--header 'Authorization;' \
--header 'Content-Type: application/xml' \
--data-raw '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<shipPointImportRequest version="0.1" login="username" password="password">
    <shipPoints>
        <shipPoint sequence="1">
            <clientReferenceNumber>sh00105001</clientReferenceNumber>
            <type>0</type>
            <companyName>Shanghai 001 co.,ltd.</companyName>
            <myLocation>Shanghai DC</myLocation>
            <selectType>3</selectType>
            <selectedLocations>
                <location>Shanghai DC</location>
                <location>Hangzhou DC</location>
            </selectedLocations>
            <externalId>11223344</externalId>
            <province>shanghai</province>
            <town>shanghai</town>
            <county/>
            <address>1606 Ganghui plaza</address>
            <zipcode>200020</zipcode>
            <contact>
                <name>Mr. Zhang</name>
                <phone>12345678</phone>
                <phoneAreaCode>021</phoneAreaCode>
                <mobile>13812345678</mobile>
                <email>peterzhang@testmail.com</email>
            </contact>
            <loading>true</loading>
            <supportXtt>true</supportXtt>
            <supportSms>true</supportSms>
            <remark/>
            <customFields>
                <customText1>sh</customText1>
                <customNum1>100</customNum1>
            </customFields>
        </shipPoint>
        <shipPoint sequence="2">
            <clientReferenceNumber>sh00105002</clientReferenceNumber>
            <type>1</type>
            <companyName>Hangzhou 001 co.,ltd.</companyName>
            <myLocation>Hangzhou DC</myLocation>
            <selectType>1</selectType>
            <externalId>22334455</externalId>
            <province>zhejiang</province>
            <town>hangzhou</town>
            <county/>
            <address>9999 Lian Hua Road</address>
            <zipcode>311010</zipcode>
            <contact>
                <name>Johnny</name>
                <phone>87654321</phone>
                <phoneAreaCode>0571</phoneAreaCode>
                <mobile>13887654321</mobile>
                <email>Johnny@testmail.com</email>
            </contact>
            <loading>false</loading>
            <supportXtt>true</supportXtt>
            <supportSms>true</supportSms>
            <remark/>
            <customFields>
                <customText1>hz</customText1>
                <customNum1>50</customNum1>
            </customFields>
        </shipPoint>
    </shipPoints>
</shipPointImportRequest>'

Responses

🟢200成功

application/xml

successful operation

Body

version

string

required

Response version number

responseCode

array [object {3}]

optional

Global response code

string

optional

Customer verification failed.

string

optional

Unsupported request version.

string

optional

There is too much delivery point data in the request.

processedShipPoints

string

optional

Number of processed pick-up and delivery points

shipPoints

array [object {5}]

optional

List of processed pick-up and delivery points

sequence

integer <int32>

optional

Sequence number

clientReferenceNumber

string

optional

Client reference number, obtained from the received pickup and delivery point.

importStatus

string

optional

Pickup and delivery point import status, including the following constants:
ADDED
UPDATED
REMOVED
FAILED

responseCodes

array [object {27}]

optional

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

responseCodeParameters

object

optional

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<shipPointImportResponse version="0.1">
    <responseCode/>
    <processedShipPoints>2</processedShipPoints>
    <shipPoints>
        <shipPoint sequence="1">
            <clientReferenceNumber>sh00105001</clientReferenceNumber>
            <importStatus>UPDATED</importStatus>
            <responseCodes>
                <responseCode>
                    <code>1014</code>
                </responseCode>
                <responseCode>
                    <code>1031</code>
                </responseCode>
                <responseCode>
                    <code>1040</code>
                </responseCode>
            </responseCodes>
        </shipPoint>
        <shipPoint sequence="2">
            <clientReferenceNumber>sh00105002</clientReferenceNumber>
            <importStatus>UPDATED</importStatus>
            <responseCodes>
                <responseCode>
                    <code>1018</code>
                </responseCode>
                <responseCode>
                    <code>1031</code>
                </responseCode>
            </responseCodes>
        </shipPoint>
    </shipPoints>
</shipPointImportResponse>

Important Notes#

Call Limitations#

Request

Request samples

Responses

Important Notes

Call Limitations