This is the API descriptor for the Nomad Pilot API, responsible for shipping and logistics processing. Developed by Samarkand Global in partnership with SF Express, eSinotrans, sto. Read the documentation online at Nomad API Suite.

  • Install for node with npm install nomad_pilot_cli
  • Install for python with pip install nomad-pilot-cli
  • Install for Maven users groupId, com.gitlab.samarkand-nomad; artifactId, nomad-pilot-cli

This is the documentation for version 1.43.1 of the API. Last update on Sep 30, 2021.

Base URL
https://nomad.samarkand-global.cn/pilot

Send an authentication token in the x-ca-key header to authenticate with the API.


Callback

The callback endpoints of logistics, available provider haiku

Path parameters
  • store Required / string

    ID of the logistics provider.

Body
Responses
POST /callback/{store}
curl \
 -X POST https://nomad.samarkand-global.cn/pilot/callback/{store} \
 -H "x-ca-key: $API_KEY" \
 -H "Content-Type: application/xml" \
 -d '{"deliveryOrder":{"deliveryOrderCode":"string","deliveryOrderId":"string","warehouseCode":"string","orderType":"string","status":"string","outBizCode":"string","confirmType":"string","orderConfirmTime":"string","operatorCode":"string","operatorName":"string","operateTime":"string","storageFee":"string","logisticsCode":"string","logisticsName":"string","expressCode":"string"}}'
Request example
{
  "deliveryOrder": {
    "deliveryOrderCode": "string",
    "deliveryOrderId": "string",
    "warehouseCode": "string",
    "orderType": "string",
    "status": "string",
    "outBizCode": "string",
    "confirmType": "string",
    "orderConfirmTime": "string",
    "operatorCode": "string",
    "operatorName": "string",
    "operateTime": "string",
    "storageFee": "string",
    "logisticsCode": "string",
    "logisticsName": "string",
    "expressCode": "string"
  }
}
Response example (200)
{
  "success": "string",
  "errorcode": "string",
  "errormsg": "string"
}
Response example (400)
{
  "success": "string",
  "errorcode": "string",
  "errormsg": "string"
}
Response example (500)
{
  "success": "string",
  "errorcode": "string",
  "errormsg": "string"
}

QueryCarrier

Query all carrier name or specific carrier

Query parameters
Responses
  • 200 object

    Success

  • 400

    Invalid input

  • 500 object

    Failed

GET /carriers/
curl \
 -X GET https://nomad.samarkand-global.cn/pilot/carriers/ \
 -H "x-ca-key: $API_KEY"
Response example (200)
{
  "code": 42,
  "message": "string",
  "data": [
    "string"
  ],
  "total": 42
}
Response example (500)
{
  "code": 42,
  "message": "string",
  "data": [
    "string"
  ],
  "total": 42
}

QueryFreightForward

Query a specfic waybill in Freight Forwarding DB

Path parameters
  • carrier Required / string

    Carrier name to ship, e.g. samarkand.sfexpress.test

Query parameters
  • status Required / string

    package status, available options: UNPROCESSED, PACKED, PROCESSED, SHIPPED, CANCEL, ALL

    Values are UNPROCESSED, PACKED, PROCESSED, SHIPPED, CANCEL, and ALL. Default value is UNPROCESSED.

  • page_no Required / integer(int32)

    Page number, between 1 and 1000

    Minimum value is 1, maximum value is 1000. Default value is 1.

  • page_size Required / integer(int32)

    Page size, options: [1, 10, 50, 100, 1000]

    Values are 1, 10, 50, 100, and 1000. Default value is 10.

  • created_range string

    the time range of package update, use ISO_8601 format here, e.g. 2020-07-10T13:00:00Z/2020-07-11T15:30:00Z

Responses
  • 200 object

    Success

  • 400

    Invalid input

  • 500 object

    Failed

GET /freight-forward/{carrier}
curl \
 -X GET https://nomad.samarkand-global.cn/pilot/freight-forward/{carrier}?status=UNPROCESSED&page_no=42&page_size=1 \
 -H "x-ca-key: $API_KEY"
Response example (200)
{
  "code": 42,
  "message": "string",
  "data": [
    "string"
  ],
  "total": 42
}
Response example (500)
{
  "code": 42,
  "message": "string",
  "data": [
    "string"
  ],
  "total": 42
}

FreightForward

Requests waybill data from specified carrier in Freight Forwarding DB. Receives waybill details in return, most carriers provide id and PDF packing label

Path parameters
  • carrier Required / string

    Carrier name to ship, e.g. samarkand.sfexpress.test

Body
  • operation Required / string

    Operation for Freight Forwarding DB, available options: QUERY, QUERY_PRODUCT, QUERY_WAYBILL. QUERY is deprecated

    Default value is QUERY_WAYBILL.

  • itemKeys array[string]

    Item keys, the key value could be tracking reference(QUERY_WAYBILL) or product sku(QUERY_PRODUCT)

  • pageNo integer

    Page number

    Minimum value is 1.

  • pageSize integer

    Page size

    Minimum value is 1, maximum value is 100.

Responses
  • 200 object

    Success

  • 400

    Invalid input

  • 500 object

    Failed

POST /freight-forward/{carrier}
curl \
 -X POST https://nomad.samarkand-global.cn/pilot/freight-forward/{carrier} \
 -H "x-ca-key: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"operation":"QUERY_WAYBILL","itemKeys":["SF1035215690597","SF1025950147480"],"pageNo":1,"pageSize":10}'
Request example
{
  "operation": "QUERY_WAYBILL",
  "itemKeys": [
    "SF1035215690597",
    "SF1025950147480"
  ],
  "pageNo": 1,
  "pageSize": 10
}
Response example (200)
{
  "code": 42,
  "message": "string",
  "data": [
    "string"
  ],
  "total": 42
}
Response example (500)
{
  "code": 42,
  "message": "string",
  "data": [
    "string"
  ],
  "total": 42
}

QuickShip

Requests waybill creation from specified carrier. Receives waybill details in return, most carriers provide id and PDF packing label

Path parameters
  • carrier Required / string

    Carrier name to ship, e.g. samarkand.sfexpress.test

Body
  • dimension object

    Dimensions of package

    • weight number(float) Deprecated

      The whole package, not just the products. kilogram.

    • height number(float)

      the height of current package. centimetre.

    • length number(float)

      the length of current package. centimetre.

    • width number(float)

      the width of current package. centimetre.

  • shipFrom object
  • shipTo object
  • bill object
  • orderRef string

    Order reference number in ERP application

  • Order reference number from retailers, e-commerce platform, e.g. Youzan, Little Red

  • Package tracking reference from logistics company

  • orderTime string

    ISO 8601 format, '2019-01-19T18:30:52.442118+00:00' or '2019-01-19T18:30:52+00:00'

  • grossWeight number

    Use Kilogram as the basic unit of mass.

  • netWeight number

    Use Kilogram as the basic unit of mass.

  • totalPrice number(float)

    The total price of this package, not including any discount and tax.

  • currency string

    Price makes sense under an explicit currency, available options: RMB, CNY, USD, GBP

    Default value is RMB.

  • massUnit string

    weight Unit of measurement

    Default value is Kilogram.

  • lengthUnit string

    length Unit of measurement

    Default value is Centimetre.

  • the domestic delivery vendor, 2 available options: [SF, YTO]

    Default value is SF.

  • createdAt string

    The time when current order was created. ISO_8601 format

  • updatedAt string

    The time when current order was updated. ISO_8601 format

  • payMethod string
  • payAmount number(float)

    The actual amount paid for the order.

  • payId string

    The payment number generated by eCommerce platform such as Youzan

  • paidAt string

    The time when the pay was made. ISO_8601 format

  • productsTotalTax number(float)

    The sum tax of all products in current order, including Non-cash deduction amount.

  • shippingCost number(float)

    The shipping cost of current order, excluding the shipping cost on each contained products. If delivery free, just set 0.

  • nonCashDeductionAmount number(float)

    Amount that deducted by non-cash, e.g. member points, virtual currency, voucher code, etc.

  • customerNote string

    The special note from the buyer.

  • cancelReason string

    The cancel reason of current package.

  • warehouseCode string

    The code of warehouse for this package

  • customerIdRef string

    The ID of buyer on current third party platform.

  • insuranceFee number(float)

    The insurance fee of current shipping.

  • expressType string

    International logistics express type. BC for 901, 229; CC for 902

  • paymentPayId string

    The payment number generated by payment tool such as WeChat Pay

  • platformName string

    The e-commerce platform name, available options: youzan, pdd, nomad

    Default value is youzan.

  • checkPoint string

    log express check point, turn on it by input "enable", default is disabled

  • items array[object]
    • skuNumber Required / string

      The sku Number of this product

    • barcode string

      The barcode of this product

    • quantity Required / integer(int32)

      The quantity of this product in current order

    • price Required / number

      The price of this product, not including any discount and tax.

Responses
  • 200 object

    Waybill creation successed

    • code integer(int32)
    • message string
    • data object
      • shipmentId string
      • scanFormId string
      • scanFormUrl string
      • waybillId string
      • orderSn string Deprecated

        Deprecated. Replaced by 'orderRef'.

      • orderRef string

        Order reference number. Default is from Odoo.

      • Order reference number. Also could be from retailers, e.g. Youzan.

      • the domestic delivery vender for sinotrans

      • The delivery status of one package, 9 possible values are below statues will be loaded into PilotDeliveryStatus().statuses. If status begin with 'DOMESTIC', it means order has been declared in customs. @PREPARE_ORDER @SORT_ORDER @PACK_ORDER @ORDER_OUTBOUND @CUSTOM_CLEAR @CUSTOM_CLEAR_COMPLETE @FLIGHT_DEPARTURE @FLIGHT_ARRIVE
        @DOMESTIC_DELIVERY @DOMESTIC_IN_TRANSIT @DOMESTIC_SIGNING @DOMESTIC_SUCCESS @DOMESTIC_RETURNED @DOMESTIC_FAILURE

      • deliveryNote string

        A note marked by the carrier, could be changed at any time.

      • The URL of delivery slip.

      • trackingUrl string

        The URL of waybill tracking.

      • checkPoints array[string]

        The details of express checkpoints.

      • weightFailed boolean

        Comparison of gross weight with expected weight(the sum of net weight of items * 1.2 + 1)

    • connectorResponses array[object]
      • input string

        The input of a NomadOperation, usually it's JSON format.

      • mappingName string

        The name of mapping class.

      • api array[string]
      • Raw data of current HTTP request to the third party server, easy for debug.

      • code integer(int32)
      • response string
      • responseEn string
      • platform string
      • requestCount integer(int32)

        The number of requests against the third party in one Nomad request.

      • responseTime integer(int32)

        The response time of current NomadOperation request, including sub-NomadOperation. The time unit is millisecond.

    • responseTime integer(int32)

      The response time of current NomadOperation request, including sub-NomadOperation. The time unit is millisecond.

  • 400

    Invalid input

  • 500 object

    Waybill creation failed

    • code integer(int32)
    • message string
    • data object
      • shipmentId string
      • scanFormId string
      • scanFormUrl string
      • waybillId string
      • orderSn string Deprecated

        Deprecated. Replaced by 'orderRef'.

      • orderRef string

        Order reference number. Default is from Odoo.

      • Order reference number. Also could be from retailers, e.g. Youzan.

      • the domestic delivery vender for sinotrans

      • The delivery status of one package, 9 possible values are below statues will be loaded into PilotDeliveryStatus().statuses. If status begin with 'DOMESTIC', it means order has been declared in customs. @PREPARE_ORDER @SORT_ORDER @PACK_ORDER @ORDER_OUTBOUND @CUSTOM_CLEAR @CUSTOM_CLEAR_COMPLETE @FLIGHT_DEPARTURE @FLIGHT_ARRIVE
        @DOMESTIC_DELIVERY @DOMESTIC_IN_TRANSIT @DOMESTIC_SIGNING @DOMESTIC_SUCCESS @DOMESTIC_RETURNED @DOMESTIC_FAILURE

      • deliveryNote string

        A note marked by the carrier, could be changed at any time.

      • The URL of delivery slip.

      • trackingUrl string

        The URL of waybill tracking.

      • checkPoints array[string]

        The details of express checkpoints.

      • weightFailed boolean

        Comparison of gross weight with expected weight(the sum of net weight of items * 1.2 + 1)

    • connectorResponses array[object]
      • input string

        The input of a NomadOperation, usually it's JSON format.

      • mappingName string

        The name of mapping class.

      • api array[string]
      • Raw data of current HTTP request to the third party server, easy for debug.

      • code integer(int32)
      • response string
      • responseEn string
      • platform string
      • requestCount integer(int32)

        The number of requests against the third party in one Nomad request.

      • responseTime integer(int32)

        The response time of current NomadOperation request, including sub-NomadOperation. The time unit is millisecond.

    • responseTime integer(int32)

      The response time of current NomadOperation request, including sub-NomadOperation. The time unit is millisecond.

POST /quick-ship/{carrier}
curl \
 -X POST https://nomad.samarkand-global.cn/pilot/quick-ship/{carrier} \
 -H "x-ca-key: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"dimension":{"weight":42.0,"height":42.0,"length":42.0,"width":42.0},"shipFrom":{"firstName":"John","lastName":"string","address1":"string","address2":"string","county":"string","city":"string","state":"string","country":"string","zip":"string","tin":"string","phone":"string","countryCode":142,"idCard":"string","email":"string","company":"string","ecommerceWebsiteUserId":"string"},"shipTo":{"firstName":"John","lastName":"string","address1":"string","address2":"string","county":"string","cit...}'
Request example
{
  "dimension": {
    "weight": 42.0,
    "height": 42.0,
    "length": 42.0,
    "width": 42.0
  },
  "shipFrom": {
    "firstName": "John",
    "lastName": "string",
    "address1": "string",
    "address2": "string",
    "county": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "zip": "string",
    "tin": "string",
    "phone": "string",
    "countryCode": 142,
    "idCard": "string",
    "email": "string",
    "company": "string",
    "ecommerceWebsiteUserId": "string"
  },
  "shipTo": {
    "firstName": "John",
    "lastName": "string",
    "address1": "string",
    "address2": "string",
    "county": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "zip": "string",
    "tin": "string",
    "phone": "string",
    "countryCode": 142,
    "idCard": "string",
    "email": "string",
    "company": "string",
    "ecommerceWebsiteUserId": "string"
  },
  "bill": {
    "firstName": "John",
    "lastName": "string",
    "address1": "string",
    "address2": "string",
    "county": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "zip": "string",
    "tin": "string",
    "phone": "string",
    "countryCode": 142,
    "idCard": "string",
    "email": "string",
    "company": "string",
    "ecommerceWebsiteUserId": "string"
  },
  "orderRef": "SO224571",
  "sellerOrderRef": "E202010152223470377011119610GZ",
  "trackingReference": "SF1032566311525",
  "orderTime": "string",
  "grossWeight": 1.53,
  "netWeight": 1.53,
  "totalPrice": 532.8,
  "currency": "RMB",
  "massUnit": "Kilogram",
  "lengthUnit": "Centimetre",
  "domesticDeliveryCompany": "SF",
  "createdAt": "2019-07-12T13:13:52.004637+01:00",
  "updatedAt": "2019-07-12T13:13:52.004637+01:00",
  "payMethod": "EASIPAY",
  "payMerchantName": "Paypal",
  "payAmount": 611.08,
  "payId": "2014030120394812",
  "paidAt": "2019-07-12T13:13:52.004637+01:00",
  "productsTotalTax": 53.28,
  "shippingCost": 25,
  "nonCashDeductionAmount": 0,
  "customerNote": "This package is very important.",
  "cancelReason": "The customers updated the address.",
  "warehouseCode": "718595286704",
  "customerIdRef": "string",
  "insuranceFee": 2.5,
  "expressType": "BC",
  "paymentPayId": "191028195204000214",
  "platformName": "youzan",
  "checkPoint": "string",
  "items": [
    {
      "skuNumber": "SMK123",
      "barcode": 5060280371714,
      "quantity": 7,
      "price": 21.3
    }
  ]
}
Response example (200)
{
  "code": 42,
  "message": "string",
  "data": {
    "shipmentId": "string",
    "scanFormId": "string",
    "scanFormUrl": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "string",
    "deliveryNote": "string",
    "deliverySlipUrl": "string",
    "trackingUrl": "string",
    "checkPoints": [
      "@accept_time 2020-05-01 04:59:38; @accept_address 伦敦; @remark 寄方准备快件中,当前地点: 【GB London Delivery Centre (英國倫敦收派中心)】; @opcode 647; @zoneGmt 1",
      "...",
      "@accept_time 2020-05-13 09:10:49; @accept_address 江门市;  @remark 在官网'运单资料&签收图',可查看签收人信息; @opcode 8000; @stayWhyCode  1; @zoneGmt 8"
    ],
    "weightFailed": false
  },
  "connectorResponses": [
    {
      "input": "{\"product_id\": 12121}",
      "mappingName": "GetProductOp",
      "api": [
        "string"
      ],
      "httpRequestRawData": "-",
      "code": 42,
      "response": "string",
      "responseEn": "string",
      "platform": "youzan",
      "requestCount": 1,
      "responseTime": 1000
    }
  ],
  "responseTime": 1000
}
Response example (500)
{
  "code": 42,
  "message": "string",
  "data": {
    "shipmentId": "string",
    "scanFormId": "string",
    "scanFormUrl": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "string",
    "deliveryNote": "string",
    "deliverySlipUrl": "string",
    "trackingUrl": "string",
    "checkPoints": [
      "@accept_time 2020-05-01 04:59:38; @accept_address 伦敦; @remark 寄方准备快件中,当前地点: 【GB London Delivery Centre (英國倫敦收派中心)】; @opcode 647; @zoneGmt 1",
      "...",
      "@accept_time 2020-05-13 09:10:49; @accept_address 江门市;  @remark 在官网'运单资料&签收图',可查看签收人信息; @opcode 8000; @stayWhyCode  1; @zoneGmt 8"
    ],
    "weightFailed": false
  },
  "connectorResponses": [
    {
      "input": "{\"product_id\": 12121}",
      "mappingName": "GetProductOp",
      "api": [
        "string"
      ],
      "httpRequestRawData": "-",
      "code": 42,
      "response": "string",
      "responseEn": "string",
      "platform": "youzan",
      "requestCount": 1,
      "responseTime": 1000
    }
  ],
  "responseTime": 1000
}

Ship

Update waybill details for specified carrier.

Path parameters
  • carrier Required / string

    Carrier name to ship, e.g. samarkand.sfexpress.test

Body
  • dimension object

    Dimensions of package

    • weight number(float) Deprecated

      The whole package, not just the products. kilogram.

    • height number(float)

      the height of current package. centimetre.

    • length number(float)

      the length of current package. centimetre.

    • width number(float)

      the width of current package. centimetre.

  • shipFrom object
  • shipTo object
  • bill object
  • orderRef string

    Order reference number in ERP application

  • Order reference number from retailers, e-commerce platform, e.g. Youzan, Little Red

  • trackingReference Required / string

    Package tracking reference from logistics company

  • orderTime string

    ISO 8601 format, '2019-01-19T18:30:52.442118+00:00' or '2019-01-19T18:30:52+00:00'

  • grossWeight number

    Use Kilogram as the basic unit of mass.

  • netWeight number

    Use Kilogram as the basic unit of mass.

  • totalPrice number(float)

    The total price of this package, not including any discount and tax.

  • currency string

    Price makes sense under an explicit currency, available options: RMB, CNY, USD, GBP

    Default value is RMB.

  • massUnit string

    weight Unit of measurement

    Default value is Kilogram.

  • lengthUnit string

    length Unit of measurement

    Default value is Centimetre.

  • the domestic delivery vendor, 2 available options: [SF, YTO]

    Default value is SF.

  • createdAt string

    The time when current order was created. ISO_8601 format

  • updatedAt string

    The time when current order was updated. ISO_8601 format

  • payMethod string
  • payAmount number(float)

    The actual amount paid for the order.

  • payId string

    The payment number generated by eCommerce platform such as Youzan

  • paidAt string

    The time when the pay was made. ISO_8601 format

  • productsTotalTax number(float)

    The sum tax of all products in current order, including Non-cash deduction amount.

  • shippingCost number(float)

    The shipping cost of current order, excluding the shipping cost on each contained products. If delivery free, just set 0.

  • nonCashDeductionAmount number(float)

    Amount that deducted by non-cash, e.g. member points, virtual currency, voucher code, etc.

  • customerNote string

    The special note from the buyer.

  • cancelReason string

    The cancel reason of current package.

  • warehouseCode string

    The code of warehouse for this package

  • customerIdRef string

    The ID of buyer on current third party platform.

  • insuranceFee number(float)

    The insurance fee of current shipping.

  • expressType string

    International logistics express type. BC for 901, 229; CC for 902

  • paymentPayId string

    The payment number generated by payment tool such as WeChat Pay

  • platformName string

    The e-commerce platform name, available options: youzan, pdd, nomad

    Default value is youzan.

  • checkPoint string

    log express check point, turn on it by input "enable", default is disabled

  • items array[object]

    Contents of package

  • status string

    package status, 4 available options: UNPROCESSED, PACKED, PROCESSED, CANCEL. Status SHIPPED is updated by confirm api

  • carrier string

    nomad express carrier name

  • express delivery slip url

  • createdDate string

    waybill create date

  • packedDate string

    waybill packed date

  • processedDate string

    waybill processed date

  • shippedDate string

    waybill shipped date

  • cancelDate string

    waybill cancel date

  • customsNote string

    Customs order declaration results

Responses
  • 200 object

    Waybill update successed

    • code integer(int32)
    • message string
    • data object
      • shipmentId string
      • scanFormId string
      • scanFormUrl string
      • waybillId string
      • orderSn string Deprecated

        Deprecated. Replaced by 'orderRef'.

      • orderRef string

        Order reference number. Default is from Odoo.

      • Order reference number. Also could be from retailers, e.g. Youzan.

      • the domestic delivery vender for sinotrans

      • The delivery status of one package, 9 possible values are below statues will be loaded into PilotDeliveryStatus().statuses. If status begin with 'DOMESTIC', it means order has been declared in customs. @PREPARE_ORDER @SORT_ORDER @PACK_ORDER @ORDER_OUTBOUND @CUSTOM_CLEAR @CUSTOM_CLEAR_COMPLETE @FLIGHT_DEPARTURE @FLIGHT_ARRIVE
        @DOMESTIC_DELIVERY @DOMESTIC_IN_TRANSIT @DOMESTIC_SIGNING @DOMESTIC_SUCCESS @DOMESTIC_RETURNED @DOMESTIC_FAILURE

      • deliveryNote string

        A note marked by the carrier, could be changed at any time.

      • The URL of delivery slip.

      • trackingUrl string

        The URL of waybill tracking.

      • checkPoints array[string]

        The details of express checkpoints.

      • weightFailed boolean

        Comparison of gross weight with expected weight(the sum of net weight of items * 1.2 + 1)

    • connectorResponses array[object]
      • input string

        The input of a NomadOperation, usually it's JSON format.

      • mappingName string

        The name of mapping class.

      • api array[string]
      • Raw data of current HTTP request to the third party server, easy for debug.

      • code integer(int32)
      • response string
      • responseEn string
      • platform string
      • requestCount integer(int32)

        The number of requests against the third party in one Nomad request.

      • responseTime integer(int32)

        The response time of current NomadOperation request, including sub-NomadOperation. The time unit is millisecond.

    • responseTime integer(int32)

      The response time of current NomadOperation request, including sub-NomadOperation. The time unit is millisecond.

  • 400

    Invalid input

  • 409

    Waybill update failed, package is on the way

  • 500 object

    Waybill update failed

    • code integer(int32)
    • message string
    • data object
      • shipmentId string
      • scanFormId string
      • scanFormUrl string
      • waybillId string
      • orderSn string Deprecated

        Deprecated. Replaced by 'orderRef'.

      • orderRef string

        Order reference number. Default is from Odoo.

      • Order reference number. Also could be from retailers, e.g. Youzan.

      • the domestic delivery vender for sinotrans

      • The delivery status of one package, 9 possible values are below statues will be loaded into PilotDeliveryStatus().statuses. If status begin with 'DOMESTIC', it means order has been declared in customs. @PREPARE_ORDER @SORT_ORDER @PACK_ORDER @ORDER_OUTBOUND @CUSTOM_CLEAR @CUSTOM_CLEAR_COMPLETE @FLIGHT_DEPARTURE @FLIGHT_ARRIVE
        @DOMESTIC_DELIVERY @DOMESTIC_IN_TRANSIT @DOMESTIC_SIGNING @DOMESTIC_SUCCESS @DOMESTIC_RETURNED @DOMESTIC_FAILURE

      • deliveryNote string

        A note marked by the carrier, could be changed at any time.

      • The URL of delivery slip.

      • trackingUrl string

        The URL of waybill tracking.

      • checkPoints array[string]

        The details of express checkpoints.

      • weightFailed boolean

        Comparison of gross weight with expected weight(the sum of net weight of items * 1.2 + 1)

    • connectorResponses array[object]
      • input string

        The input of a NomadOperation, usually it's JSON format.

      • mappingName string

        The name of mapping class.

      • api array[string]
      • Raw data of current HTTP request to the third party server, easy for debug.

      • code integer(int32)
      • response string
      • responseEn string
      • platform string
      • requestCount integer(int32)

        The number of requests against the third party in one Nomad request.

      • responseTime integer(int32)

        The response time of current NomadOperation request, including sub-NomadOperation. The time unit is millisecond.

    • responseTime integer(int32)

      The response time of current NomadOperation request, including sub-NomadOperation. The time unit is millisecond.

PUT /ship/{carrier}
curl \
 -X PUT https://nomad.samarkand-global.cn/pilot/ship/{carrier} \
 -H "x-ca-key: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"dimension":{"weight":42.0,"height":42.0,"length":42.0,"width":42.0},"shipFrom":{"firstName":"John","lastName":"string","address1":"string","address2":"string","county":"string","city":"string","state":"string","country":"string","zip":"string","tin":"string","phone":"string","countryCode":142,"idCard":"string","email":"string","company":"string","ecommerceWebsiteUserId":"string"},"shipTo":{"firstName":"John","lastName":"string","address1":"string","address2":"string","county":"string","cit...}'
Request example
{
  "dimension": {
    "weight": 42.0,
    "height": 42.0,
    "length": 42.0,
    "width": 42.0
  },
  "shipFrom": {
    "firstName": "John",
    "lastName": "string",
    "address1": "string",
    "address2": "string",
    "county": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "zip": "string",
    "tin": "string",
    "phone": "string",
    "countryCode": 142,
    "idCard": "string",
    "email": "string",
    "company": "string",
    "ecommerceWebsiteUserId": "string"
  },
  "shipTo": {
    "firstName": "John",
    "lastName": "string",
    "address1": "string",
    "address2": "string",
    "county": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "zip": "string",
    "tin": "string",
    "phone": "string",
    "countryCode": 142,
    "idCard": "string",
    "email": "string",
    "company": "string",
    "ecommerceWebsiteUserId": "string"
  },
  "bill": {
    "firstName": "John",
    "lastName": "string",
    "address1": "string",
    "address2": "string",
    "county": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "zip": "string",
    "tin": "string",
    "phone": "string",
    "countryCode": 142,
    "idCard": "string",
    "email": "string",
    "company": "string",
    "ecommerceWebsiteUserId": "string"
  },
  "orderRef": "SO224571",
  "sellerOrderRef": "E202010152223470377011119610GZ",
  "trackingReference": "SF1032566311525",
  "orderTime": "string",
  "grossWeight": 1.53,
  "netWeight": 1.53,
  "totalPrice": 532.8,
  "currency": "RMB",
  "massUnit": "Kilogram",
  "lengthUnit": "Centimetre",
  "domesticDeliveryCompany": "SF",
  "createdAt": "2019-07-12T13:13:52.004637+01:00",
  "updatedAt": "2019-07-12T13:13:52.004637+01:00",
  "payMethod": "EASIPAY",
  "payMerchantName": "Paypal",
  "payAmount": 611.08,
  "payId": "2014030120394812",
  "paidAt": "2019-07-12T13:13:52.004637+01:00",
  "productsTotalTax": 53.28,
  "shippingCost": 25,
  "nonCashDeductionAmount": 0,
  "customerNote": "This package is very important.",
  "cancelReason": "The customers updated the address.",
  "warehouseCode": "718595286704",
  "customerIdRef": "string",
  "insuranceFee": 2.5,
  "expressType": "BC",
  "paymentPayId": "191028195204000214",
  "platformName": "youzan",
  "checkPoint": "string",
  "items": [
    {
      "name": "string",
      "nameCn": "测试",
      "barcode": "string",
      "skuNumber": "SMK123",
      "quantity": 7,
      "price": 21.3,
      "brand": "string",
      "quantityUom": "50G",
      "hsCode": "string",
      "countryOfOrigin": "string",
      "goldjet": {
        "goodsPtcode": "string"
      },
      "grossWeight": 42.0,
      "netWeight": 42.0,
      "customsUnitCode": "142, 007, 瓶, ...",
      "customsUnitCodePackage": "142, 011, 140",
      "customsUnitCodeWeight": "035(means 千克, kilogram)",
      "customsFilingId": "string",
      "spec": "25mm",
      "model": "iPhone XR",
      "ingredients": "发酵乳杆菌Lc40(CECT5716),麦芽糊精,蔗糖,抗坏血酸钠",
      "customsUnitCodeCn": "瓶",
      "countryOfOriginIso": "RU"
    }
  ],
  "status": "string",
  "carrier": "samarkand.sfexpress.test",
  "deliverySlipUrl": "string",
  "createdDate": "string",
  "packedDate": "string",
  "processedDate": "string",
  "shippedDate": "string",
  "cancelDate": "string",
  "customsNote": "string"
}
Response example (200)
{
  "code": 42,
  "message": "string",
  "data": {
    "shipmentId": "string",
    "scanFormId": "string",
    "scanFormUrl": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "string",
    "deliveryNote": "string",
    "deliverySlipUrl": "string",
    "trackingUrl": "string",
    "checkPoints": [
      "@accept_time 2020-05-01 04:59:38; @accept_address 伦敦; @remark 寄方准备快件中,当前地点: 【GB London Delivery Centre (英國倫敦收派中心)】; @opcode 647; @zoneGmt 1",
      "...",
      "@accept_time 2020-05-13 09:10:49; @accept_address 江门市;  @remark 在官网'运单资料&签收图',可查看签收人信息; @opcode 8000; @stayWhyCode  1; @zoneGmt 8"
    ],
    "weightFailed": false
  },
  "connectorResponses": [
    {
      "input": "{\"product_id\": 12121}",
      "mappingName": "GetProductOp",
      "api": [
        "string"
      ],
      "httpRequestRawData": "-",
      "code": 42,
      "response": "string",
      "responseEn": "string",
      "platform": "youzan",
      "requestCount": 1,
      "responseTime": 1000
    }
  ],
  "responseTime": 1000
}
Response example (500)
{
  "code": 42,
  "message": "string",
  "data": {
    "shipmentId": "string",
    "scanFormId": "string",
    "scanFormUrl": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "string",
    "deliveryNote": "string",
    "deliverySlipUrl": "string",
    "trackingUrl": "string",
    "checkPoints": [
      "@accept_time 2020-05-01 04:59:38; @accept_address 伦敦; @remark 寄方准备快件中,当前地点: 【GB London Delivery Centre (英國倫敦收派中心)】; @opcode 647; @zoneGmt 1",
      "...",
      "@accept_time 2020-05-13 09:10:49; @accept_address 江门市;  @remark 在官网'运单资料&签收图',可查看签收人信息; @opcode 8000; @stayWhyCode  1; @zoneGmt 8"
    ],
    "weightFailed": false
  },
  "connectorResponses": [
    {
      "input": "{\"product_id\": 12121}",
      "mappingName": "GetProductOp",
      "api": [
        "string"
      ],
      "httpRequestRawData": "-",
      "code": 42,
      "response": "string",
      "responseEn": "string",
      "platform": "youzan",
      "requestCount": 1,
      "responseTime": 1000
    }
  ],
  "responseTime": 1000
}

Ship

Requests waybill creation from specified carrier. Receives waybill details in return, most carriers provide id and PDF packing label

Path parameters
  • carrier Required / string

    Carrier name to ship, e.g. samarkand.sfexpress.test

Body
  • dimension object

    Dimensions of package

    • weight number(float) Deprecated

      The whole package, not just the products. kilogram.

    • height number(float)

      the height of current package. centimetre.

    • length number(float)

      the length of current package. centimetre.

    • width number(float)

      the width of current package. centimetre.

  • shipFrom object
    • firstName string
    • lastName string
    • address1 string
    • address2 string
    • county string

      The county of current city. 县/区, e.g. 西湖区

    • city string
    • state string
    • country Required / string
    • zip Required / string

      Postal Code / Zip, please set to . if not known

    • tin string

      TIN; The Chinese ID number of current person.

    • phone Required / string

      The phone of customer

    • countryCode string

      The customs code of country.

    • idCard string

      The Chinese ID number of current person (will be removed since we are using tin).

    • email string
    • company string
    • The user ID of that e-commerce website.

  • shipTo object
    • firstName string
    • lastName string
    • address1 string
    • address2 string
    • county string

      The county of current city. 县/区, e.g. 西湖区

    • city string
    • state string
    • country Required / string
    • zip Required / string

      Postal Code / Zip, please set to . if not known

    • tin string

      TIN; The Chinese ID number of current person.

    • phone Required / string

      The phone of customer

    • countryCode string

      The customs code of country.

    • idCard string

      The Chinese ID number of current person (will be removed since we are using tin).

    • email string
    • company string
    • The user ID of that e-commerce website.

  • bill object
  • orderRef string

    Order reference number in ERP application

  • sellerOrderRef Required / string

    Order reference number from retailers, e-commerce platform, e.g. Youzan, Little Red

  • Package tracking reference from logistics company

  • orderTime string

    ISO 8601 format, '2019-01-19T18:30:52.442118+00:00' or '2019-01-19T18:30:52+00:00'

  • grossWeight number

    Use Kilogram as the basic unit of mass.

  • netWeight number

    Use Kilogram as the basic unit of mass.

  • totalPrice number(float)

    The total price of this package, not including any discount and tax.

  • currency Required / string

    Price makes sense under an explicit currency, available options: RMB, CNY, USD, GBP

    Default value is RMB.

  • massUnit Required / string

    weight Unit of measurement

    Default value is Kilogram.

  • lengthUnit Required / string

    length Unit of measurement

    Default value is Centimetre.

  • the domestic delivery vendor, 2 available options: [SF, YTO]

    Default value is SF.

  • createdAt string

    The time when current order was created. ISO_8601 format

  • updatedAt string

    The time when current order was updated. ISO_8601 format

  • payMethod string
  • payAmount number(float)

    The actual amount paid for the order.

  • payId string

    The payment number generated by eCommerce platform such as Youzan

  • paidAt string

    The time when the pay was made. ISO_8601 format

  • productsTotalTax number(float)

    The sum tax of all products in current order, including Non-cash deduction amount.

  • shippingCost number(float)

    The shipping cost of current order, excluding the shipping cost on each contained products. If delivery free, just set 0.

  • nonCashDeductionAmount number(float)

    Amount that deducted by non-cash, e.g. member points, virtual currency, voucher code, etc.

  • customerNote string

    The special note from the buyer.

  • cancelReason string

    The cancel reason of current package.

  • warehouseCode string

    The code of warehouse for this package

  • customerIdRef string

    The ID of buyer on current third party platform.

  • insuranceFee number(float)

    The insurance fee of current shipping.

  • expressType Required / string

    International logistics express type. BC for 901, 229; CC for 902

  • paymentPayId string

    The payment number generated by payment tool such as WeChat Pay

  • platformName string

    The e-commerce platform name, available options: youzan, pdd, nomad

    Default value is youzan.

  • checkPoint string

    log express check point, turn on it by input "enable", default is disabled

  • items array[object]

    Contents of package

Responses
  • 200 object

    Waybill creation successed

    • code integer(int32)
    • message string
    • data object
      • shipmentId string
      • scanFormId string
      • scanFormUrl string
      • waybillId string
      • orderSn string Deprecated

        Deprecated. Replaced by 'orderRef'.

      • orderRef string

        Order reference number. Default is from Odoo.

      • Order reference number. Also could be from retailers, e.g. Youzan.

      • the domestic delivery vender for sinotrans

      • The delivery status of one package, 9 possible values are below statues will be loaded into PilotDeliveryStatus().statuses. If status begin with 'DOMESTIC', it means order has been declared in customs. @PREPARE_ORDER @SORT_ORDER @PACK_ORDER @ORDER_OUTBOUND @CUSTOM_CLEAR @CUSTOM_CLEAR_COMPLETE @FLIGHT_DEPARTURE @FLIGHT_ARRIVE
        @DOMESTIC_DELIVERY @DOMESTIC_IN_TRANSIT @DOMESTIC_SIGNING @DOMESTIC_SUCCESS @DOMESTIC_RETURNED @DOMESTIC_FAILURE

      • deliveryNote string

        A note marked by the carrier, could be changed at any time.

      • The URL of delivery slip.

      • trackingUrl string

        The URL of waybill tracking.

      • checkPoints array[string]

        The details of express checkpoints.

      • weightFailed boolean

        Comparison of gross weight with expected weight(the sum of net weight of items * 1.2 + 1)

    • connectorResponses array[object]
      • input string

        The input of a NomadOperation, usually it's JSON format.

      • mappingName string

        The name of mapping class.

      • api array[string]
      • Raw data of current HTTP request to the third party server, easy for debug.

      • code integer(int32)
      • response string
      • responseEn string
      • platform string
      • requestCount integer(int32)

        The number of requests against the third party in one Nomad request.

      • responseTime integer(int32)

        The response time of current NomadOperation request, including sub-NomadOperation. The time unit is millisecond.

    • responseTime integer(int32)

      The response time of current NomadOperation request, including sub-NomadOperation. The time unit is millisecond.

  • 400

    Invalid input

  • 500 object

    Waybill creation failed

    • code integer(int32)
    • message string
    • data object
      • shipmentId string
      • scanFormId string
      • scanFormUrl string
      • waybillId string
      • orderSn string Deprecated

        Deprecated. Replaced by 'orderRef'.

      • orderRef string

        Order reference number. Default is from Odoo.

      • Order reference number. Also could be from retailers, e.g. Youzan.

      • the domestic delivery vender for sinotrans

      • The delivery status of one package, 9 possible values are below statues will be loaded into PilotDeliveryStatus().statuses. If status begin with 'DOMESTIC', it means order has been declared in customs. @PREPARE_ORDER @SORT_ORDER @PACK_ORDER @ORDER_OUTBOUND @CUSTOM_CLEAR @CUSTOM_CLEAR_COMPLETE @FLIGHT_DEPARTURE @FLIGHT_ARRIVE
        @DOMESTIC_DELIVERY @DOMESTIC_IN_TRANSIT @DOMESTIC_SIGNING @DOMESTIC_SUCCESS @DOMESTIC_RETURNED @DOMESTIC_FAILURE

      • deliveryNote string

        A note marked by the carrier, could be changed at any time.

      • The URL of delivery slip.

      • trackingUrl string

        The URL of waybill tracking.

      • checkPoints array[string]

        The details of express checkpoints.

      • weightFailed boolean

        Comparison of gross weight with expected weight(the sum of net weight of items * 1.2 + 1)

    • connectorResponses array[object]
      • input string

        The input of a NomadOperation, usually it's JSON format.

      • mappingName string

        The name of mapping class.

      • api array[string]
      • Raw data of current HTTP request to the third party server, easy for debug.

      • code integer(int32)
      • response string
      • responseEn string
      • platform string
      • requestCount integer(int32)

        The number of requests against the third party in one Nomad request.

      • responseTime integer(int32)

        The response time of current NomadOperation request, including sub-NomadOperation. The time unit is millisecond.

    • responseTime integer(int32)

      The response time of current NomadOperation request, including sub-NomadOperation. The time unit is millisecond.

POST /ship/{carrier}
curl \
 -X POST https://nomad.samarkand-global.cn/pilot/ship/{carrier} \
 -H "x-ca-key: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"dimension":{"weight":42.0,"height":42.0,"length":42.0,"width":42.0},"shipFrom":{"firstName":"John","lastName":"string","address1":"string","address2":"string","county":"string","city":"string","state":"string","country":"string","zip":"string","tin":"string","phone":"string","countryCode":142,"idCard":"string","email":"string","company":"string","ecommerceWebsiteUserId":"string"},"shipTo":{"firstName":"John","lastName":"string","address1":"string","address2":"string","county":"string","cit...}'
Request example
{
  "dimension": {
    "weight": 42.0,
    "height": 42.0,
    "length": 42.0,
    "width": 42.0
  },
  "shipFrom": {
    "firstName": "John",
    "lastName": "string",
    "address1": "string",
    "address2": "string",
    "county": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "zip": "string",
    "tin": "string",
    "phone": "string",
    "countryCode": 142,
    "idCard": "string",
    "email": "string",
    "company": "string",
    "ecommerceWebsiteUserId": "string"
  },
  "shipTo": {
    "firstName": "John",
    "lastName": "string",
    "address1": "string",
    "address2": "string",
    "county": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "zip": "string",
    "tin": "string",
    "phone": "string",
    "countryCode": 142,
    "idCard": "string",
    "email": "string",
    "company": "string",
    "ecommerceWebsiteUserId": "string"
  },
  "bill": {
    "firstName": "John",
    "lastName": "string",
    "address1": "string",
    "address2": "string",
    "county": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "zip": "string",
    "tin": "string",
    "phone": "string",
    "countryCode": 142,
    "idCard": "string",
    "email": "string",
    "company": "string",
    "ecommerceWebsiteUserId": "string"
  },
  "orderRef": "SO224571",
  "sellerOrderRef": "E202010152223470377011119610GZ",
  "trackingReference": "SF1032566311525",
  "orderTime": "string",
  "grossWeight": 1.53,
  "netWeight": 1.53,
  "totalPrice": 532.8,
  "currency": "RMB",
  "massUnit": "Kilogram",
  "lengthUnit": "Centimetre",
  "domesticDeliveryCompany": "SF",
  "createdAt": "2019-07-12T13:13:52.004637+01:00",
  "updatedAt": "2019-07-12T13:13:52.004637+01:00",
  "payMethod": "EASIPAY",
  "payMerchantName": "Paypal",
  "payAmount": 611.08,
  "payId": "2014030120394812",
  "paidAt": "2019-07-12T13:13:52.004637+01:00",
  "productsTotalTax": 53.28,
  "shippingCost": 25,
  "nonCashDeductionAmount": 0,
  "customerNote": "This package is very important.",
  "cancelReason": "The customers updated the address.",
  "warehouseCode": "718595286704",
  "customerIdRef": "string",
  "insuranceFee": 2.5,
  "expressType": "BC",
  "paymentPayId": "191028195204000214",
  "platformName": "youzan",
  "checkPoint": "string",
  "items": [
    {
      "name": "string",
      "nameCn": "测试",
      "barcode": "string",
      "skuNumber": "SMK123",
      "quantity": 7,
      "price": 21.3,
      "brand": "string",
      "quantityUom": "50G",
      "hsCode": "string",
      "countryOfOrigin": "string",
      "goldjet": {
        "goodsPtcode": "string"
      },
      "grossWeight": 42.0,
      "netWeight": 42.0,
      "customsUnitCode": "142, 007, 瓶, ...",
      "customsUnitCodePackage": "142, 011, 140",
      "customsUnitCodeWeight": "035(means 千克, kilogram)",
      "customsFilingId": "string",
      "spec": "25mm",
      "model": "iPhone XR",
      "ingredients": "发酵乳杆菌Lc40(CECT5716),麦芽糊精,蔗糖,抗坏血酸钠",
      "customsUnitCodeCn": "瓶",
      "countryOfOriginIso": "RU"
    }
  ]
}
Response example (200)
{
  "code": 42,
  "message": "string",
  "data": {
    "shipmentId": "string",
    "scanFormId": "string",
    "scanFormUrl": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "string",
    "deliveryNote": "string",
    "deliverySlipUrl": "string",
    "trackingUrl": "string",
    "checkPoints": [
      "@accept_time 2020-05-01 04:59:38; @accept_address 伦敦; @remark 寄方准备快件中,当前地点: 【GB London Delivery Centre (英國倫敦收派中心)】; @opcode 647; @zoneGmt 1",
      "...",
      "@accept_time 2020-05-13 09:10:49; @accept_address 江门市;  @remark 在官网'运单资料&签收图',可查看签收人信息; @opcode 8000; @stayWhyCode  1; @zoneGmt 8"
    ],
    "weightFailed": false
  },
  "connectorResponses": [
    {
      "input": "{\"product_id\": 12121}",
      "mappingName": "GetProductOp",
      "api": [
        "string"
      ],
      "httpRequestRawData": "-",
      "code": 42,
      "response": "string",
      "responseEn": "string",
      "platform": "youzan",
      "requestCount": 1,
      "responseTime": 1000
    }
  ],
  "responseTime": 1000
}
Response example (500)
{
  "code": 42,
  "message": "string",
  "data": {
    "shipmentId": "string",
    "scanFormId": "string",
    "scanFormUrl": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "string",
    "deliveryNote": "string",
    "deliverySlipUrl": "string",
    "trackingUrl": "string",
    "checkPoints": [
      "@accept_time 2020-05-01 04:59:38; @accept_address 伦敦; @remark 寄方准备快件中,当前地点: 【GB London Delivery Centre (英國倫敦收派中心)】; @opcode 647; @zoneGmt 1",
      "...",
      "@accept_time 2020-05-13 09:10:49; @accept_address 江门市;  @remark 在官网'运单资料&签收图',可查看签收人信息; @opcode 8000; @stayWhyCode  1; @zoneGmt 8"
    ],
    "weightFailed": false
  },
  "connectorResponses": [
    {
      "input": "{\"product_id\": 12121}",
      "mappingName": "GetProductOp",
      "api": [
        "string"
      ],
      "httpRequestRawData": "-",
      "code": 42,
      "response": "string",
      "responseEn": "string",
      "platform": "youzan",
      "requestCount": 1,
      "responseTime": 1000
    }
  ],
  "responseTime": 1000
}

ShipConfirm

Confirm waybill with specified carrier.

Path parameters
  • carrier Required / string

    Carrier name to ship, e.g. samarkand.sfexpress.test

Body
  • dimension object

    Dimensions of package

    • weight number(float) Deprecated

      The whole package, not just the products. kilogram.

    • height number(float)

      the height of current package. centimetre.

    • length number(float)

      the length of current package. centimetre.

    • width number(float)

      the width of current package. centimetre.

  • shipFrom object
  • shipTo object
  • bill object
  • orderRef string

    Order reference number in ERP application

  • Order reference number from retailers, e-commerce platform, e.g. Youzan, Little Red

  • trackingReference Required / string

    Package tracking reference from logistics company

  • orderTime string

    ISO 8601 format, '2019-01-19T18:30:52.442118+00:00' or '2019-01-19T18:30:52+00:00'

  • grossWeight number

    Use Kilogram as the basic unit of mass.

  • netWeight number

    Use Kilogram as the basic unit of mass.

  • totalPrice number(float)

    The total price of this package, not including any discount and tax.

  • currency string

    Price makes sense under an explicit currency, available options: RMB, CNY, USD, GBP

    Default value is RMB.

  • massUnit string

    weight Unit of measurement

    Default value is Kilogram.

  • lengthUnit string

    length Unit of measurement

    Default value is Centimetre.

  • the domestic delivery vendor, 2 available options: [SF, YTO]

    Default value is SF.

  • createdAt string

    The time when current order was created. ISO_8601 format

  • updatedAt string

    The time when current order was updated. ISO_8601 format

  • payMethod string
  • payAmount number(float)

    The actual amount paid for the order.

  • payId string

    The payment number generated by eCommerce platform such as Youzan

  • paidAt string

    The time when the pay was made. ISO_8601 format

  • productsTotalTax number(float)

    The sum tax of all products in current order, including Non-cash deduction amount.

  • shippingCost number(float)

    The shipping cost of current order, excluding the shipping cost on each contained products. If delivery free, just set 0.

  • nonCashDeductionAmount number(float)

    Amount that deducted by non-cash, e.g. member points, virtual currency, voucher code, etc.

  • customerNote string

    The special note from the buyer.

  • cancelReason string

    The cancel reason of current package.

  • warehouseCode string

    The code of warehouse for this package

  • customerIdRef string

    The ID of buyer on current third party platform.

  • insuranceFee number(float)

    The insurance fee of current shipping.

  • expressType string

    International logistics express type. BC for 901, 229; CC for 902

  • paymentPayId string

    The payment number generated by payment tool such as WeChat Pay

  • platformName string

    The e-commerce platform name, available options: youzan, pdd, nomad

    Default value is youzan.

  • checkPoint string

    log express check point, turn on it by input "enable", default is disabled

  • items array[object]

    Contents of package

Responses
  • 200 object

    Waybill confirm successed

    • code integer(int32)
    • message string
    • data object
      • shipmentId string
      • scanFormId string
      • scanFormUrl string
      • waybillId string
      • orderSn string Deprecated

        Deprecated. Replaced by 'orderRef'.

      • orderRef string

        Order reference number. Default is from Odoo.

      • Order reference number. Also could be from retailers, e.g. Youzan.

      • the domestic delivery vender for sinotrans

      • The delivery status of one package, 9 possible values are below statues will be loaded into PilotDeliveryStatus().statuses. If status begin with 'DOMESTIC', it means order has been declared in customs. @PREPARE_ORDER @SORT_ORDER @PACK_ORDER @ORDER_OUTBOUND @CUSTOM_CLEAR @CUSTOM_CLEAR_COMPLETE @FLIGHT_DEPARTURE @FLIGHT_ARRIVE
        @DOMESTIC_DELIVERY @DOMESTIC_IN_TRANSIT @DOMESTIC_SIGNING @DOMESTIC_SUCCESS @DOMESTIC_RETURNED @DOMESTIC_FAILURE

      • deliveryNote string

        A note marked by the carrier, could be changed at any time.

      • The URL of delivery slip.

      • trackingUrl string

        The URL of waybill tracking.

      • checkPoints array[string]

        The details of express checkpoints.

      • weightFailed boolean

        Comparison of gross weight with expected weight(the sum of net weight of items * 1.2 + 1)

    • connectorResponses array[object]
      • input string

        The input of a NomadOperation, usually it's JSON format.

      • mappingName string

        The name of mapping class.

      • api array[string]
      • Raw data of current HTTP request to the third party server, easy for debug.

      • code integer(int32)
      • response string
      • responseEn string
      • platform string
      • requestCount integer(int32)

        The number of requests against the third party in one Nomad request.

      • responseTime integer(int32)

        The response time of current NomadOperation request, including sub-NomadOperation. The time unit is millisecond.

    • responseTime integer(int32)

      The response time of current NomadOperation request, including sub-NomadOperation. The time unit is millisecond.

  • 400

    Invalid input

  • 500 object

    Waybill confirm failed

    • code integer(int32)
    • message string
    • data object
      • shipmentId string
      • scanFormId string
      • scanFormUrl string
      • waybillId string
      • orderSn string Deprecated

        Deprecated. Replaced by 'orderRef'.

      • orderRef string

        Order reference number. Default is from Odoo.

      • Order reference number. Also could be from retailers, e.g. Youzan.

      • the domestic delivery vender for sinotrans

      • The delivery status of one package, 9 possible values are below statues will be loaded into PilotDeliveryStatus().statuses. If status begin with 'DOMESTIC', it means order has been declared in customs. @PREPARE_ORDER @SORT_ORDER @PACK_ORDER @ORDER_OUTBOUND @CUSTOM_CLEAR @CUSTOM_CLEAR_COMPLETE @FLIGHT_DEPARTURE @FLIGHT_ARRIVE
        @DOMESTIC_DELIVERY @DOMESTIC_IN_TRANSIT @DOMESTIC_SIGNING @DOMESTIC_SUCCESS @DOMESTIC_RETURNED @DOMESTIC_FAILURE

      • deliveryNote string

        A note marked by the carrier, could be changed at any time.

      • The URL of delivery slip.

      • trackingUrl string

        The URL of waybill tracking.

      • checkPoints array[string]

        The details of express checkpoints.

      • weightFailed boolean

        Comparison of gross weight with expected weight(the sum of net weight of items * 1.2 + 1)

    • connectorResponses array[object]
      • input string

        The input of a NomadOperation, usually it's JSON format.

      • mappingName string

        The name of mapping class.

      • api array[string]
      • Raw data of current HTTP request to the third party server, easy for debug.

      • code integer(int32)
      • response string
      • responseEn string
      • platform string
      • requestCount integer(int32)

        The number of requests against the third party in one Nomad request.

      • responseTime integer(int32)

        The response time of current NomadOperation request, including sub-NomadOperation. The time unit is millisecond.

    • responseTime integer(int32)

      The response time of current NomadOperation request, including sub-NomadOperation. The time unit is millisecond.

POST /ship/{carrier}/confirm
curl \
 -X POST https://nomad.samarkand-global.cn/pilot/ship/{carrier}/confirm \
 -H "x-ca-key: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"dimension":{"weight":42.0,"height":42.0,"length":42.0,"width":42.0},"shipFrom":{"firstName":"John","lastName":"string","address1":"string","address2":"string","county":"string","city":"string","state":"string","country":"string","zip":"string","tin":"string","phone":"string","countryCode":142,"idCard":"string","email":"string","company":"string","ecommerceWebsiteUserId":"string"},"shipTo":{"firstName":"John","lastName":"string","address1":"string","address2":"string","county":"string","cit...}'
Request example
{
  "dimension": {
    "weight": 42.0,
    "height": 42.0,
    "length": 42.0,
    "width": 42.0
  },
  "shipFrom": {
    "firstName": "John",
    "lastName": "string",
    "address1": "string",
    "address2": "string",
    "county": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "zip": "string",
    "tin": "string",
    "phone": "string",
    "countryCode": 142,
    "idCard": "string",
    "email": "string",
    "company": "string",
    "ecommerceWebsiteUserId": "string"
  },
  "shipTo": {
    "firstName": "John",
    "lastName": "string",
    "address1": "string",
    "address2": "string",
    "county": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "zip": "string",
    "tin": "string",
    "phone": "string",
    "countryCode": 142,
    "idCard": "string",
    "email": "string",
    "company": "string",
    "ecommerceWebsiteUserId": "string"
  },
  "bill": {
    "firstName": "John",
    "lastName": "string",
    "address1": "string",
    "address2": "string",
    "county": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "zip": "string",
    "tin": "string",
    "phone": "string",
    "countryCode": 142,
    "idCard": "string",
    "email": "string",
    "company": "string",
    "ecommerceWebsiteUserId": "string"
  },
  "orderRef": "SO224571",
  "sellerOrderRef": "E202010152223470377011119610GZ",
  "trackingReference": "SF1032566311525",
  "orderTime": "string",
  "grossWeight": 1.53,
  "netWeight": 1.53,
  "totalPrice": 532.8,
  "currency": "RMB",
  "massUnit": "Kilogram",
  "lengthUnit": "Centimetre",
  "domesticDeliveryCompany": "SF",
  "createdAt": "2019-07-12T13:13:52.004637+01:00",
  "updatedAt": "2019-07-12T13:13:52.004637+01:00",
  "payMethod": "EASIPAY",
  "payMerchantName": "Paypal",
  "payAmount": 611.08,
  "payId": "2014030120394812",
  "paidAt": "2019-07-12T13:13:52.004637+01:00",
  "productsTotalTax": 53.28,
  "shippingCost": 25,
  "nonCashDeductionAmount": 0,
  "customerNote": "This package is very important.",
  "cancelReason": "The customers updated the address.",
  "warehouseCode": "718595286704",
  "customerIdRef": "string",
  "insuranceFee": 2.5,
  "expressType": "BC",
  "paymentPayId": "191028195204000214",
  "platformName": "youzan",
  "checkPoint": "string",
  "items": [
    {
      "name": "string",
      "nameCn": "测试",
      "barcode": "string",
      "skuNumber": "SMK123",
      "quantity": 7,
      "price": 21.3,
      "brand": "string",
      "quantityUom": "50G",
      "hsCode": "string",
      "countryOfOrigin": "string",
      "goldjet": {
        "goodsPtcode": "string"
      },
      "grossWeight": 42.0,
      "netWeight": 42.0,
      "customsUnitCode": "142, 007, 瓶, ...",
      "customsUnitCodePackage": "142, 011, 140",
      "customsUnitCodeWeight": "035(means 千克, kilogram)",
      "customsFilingId": "string",
      "spec": "25mm",
      "model": "iPhone XR",
      "ingredients": "发酵乳杆菌Lc40(CECT5716),麦芽糊精,蔗糖,抗坏血酸钠",
      "customsUnitCodeCn": "瓶",
      "countryOfOriginIso": "RU"
    }
  ]
}
Response example (200)
{
  "code": 42,
  "message": "string",
  "data": {
    "shipmentId": "string",
    "scanFormId": "string",
    "scanFormUrl": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "string",
    "deliveryNote": "string",
    "deliverySlipUrl": "string",
    "trackingUrl": "string",
    "checkPoints": [
      "@accept_time 2020-05-01 04:59:38; @accept_address 伦敦; @remark 寄方准备快件中,当前地点: 【GB London Delivery Centre (英國倫敦收派中心)】; @opcode 647; @zoneGmt 1",
      "...",
      "@accept_time 2020-05-13 09:10:49; @accept_address 江门市;  @remark 在官网'运单资料&签收图',可查看签收人信息; @opcode 8000; @stayWhyCode  1; @zoneGmt 8"
    ],
    "weightFailed": false
  },
  "connectorResponses": [
    {
      "input": "{\"product_id\": 12121}",
      "mappingName": "GetProductOp",
      "api": [
        "string"
      ],
      "httpRequestRawData": "-",
      "code": 42,
      "response": "string",
      "responseEn": "string",
      "platform": "youzan",
      "requestCount": 1,
      "responseTime": 1000
    }
  ],
  "responseTime": 1000
}
Response example (500)
{
  "code": 42,
  "message": "string",
  "data": {
    "shipmentId": "string",
    "scanFormId": "string",
    "scanFormUrl": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "string",
    "deliveryNote": "string",
    "deliverySlipUrl": "string",
    "trackingUrl": "string",
    "checkPoints": [
      "@accept_time 2020-05-01 04:59:38; @accept_address 伦敦; @remark 寄方准备快件中,当前地点: 【GB London Delivery Centre (英國倫敦收派中心)】; @opcode 647; @zoneGmt 1",
      "...",
      "@accept_time 2020-05-13 09:10:49; @accept_address 江门市;  @remark 在官网'运单资料&签收图',可查看签收人信息; @opcode 8000; @stayWhyCode  1; @zoneGmt 8"
    ],
    "weightFailed": false
  },
  "connectorResponses": [
    {
      "input": "{\"product_id\": 12121}",
      "mappingName": "GetProductOp",
      "api": [
        "string"
      ],
      "httpRequestRawData": "-",
      "code": 42,
      "response": "string",
      "responseEn": "string",
      "platform": "youzan",
      "requestCount": 1,
      "responseTime": 1000
    }
  ],
  "responseTime": 1000
}

QueryShip

Query the status of an waybill.

Path parameters
  • carrier Required / string

    String name of carrier

  • seller_order_ref Required / string

    Order reference number from retailers, e-commerce platform, e.g. Youzan, Little Red

Responses
  • 200 object

    Success

    • code integer(int32)
    • message string
    • data object
      • shipmentId string
      • scanFormId string
      • scanFormUrl string
      • waybillId string
      • orderSn string Deprecated

        Deprecated. Replaced by 'orderRef'.

      • orderRef string

        Order reference number. Default is from Odoo.

      • Order reference number. Also could be from retailers, e.g. Youzan.

      • the domestic delivery vender for sinotrans

      • The delivery status of one package, 9 possible values are below statues will be loaded into PilotDeliveryStatus().statuses. If status begin with 'DOMESTIC', it means order has been declared in customs. @PREPARE_ORDER @SORT_ORDER @PACK_ORDER @ORDER_OUTBOUND @CUSTOM_CLEAR @CUSTOM_CLEAR_COMPLETE @FLIGHT_DEPARTURE @FLIGHT_ARRIVE
        @DOMESTIC_DELIVERY @DOMESTIC_IN_TRANSIT @DOMESTIC_SIGNING @DOMESTIC_SUCCESS @DOMESTIC_RETURNED @DOMESTIC_FAILURE

      • deliveryNote string

        A note marked by the carrier, could be changed at any time.

      • The URL of delivery slip.

      • trackingUrl string

        The URL of waybill tracking.

      • checkPoints array[string]

        The details of express checkpoints.

      • weightFailed boolean

        Comparison of gross weight with expected weight(the sum of net weight of items * 1.2 + 1)

    • connectorResponses array[object]
      • input string

        The input of a NomadOperation, usually it's JSON format.

      • mappingName string

        The name of mapping class.

      • api array[string]
      • Raw data of current HTTP request to the third party server, easy for debug.

      • code integer(int32)
      • response string
      • responseEn string
      • platform string
      • requestCount integer(int32)

        The number of requests against the third party in one Nomad request.

      • responseTime integer(int32)

        The response time of current NomadOperation request, including sub-NomadOperation. The time unit is millisecond.

    • responseTime integer(int32)

      The response time of current NomadOperation request, including sub-NomadOperation. The time unit is millisecond.

  • 500 object

    Failed