Nomad Pilot
1.52.0

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.52.0 of the API. Last update on Feb 2, 2023.

Base URL

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

Authentication

Ca key (http_api_key)

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

ship

Create a new waybill for shipping via the specified carrier

Ship

PUT /ship/{carrier}

Update waybill details for specified carrier.

Path parameters

carrier string Required

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

Body Required

Package to ship

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 string
- zip string
  
  Postal Code / Zip, please set to . if not known
- tin string
  
  TIN; The Chinese ID number of current person.
- phone string
- 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
- ecommerceWebsiteUserId 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 string
- zip string
  
  Postal Code / Zip, please set to . if not known
- tin string
  
  TIN; The Chinese ID number of current person.
- phone string
- 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
- ecommerceWebsiteUserId string
  
  The user ID of that e-commerce website.
bill object
- firstName string
- lastName string
- address1 string
- address2 string
- county string
  
  The county of current city. 县/区, e.g. 西湖区
- city string
- state string
- country string
- zip string
  
  Postal Code / Zip, please set to . if not known
- tin string
  
  TIN; The Chinese ID number of current person.
- phone string
- 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
- ecommerceWebsiteUserId string
  
  The user ID of that e-commerce website.
orderRef string

Order reference number in ERP application
sellerOrderRef string

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

Order reference number from merchant, e.g. WConceput
trackingReference string Required

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.
domesticDeliveryCompany string

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
payMerchantName 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

Express route check point, turn on it by input "enable", default is disabled
service string

Services provided by logistics companies, such as next_day for Next Day Delivery, sign for Signed Delivery, international for International Delivery and so on.
expressCompany string

Logistic companies, e.g. SF, FEDEX.
items array[object]

Contents of package
- name string
- nameCn string
  
  The Chinese name of current product item
- barcode string
- skuNumber string
- quantity integer(int32)
- price number
  
  The price of this product, not including any discount and tax.
- tax number
  
  The tax of this product.
- discount number
  
  The discount of this product.
- brand string
- quantityUom string
- hsCode string
- countryOfOrigin string
- goldjet object Deprecated
  goodsPtcode string
- grossWeight number
  
  Use Kilogram as the basic unit of mass.
- netWeight number
  
  Use Kilogram as the basic unit of mass.
- customsUnitCode string
  
  aka customsUnitCodeSKU. The quantity unit code of current sku for customs purpose. Both Chinese or number are ok.
- customsUnitCodePackage string
  
  The quantity unit code customs purpose. Declaration Unit, 申报单位.
- customsUnitCodeWeight string
  
  The weight unit code for customs purpose.
  
  Default value is 035.
- customsFilingId string
  
  The returned filing id of current SKU from customs
- spec string
  
  The spec of current product.
- model string
  
  The model of current product.
- ingredients string
  
  The ingredients of current product.
- customsUnitCodeCn string
  
  Declaration Unit with Chinese format, 申报单位.
- countryOfOriginIso string
  
  Two letters country code
- declarationElements string
  
  Customs declaration elements, separate each item with a comma.
status string

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

nomad express carrier name
deliverySlipUrl string

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
  
  trackingReference string
  
  waybillId string
  
  Logistics company waybill no.
  
  orderSn string Deprecated
  
  Deprecated. Replaced by 'orderRef'.
  
  orderRef string
  
  Order reference number. Default is from Odoo.
  
  sellerOrderRef string
  
  Order reference number. Also could be from retailers, e.g. Youzan.
  
  domesticDeliveryCompany string
  
  the domestic delivery vender for sinotrans
  
  deliveryStatus string
  
  The delivery status of one package
  
  Values are PREPARE_ORDER, SORT_ORDER, PACK_ORDER, ORDER_OUTBOUND, DELIVERY, FLIGHT_DEPARTURE, FLIGHT_ARRIVE, CUSTOM_CLEAR, CUSTOM_CLEAR_COMPLETE, CUSTOM_CLEAR_FAILURE, DOMESTIC_DELIVERY, DOMESTIC_IN_TRANSIT, DOMESTIC_SIGNING, DOMESTIC_SUCCESS, DOMESTIC_RETURNED, or DOMESTIC_FAILURE.
  
  deliveryNote string
  
  A note marked by the carrier, could be changed at any time.
  
  deliverySlipUrl string
  
  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)
  
  Default value is false.
  
  errorCode string
  
  Error code, returning if waybill creation failed. Available codes which will be progressively clarified: PRODUCT_NOT_EXIST, ORDER_NOT_EXIST, AREA_RESTRICTED, PRODUCT_ERROR, CUSTOMER_ERROR, ADDRESS_ERROR, LOGISTIC_ERROR, OTHERS
  
  errorMessage string
  
  Error message, which will be progressively clarified
- 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]
  
  httpRequestRawData 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
  
  trackingReference string
  
  waybillId string
  
  Logistics company waybill no.
  
  orderSn string Deprecated
  
  Deprecated. Replaced by 'orderRef'.
  
  orderRef string
  
  Order reference number. Default is from Odoo.
  
  sellerOrderRef string
  
  Order reference number. Also could be from retailers, e.g. Youzan.
  
  domesticDeliveryCompany string
  
  the domestic delivery vender for sinotrans
  
  deliveryStatus string
  
  The delivery status of one package
  
  Values are PREPARE_ORDER, SORT_ORDER, PACK_ORDER, ORDER_OUTBOUND, DELIVERY, FLIGHT_DEPARTURE, FLIGHT_ARRIVE, CUSTOM_CLEAR, CUSTOM_CLEAR_COMPLETE, CUSTOM_CLEAR_FAILURE, DOMESTIC_DELIVERY, DOMESTIC_IN_TRANSIT, DOMESTIC_SIGNING, DOMESTIC_SUCCESS, DOMESTIC_RETURNED, or DOMESTIC_FAILURE.
  
  deliveryNote string
  
  A note marked by the carrier, could be changed at any time.
  
  deliverySlipUrl string
  
  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)
  
  Default value is false.
  
  errorCode string
  
  Error code, returning if waybill creation failed. Available codes which will be progressively clarified: PRODUCT_NOT_EXIST, ORDER_NOT_EXIST, AREA_RESTRICTED, PRODUCT_ERROR, CUSTOMER_ERROR, ADDRESS_ERROR, LOGISTIC_ERROR, OTHERS
  
  errorMessage string
  
  Error message, which will be progressively clarified
- 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]
  
  httpRequestRawData 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","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","merchantOrderRef":"WU202127533","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","service":"string","expressCompany":"string","items":[{"name":"string","nameCn":"测试","barcode":"string","skuNumber":"SMK123","quantity":7,"price":21.3,"tax":2,"discount":1,"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","declarationElements":"string"}],"status":"string","carrier":"samarkand.sfexpress.test","deliverySlipUrl":"string","createdDate":"string","packedDate":"string","processedDate":"string","shippedDate":"string","cancelDate":"string","customsNote":"string"}'

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",
  "merchantOrderRef": "WU202127533",
  "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",
  "service": "string",
  "expressCompany": "string",
  "items": [
    {
      "name": "string",
      "nameCn": "测试",
      "barcode": "string",
      "skuNumber": "SMK123",
      "quantity": 7,
      "price": 21.3,
      "tax": 2,
      "discount": 1,
      "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",
      "declarationElements": "string"
    }
  ],
  "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",
    "trackingReference": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "DELIVERY",
    "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,
    "errorCode": "string",
    "errorMessage": "string"
  },
  "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",
    "trackingReference": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "DELIVERY",
    "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,
    "errorCode": "string",
    "errorMessage": "string"
  },
  "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

POST /ship/{carrier}

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

Path parameters

carrier string Required

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

Body Required

Package to ship

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 string Required
- zip string Required
  
  Postal Code / Zip, please set to . if not known
- tin string
  
  TIN; The Chinese ID number of current person.
- phone string Required
  
  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
- ecommerceWebsiteUserId 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 string Required
- zip string Required
  
  Postal Code / Zip, please set to . if not known
- tin string
  
  TIN; The Chinese ID number of current person.
- phone string Required
  
  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
- ecommerceWebsiteUserId string
  
  The user ID of that e-commerce website.
bill object
- firstName string
- lastName string
- address1 string
- address2 string
- county string
  
  The county of current city. 县/区, e.g. 西湖区
- city string
- state string
- country string
- zip string
  
  Postal Code / Zip, please set to . if not known
- tin string
  
  TIN; The Chinese ID number of current person.
- phone string
- 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
- ecommerceWebsiteUserId string
  
  The user ID of that e-commerce website.
orderRef string

Order reference number in ERP application
sellerOrderRef string Required

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

Order reference number from merchant, e.g. WConceput
trackingReference 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 Required

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

Default value is RMB.
massUnit string Required

weight Unit of measurement

Default value is Kilogram.
lengthUnit string Required

length Unit of measurement

Default value is Centimetre.
domesticDeliveryCompany string

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
payMerchantName 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 Required

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

Express route check point, turn on it by input "enable", default is disabled
service string

Services provided by logistics companies, such as next_day for Next Day Delivery, sign for Signed Delivery, international for International Delivery and so on.
expressCompany string

Logistic companies, e.g. SF, FEDEX.
items array[object]

Contents of package
- name string
- nameCn string
  
  The Chinese name of current product item
- barcode string
- skuNumber string
- quantity integer(int32)
- price number
  
  The price of this product, not including any discount and tax.
- tax number
  
  The tax of this product.
- discount number
  
  The discount of this product.
- brand string
- quantityUom string
- hsCode string
- countryOfOrigin string
- goldjet object Deprecated
  goodsPtcode string
- grossWeight number
  
  Use Kilogram as the basic unit of mass.
- netWeight number
  
  Use Kilogram as the basic unit of mass.
- customsUnitCode string
  
  aka customsUnitCodeSKU. The quantity unit code of current sku for customs purpose. Both Chinese or number are ok.
- customsUnitCodePackage string
  
  The quantity unit code customs purpose. Declaration Unit, 申报单位.
- customsUnitCodeWeight string
  
  The weight unit code for customs purpose.
  
  Default value is 035.
- customsFilingId string
  
  The returned filing id of current SKU from customs
- spec string
  
  The spec of current product.
- model string
  
  The model of current product.
- ingredients string
  
  The ingredients of current product.
- customsUnitCodeCn string
  
  Declaration Unit with Chinese format, 申报单位.
- countryOfOriginIso string
  
  Two letters country code
- declarationElements string
  
  Customs declaration elements, separate each item with a comma.

Responses

• 200 object

Waybill creation successed
- code integer(int32)
- message string
- data object
  shipmentId string
  
  scanFormId string
  
  scanFormUrl string
  
  trackingReference string
  
  waybillId string
  
  Logistics company waybill no.
  
  orderSn string Deprecated
  
  Deprecated. Replaced by 'orderRef'.
  
  orderRef string
  
  Order reference number. Default is from Odoo.
  
  sellerOrderRef string
  
  Order reference number. Also could be from retailers, e.g. Youzan.
  
  domesticDeliveryCompany string
  
  the domestic delivery vender for sinotrans
  
  deliveryStatus string
  
  The delivery status of one package
  
  Values are PREPARE_ORDER, SORT_ORDER, PACK_ORDER, ORDER_OUTBOUND, DELIVERY, FLIGHT_DEPARTURE, FLIGHT_ARRIVE, CUSTOM_CLEAR, CUSTOM_CLEAR_COMPLETE, CUSTOM_CLEAR_FAILURE, DOMESTIC_DELIVERY, DOMESTIC_IN_TRANSIT, DOMESTIC_SIGNING, DOMESTIC_SUCCESS, DOMESTIC_RETURNED, or DOMESTIC_FAILURE.
  
  deliveryNote string
  
  A note marked by the carrier, could be changed at any time.
  
  deliverySlipUrl string
  
  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)
  
  Default value is false.
  
  errorCode string
  
  Error code, returning if waybill creation failed. Available codes which will be progressively clarified: PRODUCT_NOT_EXIST, ORDER_NOT_EXIST, AREA_RESTRICTED, PRODUCT_ERROR, CUSTOMER_ERROR, ADDRESS_ERROR, LOGISTIC_ERROR, OTHERS
  
  errorMessage string
  
  Error message, which will be progressively clarified
- 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]
  
  httpRequestRawData 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
  
  trackingReference string
  
  waybillId string
  
  Logistics company waybill no.
  
  orderSn string Deprecated
  
  Deprecated. Replaced by 'orderRef'.
  
  orderRef string
  
  Order reference number. Default is from Odoo.
  
  sellerOrderRef string
  
  Order reference number. Also could be from retailers, e.g. Youzan.
  
  domesticDeliveryCompany string
  
  the domestic delivery vender for sinotrans
  
  deliveryStatus string
  
  The delivery status of one package
  
  Values are PREPARE_ORDER, SORT_ORDER, PACK_ORDER, ORDER_OUTBOUND, DELIVERY, FLIGHT_DEPARTURE, FLIGHT_ARRIVE, CUSTOM_CLEAR, CUSTOM_CLEAR_COMPLETE, CUSTOM_CLEAR_FAILURE, DOMESTIC_DELIVERY, DOMESTIC_IN_TRANSIT, DOMESTIC_SIGNING, DOMESTIC_SUCCESS, DOMESTIC_RETURNED, or DOMESTIC_FAILURE.
  
  deliveryNote string
  
  A note marked by the carrier, could be changed at any time.
  
  deliverySlipUrl string
  
  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)
  
  Default value is false.
  
  errorCode string
  
  Error code, returning if waybill creation failed. Available codes which will be progressively clarified: PRODUCT_NOT_EXIST, ORDER_NOT_EXIST, AREA_RESTRICTED, PRODUCT_ERROR, CUSTOMER_ERROR, ADDRESS_ERROR, LOGISTIC_ERROR, OTHERS
  
  errorMessage string
  
  Error message, which will be progressively clarified
- 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]
  
  httpRequestRawData 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","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","merchantOrderRef":"WU202127533","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","service":"string","expressCompany":"string","items":[{"name":"string","nameCn":"测试","barcode":"string","skuNumber":"SMK123","quantity":7,"price":21.3,"tax":2,"discount":1,"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","declarationElements":"string"}]}'

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",
  "merchantOrderRef": "WU202127533",
  "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",
  "service": "string",
  "expressCompany": "string",
  "items": [
    {
      "name": "string",
      "nameCn": "测试",
      "barcode": "string",
      "skuNumber": "SMK123",
      "quantity": 7,
      "price": 21.3,
      "tax": 2,
      "discount": 1,
      "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",
      "declarationElements": "string"
    }
  ]
}

Response example (200)

{
  "code": 42,
  "message": "string",
  "data": {
    "shipmentId": "string",
    "scanFormId": "string",
    "scanFormUrl": "string",
    "trackingReference": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "DELIVERY",
    "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,
    "errorCode": "string",
    "errorMessage": "string"
  },
  "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",
    "trackingReference": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "DELIVERY",
    "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,
    "errorCode": "string",
    "errorMessage": "string"
  },
  "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

GET /ship/{carrier}/order/{seller_order_ref}

Query the status of an waybill.

Path parameters

carrier string Required

String name of carrier
seller_order_ref string Required

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
  
  trackingReference string
  
  waybillId string
  
  Logistics company waybill no.
  
  orderSn string Deprecated
  
  Deprecated. Replaced by 'orderRef'.
  
  orderRef string
  
  Order reference number. Default is from Odoo.
  
  sellerOrderRef string
  
  Order reference number. Also could be from retailers, e.g. Youzan.
  
  domesticDeliveryCompany string
  
  the domestic delivery vender for sinotrans
  
  deliveryStatus string
  
  The delivery status of one package
  
  Values are PREPARE_ORDER, SORT_ORDER, PACK_ORDER, ORDER_OUTBOUND, DELIVERY, FLIGHT_DEPARTURE, FLIGHT_ARRIVE, CUSTOM_CLEAR, CUSTOM_CLEAR_COMPLETE, CUSTOM_CLEAR_FAILURE, DOMESTIC_DELIVERY, DOMESTIC_IN_TRANSIT, DOMESTIC_SIGNING, DOMESTIC_SUCCESS, DOMESTIC_RETURNED, or DOMESTIC_FAILURE.
  
  deliveryNote string
  
  A note marked by the carrier, could be changed at any time.
  
  deliverySlipUrl string
  
  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)
  
  Default value is false.
  
  errorCode string
  
  Error code, returning if waybill creation failed. Available codes which will be progressively clarified: PRODUCT_NOT_EXIST, ORDER_NOT_EXIST, AREA_RESTRICTED, PRODUCT_ERROR, CUSTOMER_ERROR, ADDRESS_ERROR, LOGISTIC_ERROR, OTHERS
  
  errorMessage string
  
  Error message, which will be progressively clarified
- 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]
  
  httpRequestRawData 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
- code integer(int32)
- message string
- data object
  shipmentId string
  
  scanFormId string
  
  scanFormUrl string
  
  trackingReference string
  
  waybillId string
  
  Logistics company waybill no.
  
  orderSn string Deprecated
  
  Deprecated. Replaced by 'orderRef'.
  
  orderRef string
  
  Order reference number. Default is from Odoo.
  
  sellerOrderRef string
  
  Order reference number. Also could be from retailers, e.g. Youzan.
  
  domesticDeliveryCompany string
  
  the domestic delivery vender for sinotrans
  
  deliveryStatus string
  
  The delivery status of one package
  
  Values are PREPARE_ORDER, SORT_ORDER, PACK_ORDER, ORDER_OUTBOUND, DELIVERY, FLIGHT_DEPARTURE, FLIGHT_ARRIVE, CUSTOM_CLEAR, CUSTOM_CLEAR_COMPLETE, CUSTOM_CLEAR_FAILURE, DOMESTIC_DELIVERY, DOMESTIC_IN_TRANSIT, DOMESTIC_SIGNING, DOMESTIC_SUCCESS, DOMESTIC_RETURNED, or DOMESTIC_FAILURE.
  
  deliveryNote string
  
  A note marked by the carrier, could be changed at any time.
  
  deliverySlipUrl string
  
  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)
  
  Default value is false.
  
  errorCode string
  
  Error code, returning if waybill creation failed. Available codes which will be progressively clarified: PRODUCT_NOT_EXIST, ORDER_NOT_EXIST, AREA_RESTRICTED, PRODUCT_ERROR, CUSTOMER_ERROR, ADDRESS_ERROR, LOGISTIC_ERROR, OTHERS
  
  errorMessage string
  
  Error message, which will be progressively clarified
- 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]
  
  httpRequestRawData 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.

GET /ship/{carrier}/order/{seller_order_ref}

curl \
 -X GET https://nomad.samarkand-global.cn/pilot/ship/{carrier}/order/{seller_order_ref} \
 -H "x-ca-key: $API_KEY"

Response example (200)

{
  "code": 42,
  "message": "string",
  "data": {
    "shipmentId": "string",
    "scanFormId": "string",
    "scanFormUrl": "string",
    "trackingReference": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "DELIVERY",
    "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,
    "errorCode": "string",
    "errorMessage": "string"
  },
  "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",
    "trackingReference": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "DELIVERY",
    "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,
    "errorCode": "string",
    "errorMessage": "string"
  },
  "connectorResponses": [
    {
      "input": "{\"product_id\": 12121}",
      "mappingName": "GetProductOp",
      "api": [
        "string"
      ],
      "httpRequestRawData": "-",
      "code": 42,
      "response": "string",
      "responseEn": "string",
      "platform": "youzan",
      "requestCount": 1,
      "responseTime": 1000
    }
  ],
  "responseTime": 1000
}

CancelShip

DELETE /ship/{carrier}/order/{seller_order_ref}

Attempts to cancel a created waybill, success will depend on carrier support.

Path parameters

carrier string Required

Carrier name to ship, e.g. samarkand.sfexpress.test
seller_order_ref string Required

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
  
  trackingReference string
  
  waybillId string
  
  Logistics company waybill no.
  
  orderSn string Deprecated
  
  Deprecated. Replaced by 'orderRef'.
  
  orderRef string
  
  Order reference number. Default is from Odoo.
  
  sellerOrderRef string
  
  Order reference number. Also could be from retailers, e.g. Youzan.
  
  domesticDeliveryCompany string
  
  the domestic delivery vender for sinotrans
  
  deliveryStatus string
  
  The delivery status of one package
  
  Values are PREPARE_ORDER, SORT_ORDER, PACK_ORDER, ORDER_OUTBOUND, DELIVERY, FLIGHT_DEPARTURE, FLIGHT_ARRIVE, CUSTOM_CLEAR, CUSTOM_CLEAR_COMPLETE, CUSTOM_CLEAR_FAILURE, DOMESTIC_DELIVERY, DOMESTIC_IN_TRANSIT, DOMESTIC_SIGNING, DOMESTIC_SUCCESS, DOMESTIC_RETURNED, or DOMESTIC_FAILURE.
  
  deliveryNote string
  
  A note marked by the carrier, could be changed at any time.
  
  deliverySlipUrl string
  
  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)
  
  Default value is false.
  
  errorCode string
  
  Error code, returning if waybill creation failed. Available codes which will be progressively clarified: PRODUCT_NOT_EXIST, ORDER_NOT_EXIST, AREA_RESTRICTED, PRODUCT_ERROR, CUSTOMER_ERROR, ADDRESS_ERROR, LOGISTIC_ERROR, OTHERS
  
  errorMessage string
  
  Error message, which will be progressively clarified
- 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]
  
  httpRequestRawData 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
- code integer(int32)
- message string
- data object
  shipmentId string
  
  scanFormId string
  
  scanFormUrl string
  
  trackingReference string
  
  waybillId string
  
  Logistics company waybill no.
  
  orderSn string Deprecated
  
  Deprecated. Replaced by 'orderRef'.
  
  orderRef string
  
  Order reference number. Default is from Odoo.
  
  sellerOrderRef string
  
  Order reference number. Also could be from retailers, e.g. Youzan.
  
  domesticDeliveryCompany string
  
  the domestic delivery vender for sinotrans
  
  deliveryStatus string
  
  The delivery status of one package
  
  Values are PREPARE_ORDER, SORT_ORDER, PACK_ORDER, ORDER_OUTBOUND, DELIVERY, FLIGHT_DEPARTURE, FLIGHT_ARRIVE, CUSTOM_CLEAR, CUSTOM_CLEAR_COMPLETE, CUSTOM_CLEAR_FAILURE, DOMESTIC_DELIVERY, DOMESTIC_IN_TRANSIT, DOMESTIC_SIGNING, DOMESTIC_SUCCESS, DOMESTIC_RETURNED, or DOMESTIC_FAILURE.
  
  deliveryNote string
  
  A note marked by the carrier, could be changed at any time.
  
  deliverySlipUrl string
  
  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)
  
  Default value is false.
  
  errorCode string
  
  Error code, returning if waybill creation failed. Available codes which will be progressively clarified: PRODUCT_NOT_EXIST, ORDER_NOT_EXIST, AREA_RESTRICTED, PRODUCT_ERROR, CUSTOMER_ERROR, ADDRESS_ERROR, LOGISTIC_ERROR, OTHERS
  
  errorMessage string
  
  Error message, which will be progressively clarified
- 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]
  
  httpRequestRawData 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.

DELETE /ship/{carrier}/order/{seller_order_ref}

curl \
 -X DELETE https://nomad.samarkand-global.cn/pilot/ship/{carrier}/order/{seller_order_ref} \
 -H "x-ca-key: $API_KEY"

Response example (200)

{
  "code": 42,
  "message": "string",
  "data": {
    "shipmentId": "string",
    "scanFormId": "string",
    "scanFormUrl": "string",
    "trackingReference": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "DELIVERY",
    "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,
    "errorCode": "string",
    "errorMessage": "string"
  },
  "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",
    "trackingReference": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "DELIVERY",
    "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,
    "errorCode": "string",
    "errorMessage": "string"
  },
  "connectorResponses": [
    {
      "input": "{\"product_id\": 12121}",
      "mappingName": "GetProductOp",
      "api": [
        "string"
      ],
      "httpRequestRawData": "-",
      "code": 42,
      "response": "string",
      "responseEn": "string",
      "platform": "youzan",
      "requestCount": 1,
      "responseTime": 1000
    }
  ],
  "responseTime": 1000
}

quick_ship

Create a new waybill for shipping with minimum product information

QuickShip

POST /quick-ship/{carrier}

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

Path parameters

carrier string Required

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

Body Required

Package to quick ship

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 string
- zip string
  
  Postal Code / Zip, please set to . if not known
- tin string
  
  TIN; The Chinese ID number of current person.
- phone string
- 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
- ecommerceWebsiteUserId 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 string
- zip string
  
  Postal Code / Zip, please set to . if not known
- tin string
  
  TIN; The Chinese ID number of current person.
- phone string
- 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
- ecommerceWebsiteUserId string
  
  The user ID of that e-commerce website.
bill object
- firstName string
- lastName string
- address1 string
- address2 string
- county string
  
  The county of current city. 县/区, e.g. 西湖区
- city string
- state string
- country string
- zip string
  
  Postal Code / Zip, please set to . if not known
- tin string
  
  TIN; The Chinese ID number of current person.
- phone string
- 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
- ecommerceWebsiteUserId string
  
  The user ID of that e-commerce website.
orderRef string

Order reference number in ERP application
sellerOrderRef string

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

Order reference number from merchant, e.g. WConceput
trackingReference 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.
domesticDeliveryCompany string

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
payMerchantName 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

Express route check point, turn on it by input "enable", default is disabled
service string

Services provided by logistics companies, such as next_day for Next Day Delivery, sign for Signed Delivery, international for International Delivery and so on.
expressCompany string

Logistic companies, e.g. SF, FEDEX.
items array[object]
- skuNumber string Required
  
  The sku Number of this product
- barcode string
  
  The barcode of this product
- quantity integer(int32) Required
  
  The quantity of this product in current order
- price number Required
  
  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
  
  trackingReference string
  
  waybillId string
  
  Logistics company waybill no.
  
  orderSn string Deprecated
  
  Deprecated. Replaced by 'orderRef'.
  
  orderRef string
  
  Order reference number. Default is from Odoo.
  
  sellerOrderRef string
  
  Order reference number. Also could be from retailers, e.g. Youzan.
  
  domesticDeliveryCompany string
  
  the domestic delivery vender for sinotrans
  
  deliveryStatus string
  
  The delivery status of one package
  
  Values are PREPARE_ORDER, SORT_ORDER, PACK_ORDER, ORDER_OUTBOUND, DELIVERY, FLIGHT_DEPARTURE, FLIGHT_ARRIVE, CUSTOM_CLEAR, CUSTOM_CLEAR_COMPLETE, CUSTOM_CLEAR_FAILURE, DOMESTIC_DELIVERY, DOMESTIC_IN_TRANSIT, DOMESTIC_SIGNING, DOMESTIC_SUCCESS, DOMESTIC_RETURNED, or DOMESTIC_FAILURE.
  
  deliveryNote string
  
  A note marked by the carrier, could be changed at any time.
  
  deliverySlipUrl string
  
  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)
  
  Default value is false.
  
  errorCode string
  
  Error code, returning if waybill creation failed. Available codes which will be progressively clarified: PRODUCT_NOT_EXIST, ORDER_NOT_EXIST, AREA_RESTRICTED, PRODUCT_ERROR, CUSTOMER_ERROR, ADDRESS_ERROR, LOGISTIC_ERROR, OTHERS
  
  errorMessage string
  
  Error message, which will be progressively clarified
- 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]
  
  httpRequestRawData 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
  
  trackingReference string
  
  waybillId string
  
  Logistics company waybill no.
  
  orderSn string Deprecated
  
  Deprecated. Replaced by 'orderRef'.
  
  orderRef string
  
  Order reference number. Default is from Odoo.
  
  sellerOrderRef string
  
  Order reference number. Also could be from retailers, e.g. Youzan.
  
  domesticDeliveryCompany string
  
  the domestic delivery vender for sinotrans
  
  deliveryStatus string
  
  The delivery status of one package
  
  Values are PREPARE_ORDER, SORT_ORDER, PACK_ORDER, ORDER_OUTBOUND, DELIVERY, FLIGHT_DEPARTURE, FLIGHT_ARRIVE, CUSTOM_CLEAR, CUSTOM_CLEAR_COMPLETE, CUSTOM_CLEAR_FAILURE, DOMESTIC_DELIVERY, DOMESTIC_IN_TRANSIT, DOMESTIC_SIGNING, DOMESTIC_SUCCESS, DOMESTIC_RETURNED, or DOMESTIC_FAILURE.
  
  deliveryNote string
  
  A note marked by the carrier, could be changed at any time.
  
  deliverySlipUrl string
  
  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)
  
  Default value is false.
  
  errorCode string
  
  Error code, returning if waybill creation failed. Available codes which will be progressively clarified: PRODUCT_NOT_EXIST, ORDER_NOT_EXIST, AREA_RESTRICTED, PRODUCT_ERROR, CUSTOMER_ERROR, ADDRESS_ERROR, LOGISTIC_ERROR, OTHERS
  
  errorMessage string
  
  Error message, which will be progressively clarified
- 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]
  
  httpRequestRawData 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","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","merchantOrderRef":"WU202127533","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","service":"string","expressCompany":"string","items":[{"skuNumber":"SMK123","barcode":5060280371714,"quantity":7,"price":21.3}]}'

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",
  "merchantOrderRef": "WU202127533",
  "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",
  "service": "string",
  "expressCompany": "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",
    "trackingReference": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "DELIVERY",
    "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,
    "errorCode": "string",
    "errorMessage": "string"
  },
  "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",
    "trackingReference": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "DELIVERY",
    "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,
    "errorCode": "string",
    "errorMessage": "string"
  },
  "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_confirm

Confirm a waybill for shipping via the specified carrier

ShipConfirm

POST /ship/{carrier}/confirm

Confirm waybill with specified carrier.

Path parameters

carrier string Required

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

Body Required

Package tracking reference from logistics company

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 string
- zip string
  
  Postal Code / Zip, please set to . if not known
- tin string
  
  TIN; The Chinese ID number of current person.
- phone string
- 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
- ecommerceWebsiteUserId 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 string
- zip string
  
  Postal Code / Zip, please set to . if not known
- tin string
  
  TIN; The Chinese ID number of current person.
- phone string
- 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
- ecommerceWebsiteUserId string
  
  The user ID of that e-commerce website.
bill object
- firstName string
- lastName string
- address1 string
- address2 string
- county string
  
  The county of current city. 县/区, e.g. 西湖区
- city string
- state string
- country string
- zip string
  
  Postal Code / Zip, please set to . if not known
- tin string
  
  TIN; The Chinese ID number of current person.
- phone string
- 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
- ecommerceWebsiteUserId string
  
  The user ID of that e-commerce website.
orderRef string

Order reference number in ERP application
sellerOrderRef string

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

Order reference number from merchant, e.g. WConceput
trackingReference string Required

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.
domesticDeliveryCompany string

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
payMerchantName 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

Express route check point, turn on it by input "enable", default is disabled
service string

Services provided by logistics companies, such as next_day for Next Day Delivery, sign for Signed Delivery, international for International Delivery and so on.
expressCompany string

Logistic companies, e.g. SF, FEDEX.
items array[object]

Contents of package
- name string
- nameCn string
  
  The Chinese name of current product item
- barcode string
- skuNumber string
- quantity integer(int32)
- price number
  
  The price of this product, not including any discount and tax.
- tax number
  
  The tax of this product.
- discount number
  
  The discount of this product.
- brand string
- quantityUom string
- hsCode string
- countryOfOrigin string
- goldjet object Deprecated
  goodsPtcode string
- grossWeight number
  
  Use Kilogram as the basic unit of mass.
- netWeight number
  
  Use Kilogram as the basic unit of mass.
- customsUnitCode string
  
  aka customsUnitCodeSKU. The quantity unit code of current sku for customs purpose. Both Chinese or number are ok.
- customsUnitCodePackage string
  
  The quantity unit code customs purpose. Declaration Unit, 申报单位.
- customsUnitCodeWeight string
  
  The weight unit code for customs purpose.
  
  Default value is 035.
- customsFilingId string
  
  The returned filing id of current SKU from customs
- spec string
  
  The spec of current product.
- model string
  
  The model of current product.
- ingredients string
  
  The ingredients of current product.
- customsUnitCodeCn string
  
  Declaration Unit with Chinese format, 申报单位.
- countryOfOriginIso string
  
  Two letters country code
- declarationElements string
  
  Customs declaration elements, separate each item with a comma.

Responses

• 200 object

Waybill confirm successed
- code integer(int32)
- message string
- data object
  shipmentId string
  
  scanFormId string
  
  scanFormUrl string
  
  trackingReference string
  
  waybillId string
  
  Logistics company waybill no.
  
  orderSn string Deprecated
  
  Deprecated. Replaced by 'orderRef'.
  
  orderRef string
  
  Order reference number. Default is from Odoo.
  
  sellerOrderRef string
  
  Order reference number. Also could be from retailers, e.g. Youzan.
  
  domesticDeliveryCompany string
  
  the domestic delivery vender for sinotrans
  
  deliveryStatus string
  
  The delivery status of one package
  
  Values are PREPARE_ORDER, SORT_ORDER, PACK_ORDER, ORDER_OUTBOUND, DELIVERY, FLIGHT_DEPARTURE, FLIGHT_ARRIVE, CUSTOM_CLEAR, CUSTOM_CLEAR_COMPLETE, CUSTOM_CLEAR_FAILURE, DOMESTIC_DELIVERY, DOMESTIC_IN_TRANSIT, DOMESTIC_SIGNING, DOMESTIC_SUCCESS, DOMESTIC_RETURNED, or DOMESTIC_FAILURE.
  
  deliveryNote string
  
  A note marked by the carrier, could be changed at any time.
  
  deliverySlipUrl string
  
  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)
  
  Default value is false.
  
  errorCode string
  
  Error code, returning if waybill creation failed. Available codes which will be progressively clarified: PRODUCT_NOT_EXIST, ORDER_NOT_EXIST, AREA_RESTRICTED, PRODUCT_ERROR, CUSTOMER_ERROR, ADDRESS_ERROR, LOGISTIC_ERROR, OTHERS
  
  errorMessage string
  
  Error message, which will be progressively clarified
- 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]
  
  httpRequestRawData 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
  
  trackingReference string
  
  waybillId string
  
  Logistics company waybill no.
  
  orderSn string Deprecated
  
  Deprecated. Replaced by 'orderRef'.
  
  orderRef string
  
  Order reference number. Default is from Odoo.
  
  sellerOrderRef string
  
  Order reference number. Also could be from retailers, e.g. Youzan.
  
  domesticDeliveryCompany string
  
  the domestic delivery vender for sinotrans
  
  deliveryStatus string
  
  The delivery status of one package
  
  Values are PREPARE_ORDER, SORT_ORDER, PACK_ORDER, ORDER_OUTBOUND, DELIVERY, FLIGHT_DEPARTURE, FLIGHT_ARRIVE, CUSTOM_CLEAR, CUSTOM_CLEAR_COMPLETE, CUSTOM_CLEAR_FAILURE, DOMESTIC_DELIVERY, DOMESTIC_IN_TRANSIT, DOMESTIC_SIGNING, DOMESTIC_SUCCESS, DOMESTIC_RETURNED, or DOMESTIC_FAILURE.
  
  deliveryNote string
  
  A note marked by the carrier, could be changed at any time.
  
  deliverySlipUrl string
  
  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)
  
  Default value is false.
  
  errorCode string
  
  Error code, returning if waybill creation failed. Available codes which will be progressively clarified: PRODUCT_NOT_EXIST, ORDER_NOT_EXIST, AREA_RESTRICTED, PRODUCT_ERROR, CUSTOMER_ERROR, ADDRESS_ERROR, LOGISTIC_ERROR, OTHERS
  
  errorMessage string
  
  Error message, which will be progressively clarified
- 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]
  
  httpRequestRawData 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","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","merchantOrderRef":"WU202127533","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","service":"string","expressCompany":"string","items":[{"name":"string","nameCn":"测试","barcode":"string","skuNumber":"SMK123","quantity":7,"price":21.3,"tax":2,"discount":1,"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","declarationElements":"string"}]}'

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",
  "merchantOrderRef": "WU202127533",
  "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",
  "service": "string",
  "expressCompany": "string",
  "items": [
    {
      "name": "string",
      "nameCn": "测试",
      "barcode": "string",
      "skuNumber": "SMK123",
      "quantity": 7,
      "price": 21.3,
      "tax": 2,
      "discount": 1,
      "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",
      "declarationElements": "string"
    }
  ]
}

Response example (200)

{
  "code": 42,
  "message": "string",
  "data": {
    "shipmentId": "string",
    "scanFormId": "string",
    "scanFormUrl": "string",
    "trackingReference": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "DELIVERY",
    "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,
    "errorCode": "string",
    "errorMessage": "string"
  },
  "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",
    "trackingReference": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "DELIVERY",
    "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,
    "errorCode": "string",
    "errorMessage": "string"
  },
  "connectorResponses": [
    {
      "input": "{\"product_id\": 12121}",
      "mappingName": "GetProductOp",
      "api": [
        "string"
      ],
      "httpRequestRawData": "-",
      "code": 42,
      "response": "string",
      "responseEn": "string",
      "platform": "youzan",
      "requestCount": 1,
      "responseTime": 1000
    }
  ],
  "responseTime": 1000
}

freight_forward

waybills in Samarkand Freight Forwarding

QueryFreightForward

GET /freight-forward/{carrier}

Query a specfic waybill in Freight Forwarding DB

Path parameters

carrier string Required

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

Query parameters

status string Required

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

Values are UNPROCESSED, PACKED, PROCESSED, SHIPPED, CANCEL, or ALL. Default value is UNPROCESSED.
page_no integer(int32) Required

Page number, between 1 and 1000

Minimum value is 1, maximum value is 1000. Default value is 1.
page_size integer(int32) Required

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

Values are 1, 10, 50, 100, or 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
- code integer(int32)
- message string
- data array
  
  An array of arbitrary types
- total integer(int32)
• 400

Invalid input
• 500 object

Failed
- code integer(int32)
- message string
- data array
  
  An array of arbitrary types
- total integer(int32)

GET /freight-forward/{carrier}

curl \
 -X GET https://nomad.samarkand-global.cn/pilot/freight-forward/{carrier}?status=UNPROCESSED&page_no=1&page_size=10 \
 -H "x-ca-key: $API_KEY"

Response example (200)

{
  "code": 42,
  "message": "string",
  "data": [],
  "total": 42
}

Response example (500)

{
  "code": 42,
  "message": "string",
  "data": [],
  "total": 42
}

FreightForward

POST /freight-forward/{carrier}

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 string Required

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

Body

Package to ship for Freight Forwarding DB

operation string Required

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)

Not more than 100 elements. Default value is [] (empty).
pageNo integer

Page number

Minimum value is 1.
pageSize integer

Page size

Minimum value is 1, maximum value is 100.

Responses

• 200 object

Success
- code integer(int32)
- message string
- data array
  
  An array of arbitrary types
- total integer(int32)
• 400

Invalid input
• 500 object

Failed
- code integer(int32)
- message string
- data array
  
  An array of arbitrary types
- total integer(int32)

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": [],
  "total": 42
}

Response example (500)

{
  "code": 42,
  "message": "string",
  "data": [],
  "total": 42
}

FreightForward

PUT /freight-forward/product/{carrier}

Update product data with specified carrier in Freight Forwarding DB.

Path parameters

carrier string Required

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

Body

Package to ship for Freight Forwarding DB

barcode string Required

The barcode of product
skuNumber string Required

The number of stock keeping unit
brand string Required

The brand name of current product
name string Required

The product name
nameCn string Required

Chinese name of product
hsCode string Required

The Harmonized Commodity Description and Coding System (HS code) of the tariff nomenclature is an international standardised system of names and numbers for the classification of commodities
model string

The model of current product.
customsUnitCodeWeight string Required

Legal first unit of measurement for customs product
customsUnitCode string

Legal second unit of measurement for customs product
customsUnitCodePackage string Required

The quantity unit code customs purpose. Declaration Unit
countryOfOrigin string Required

Country of origin of of product
netWeight number Required

Use Kilogram as the basic unit of mass
grossWeight number

Use Kilogram as the basic unit of mass
spec string

The spec of current product
descriptionEn string

The description of product
descriptionCn string

Chinese description of product
additionalImageUrls array[string]

Additional image urls
storeIds array[string]

Available store ids of product
rrpCny number(float)

Recommended retail price, unit is China Yuan
rrpGbp number(float)

Recommended retail price, unit is Great Britain Pound
customsFilingId string

The returned filing id of current SKU from customs
ingredients string

The ingredients of current product.
taxRate number(float)

Product tax rate for cross-border e-commerce(%)

Responses

• 200 object

Success
- code integer(int32)
- message string
- data array
  
  An array of arbitrary types
- total integer(int32)
• 400

Invalid input
• 500 object

Failed
- code integer(int32)
- message string
- data array
  
  An array of arbitrary types
- total integer(int32)

PUT /freight-forward/product/{carrier}

curl \
 -X PUT https://nomad.samarkand-global.cn/pilot/freight-forward/product/{carrier} \
 -H "x-ca-key: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"barcode":"12508742","skuNumber":"12508742","brand":"Percy \u0026 Reed","name":"12508742","nameCn":"12508742","hsCode":"3305900000","model":"iPhone XR","customsUnitCodeWeight":"035, means 千克/kilogram","customsUnitCode":"string","customsUnitCodePackage":"142","countryOfOrigin":"502","netWeight":0.25,"grossWeight":0.3,"spec":"250ml/瓶","descriptionEn":"string","descriptionCn":"string","additionalImageUrls":["string"],"storeIds":["string"],"rrpCny":158.4,"rrpGbp":18,"customsFilingId":"string","ingredients":"发酵乳杆菌Lc40（CECT5716），麦芽糊精，蔗糖，抗坏血酸钠","taxRate":9.1}'

Request example

{
  "barcode": "12508742",
  "skuNumber": "12508742",
  "brand": "Percy & Reed",
  "name": "12508742",
  "nameCn": "12508742",
  "hsCode": "3305900000",
  "model": "iPhone XR",
  "customsUnitCodeWeight": "035, means 千克/kilogram",
  "customsUnitCode": "string",
  "customsUnitCodePackage": "142",
  "countryOfOrigin": "502",
  "netWeight": 0.25,
  "grossWeight": 0.3,
  "spec": "250ml/瓶",
  "descriptionEn": "string",
  "descriptionCn": "string",
  "additionalImageUrls": [
    "string"
  ],
  "storeIds": [
    "string"
  ],
  "rrpCny": 158.4,
  "rrpGbp": 18,
  "customsFilingId": "string",
  "ingredients": "发酵乳杆菌Lc40（CECT5716），麦芽糊精，蔗糖，抗坏血酸钠",
  "taxRate": 9.1
}

Response example (200)

{
  "code": 42,
  "message": "string",
  "data": [],
  "total": 42
}

Response example (500)

{
  "code": 42,
  "message": "string",
  "data": [],
  "total": 42
}

carriers

carriers information

QueryCarrier

GET /carriers/

Query all carrier name or specific carrier

Query parameters

carrier_name string

The carrier name

Responses

• 200 object

Success
- code integer(int32)
- message string
- data array
  
  An array of arbitrary types
- total integer(int32)
• 400

Invalid input
• 500 object

Failed
- code integer(int32)
- message string
- data array
  
  An array of arbitrary types
- total integer(int32)

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": [],
  "total": 42
}

Response example (500)

{
  "code": 42,
  "message": "string",
  "data": [],
  "total": 42
}

batch

Manage batches for shipping Royal Mail parcels in the UK only.

Batch

POST /ship/{carrier}/create-batch

Create a batch to add parcels to for UK shipments only.

Path parameters

carrier string Required

The carrier name

Responses

• 200 object

Batch creation successed
- code integer(int32)
- message string
- data object
  shipmentId string
  
  scanFormId string
  
  scanFormUrl string
  
  trackingReference string
  
  waybillId string
  
  Logistics company waybill no.
  
  orderSn string Deprecated
  
  Deprecated. Replaced by 'orderRef'.
  
  orderRef string
  
  Order reference number. Default is from Odoo.
  
  sellerOrderRef string
  
  Order reference number. Also could be from retailers, e.g. Youzan.
  
  domesticDeliveryCompany string
  
  the domestic delivery vender for sinotrans
  
  deliveryStatus string
  
  The delivery status of one package
  
  Values are PREPARE_ORDER, SORT_ORDER, PACK_ORDER, ORDER_OUTBOUND, DELIVERY, FLIGHT_DEPARTURE, FLIGHT_ARRIVE, CUSTOM_CLEAR, CUSTOM_CLEAR_COMPLETE, CUSTOM_CLEAR_FAILURE, DOMESTIC_DELIVERY, DOMESTIC_IN_TRANSIT, DOMESTIC_SIGNING, DOMESTIC_SUCCESS, DOMESTIC_RETURNED, or DOMESTIC_FAILURE.
  
  deliveryNote string
  
  A note marked by the carrier, could be changed at any time.
  
  deliverySlipUrl string
  
  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)
  
  Default value is false.
  
  errorCode string
  
  Error code, returning if waybill creation failed. Available codes which will be progressively clarified: PRODUCT_NOT_EXIST, ORDER_NOT_EXIST, AREA_RESTRICTED, PRODUCT_ERROR, CUSTOMER_ERROR, ADDRESS_ERROR, LOGISTIC_ERROR, OTHERS
  
  errorMessage string
  
  Error message, which will be progressively clarified
- 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]
  
  httpRequestRawData 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
  
  trackingReference string
  
  waybillId string
  
  Logistics company waybill no.
  
  orderSn string Deprecated
  
  Deprecated. Replaced by 'orderRef'.
  
  orderRef string
  
  Order reference number. Default is from Odoo.
  
  sellerOrderRef string
  
  Order reference number. Also could be from retailers, e.g. Youzan.
  
  domesticDeliveryCompany string
  
  the domestic delivery vender for sinotrans
  
  deliveryStatus string
  
  The delivery status of one package
  
  Values are PREPARE_ORDER, SORT_ORDER, PACK_ORDER, ORDER_OUTBOUND, DELIVERY, FLIGHT_DEPARTURE, FLIGHT_ARRIVE, CUSTOM_CLEAR, CUSTOM_CLEAR_COMPLETE, CUSTOM_CLEAR_FAILURE, DOMESTIC_DELIVERY, DOMESTIC_IN_TRANSIT, DOMESTIC_SIGNING, DOMESTIC_SUCCESS, DOMESTIC_RETURNED, or DOMESTIC_FAILURE.
  
  deliveryNote string
  
  A note marked by the carrier, could be changed at any time.
  
  deliverySlipUrl string
  
  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)
  
  Default value is false.
  
  errorCode string
  
  Error code, returning if waybill creation failed. Available codes which will be progressively clarified: PRODUCT_NOT_EXIST, ORDER_NOT_EXIST, AREA_RESTRICTED, PRODUCT_ERROR, CUSTOMER_ERROR, ADDRESS_ERROR, LOGISTIC_ERROR, OTHERS
  
  errorMessage string
  
  Error message, which will be progressively clarified
- 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]
  
  httpRequestRawData 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}/create-batch

curl \
 -X POST https://nomad.samarkand-global.cn/pilot/ship/{carrier}/create-batch \
 -H "x-ca-key: $API_KEY"

Response example (200)

{
  "code": 42,
  "message": "string",
  "data": {
    "shipmentId": "string",
    "scanFormId": "string",
    "scanFormUrl": "string",
    "trackingReference": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "DELIVERY",
    "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,
    "errorCode": "string",
    "errorMessage": "string"
  },
  "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",
    "trackingReference": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "DELIVERY",
    "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,
    "errorCode": "string",
    "errorMessage": "string"
  },
  "connectorResponses": [
    {
      "input": "{\"product_id\": 12121}",
      "mappingName": "GetProductOp",
      "api": [
        "string"
      ],
      "httpRequestRawData": "-",
      "code": 42,
      "response": "string",
      "responseEn": "string",
      "platform": "youzan",
      "requestCount": 1,
      "responseTime": 1000
    }
  ],
  "responseTime": 1000
}

Batch

POST /ship/{carrier}/batch/{batch_id}/add-to-batch

Add a parcel to a batch for UK shipments only.

Path parameters

carrier string Required

The carrier name
batch_id string Required

The batch name returned from the create batch method

Body Required

Waybill ID

waybillId string

Responses

• 200 object

Parcel creation successed
- code integer(int32)
- message string
- data object
  shipmentId string
  
  scanFormId string
  
  scanFormUrl string
  
  trackingReference string
  
  waybillId string
  
  Logistics company waybill no.
  
  orderSn string Deprecated
  
  Deprecated. Replaced by 'orderRef'.
  
  orderRef string
  
  Order reference number. Default is from Odoo.
  
  sellerOrderRef string
  
  Order reference number. Also could be from retailers, e.g. Youzan.
  
  domesticDeliveryCompany string
  
  the domestic delivery vender for sinotrans
  
  deliveryStatus string
  
  The delivery status of one package
  
  Values are PREPARE_ORDER, SORT_ORDER, PACK_ORDER, ORDER_OUTBOUND, DELIVERY, FLIGHT_DEPARTURE, FLIGHT_ARRIVE, CUSTOM_CLEAR, CUSTOM_CLEAR_COMPLETE, CUSTOM_CLEAR_FAILURE, DOMESTIC_DELIVERY, DOMESTIC_IN_TRANSIT, DOMESTIC_SIGNING, DOMESTIC_SUCCESS, DOMESTIC_RETURNED, or DOMESTIC_FAILURE.
  
  deliveryNote string
  
  A note marked by the carrier, could be changed at any time.
  
  deliverySlipUrl string
  
  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)
  
  Default value is false.
  
  errorCode string
  
  Error code, returning if waybill creation failed. Available codes which will be progressively clarified: PRODUCT_NOT_EXIST, ORDER_NOT_EXIST, AREA_RESTRICTED, PRODUCT_ERROR, CUSTOMER_ERROR, ADDRESS_ERROR, LOGISTIC_ERROR, OTHERS
  
  errorMessage string
  
  Error message, which will be progressively clarified
- 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]
  
  httpRequestRawData 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
  
  trackingReference string
  
  waybillId string
  
  Logistics company waybill no.
  
  orderSn string Deprecated
  
  Deprecated. Replaced by 'orderRef'.
  
  orderRef string
  
  Order reference number. Default is from Odoo.
  
  sellerOrderRef string
  
  Order reference number. Also could be from retailers, e.g. Youzan.
  
  domesticDeliveryCompany string
  
  the domestic delivery vender for sinotrans
  
  deliveryStatus string
  
  The delivery status of one package
  
  Values are PREPARE_ORDER, SORT_ORDER, PACK_ORDER, ORDER_OUTBOUND, DELIVERY, FLIGHT_DEPARTURE, FLIGHT_ARRIVE, CUSTOM_CLEAR, CUSTOM_CLEAR_COMPLETE, CUSTOM_CLEAR_FAILURE, DOMESTIC_DELIVERY, DOMESTIC_IN_TRANSIT, DOMESTIC_SIGNING, DOMESTIC_SUCCESS, DOMESTIC_RETURNED, or DOMESTIC_FAILURE.
  
  deliveryNote string
  
  A note marked by the carrier, could be changed at any time.
  
  deliverySlipUrl string
  
  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)
  
  Default value is false.
  
  errorCode string
  
  Error code, returning if waybill creation failed. Available codes which will be progressively clarified: PRODUCT_NOT_EXIST, ORDER_NOT_EXIST, AREA_RESTRICTED, PRODUCT_ERROR, CUSTOMER_ERROR, ADDRESS_ERROR, LOGISTIC_ERROR, OTHERS
  
  errorMessage string
  
  Error message, which will be progressively clarified
- 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]
  
  httpRequestRawData 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}/batch/{batch_id}/add-to-batch

curl \
 -X POST https://nomad.samarkand-global.cn/pilot/ship/{carrier}/batch/{batch_id}/add-to-batch \
 -H "x-ca-key: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"waybillId":"string"}'

Request example

{
  "waybillId": "string"
}

Response example (200)

{
  "code": 42,
  "message": "string",
  "data": {
    "shipmentId": "string",
    "scanFormId": "string",
    "scanFormUrl": "string",
    "trackingReference": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "DELIVERY",
    "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,
    "errorCode": "string",
    "errorMessage": "string"
  },
  "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",
    "trackingReference": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "DELIVERY",
    "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,
    "errorCode": "string",
    "errorMessage": "string"
  },
  "connectorResponses": [
    {
      "input": "{\"product_id\": 12121}",
      "mappingName": "GetProductOp",
      "api": [
        "string"
      ],
      "httpRequestRawData": "-",
      "code": 42,
      "response": "string",
      "responseEn": "string",
      "platform": "youzan",
      "requestCount": 1,
      "responseTime": 1000
    }
  ],
  "responseTime": 1000
}

Batch

POST /ship/{carrier}/batch/{batch_id}/remove-from-batch

Add a parcel to a batch for UK shipments only.

Path parameters

carrier string Required

The carrier name
batch_id string Required

The batch name returned from the create batch method

Body Required

Waybill ID

waybillId string

Responses

• 200 object

Parcel creation successed
- code integer(int32)
- message string
- data object
  shipmentId string
  
  scanFormId string
  
  scanFormUrl string
  
  trackingReference string
  
  waybillId string
  
  Logistics company waybill no.
  
  orderSn string Deprecated
  
  Deprecated. Replaced by 'orderRef'.
  
  orderRef string
  
  Order reference number. Default is from Odoo.
  
  sellerOrderRef string
  
  Order reference number. Also could be from retailers, e.g. Youzan.
  
  domesticDeliveryCompany string
  
  the domestic delivery vender for sinotrans
  
  deliveryStatus string
  
  The delivery status of one package
  
  Values are PREPARE_ORDER, SORT_ORDER, PACK_ORDER, ORDER_OUTBOUND, DELIVERY, FLIGHT_DEPARTURE, FLIGHT_ARRIVE, CUSTOM_CLEAR, CUSTOM_CLEAR_COMPLETE, CUSTOM_CLEAR_FAILURE, DOMESTIC_DELIVERY, DOMESTIC_IN_TRANSIT, DOMESTIC_SIGNING, DOMESTIC_SUCCESS, DOMESTIC_RETURNED, or DOMESTIC_FAILURE.
  
  deliveryNote string
  
  A note marked by the carrier, could be changed at any time.
  
  deliverySlipUrl string
  
  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)
  
  Default value is false.
  
  errorCode string
  
  Error code, returning if waybill creation failed. Available codes which will be progressively clarified: PRODUCT_NOT_EXIST, ORDER_NOT_EXIST, AREA_RESTRICTED, PRODUCT_ERROR, CUSTOMER_ERROR, ADDRESS_ERROR, LOGISTIC_ERROR, OTHERS
  
  errorMessage string
  
  Error message, which will be progressively clarified
- 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]
  
  httpRequestRawData 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
  
  trackingReference string
  
  waybillId string
  
  Logistics company waybill no.
  
  orderSn string Deprecated
  
  Deprecated. Replaced by 'orderRef'.
  
  orderRef string
  
  Order reference number. Default is from Odoo.
  
  sellerOrderRef string
  
  Order reference number. Also could be from retailers, e.g. Youzan.
  
  domesticDeliveryCompany string
  
  the domestic delivery vender for sinotrans
  
  deliveryStatus string
  
  The delivery status of one package
  
  Values are PREPARE_ORDER, SORT_ORDER, PACK_ORDER, ORDER_OUTBOUND, DELIVERY, FLIGHT_DEPARTURE, FLIGHT_ARRIVE, CUSTOM_CLEAR, CUSTOM_CLEAR_COMPLETE, CUSTOM_CLEAR_FAILURE, DOMESTIC_DELIVERY, DOMESTIC_IN_TRANSIT, DOMESTIC_SIGNING, DOMESTIC_SUCCESS, DOMESTIC_RETURNED, or DOMESTIC_FAILURE.
  
  deliveryNote string
  
  A note marked by the carrier, could be changed at any time.
  
  deliverySlipUrl string
  
  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)
  
  Default value is false.
  
  errorCode string
  
  Error code, returning if waybill creation failed. Available codes which will be progressively clarified: PRODUCT_NOT_EXIST, ORDER_NOT_EXIST, AREA_RESTRICTED, PRODUCT_ERROR, CUSTOMER_ERROR, ADDRESS_ERROR, LOGISTIC_ERROR, OTHERS
  
  errorMessage string
  
  Error message, which will be progressively clarified
- 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]
  
  httpRequestRawData 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}/batch/{batch_id}/remove-from-batch

curl \
 -X POST https://nomad.samarkand-global.cn/pilot/ship/{carrier}/batch/{batch_id}/remove-from-batch \
 -H "x-ca-key: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"waybillId":"string"}'

Request example

{
  "waybillId": "string"
}

Response example (200)

{
  "code": 42,
  "message": "string",
  "data": {
    "shipmentId": "string",
    "scanFormId": "string",
    "scanFormUrl": "string",
    "trackingReference": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "DELIVERY",
    "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,
    "errorCode": "string",
    "errorMessage": "string"
  },
  "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",
    "trackingReference": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "DELIVERY",
    "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,
    "errorCode": "string",
    "errorMessage": "string"
  },
  "connectorResponses": [
    {
      "input": "{\"product_id\": 12121}",
      "mappingName": "GetProductOp",
      "api": [
        "string"
      ],
      "httpRequestRawData": "-",
      "code": 42,
      "response": "string",
      "responseEn": "string",
      "platform": "youzan",
      "requestCount": 1,
      "responseTime": 1000
    }
  ],
  "responseTime": 1000
}

Batch

POST /ship/{carrier}/batch/{batch_id}/create-scan-form

Create a scanform (manifest) for a batch

Path parameters

carrier string Required

The carrier name
batch_id string Required

The batch name returned from the create batch method

Responses

• 200 object

Parcel creation successed
- code integer(int32)
- message string
- data object
  shipmentId string
  
  scanFormId string
  
  scanFormUrl string
  
  trackingReference string
  
  waybillId string
  
  Logistics company waybill no.
  
  orderSn string Deprecated
  
  Deprecated. Replaced by 'orderRef'.
  
  orderRef string
  
  Order reference number. Default is from Odoo.
  
  sellerOrderRef string
  
  Order reference number. Also could be from retailers, e.g. Youzan.
  
  domesticDeliveryCompany string
  
  the domestic delivery vender for sinotrans
  
  deliveryStatus string
  
  The delivery status of one package
  
  Values are PREPARE_ORDER, SORT_ORDER, PACK_ORDER, ORDER_OUTBOUND, DELIVERY, FLIGHT_DEPARTURE, FLIGHT_ARRIVE, CUSTOM_CLEAR, CUSTOM_CLEAR_COMPLETE, CUSTOM_CLEAR_FAILURE, DOMESTIC_DELIVERY, DOMESTIC_IN_TRANSIT, DOMESTIC_SIGNING, DOMESTIC_SUCCESS, DOMESTIC_RETURNED, or DOMESTIC_FAILURE.
  
  deliveryNote string
  
  A note marked by the carrier, could be changed at any time.
  
  deliverySlipUrl string
  
  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)
  
  Default value is false.
  
  errorCode string
  
  Error code, returning if waybill creation failed. Available codes which will be progressively clarified: PRODUCT_NOT_EXIST, ORDER_NOT_EXIST, AREA_RESTRICTED, PRODUCT_ERROR, CUSTOMER_ERROR, ADDRESS_ERROR, LOGISTIC_ERROR, OTHERS
  
  errorMessage string
  
  Error message, which will be progressively clarified
- 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]
  
  httpRequestRawData 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
  
  trackingReference string
  
  waybillId string
  
  Logistics company waybill no.
  
  orderSn string Deprecated
  
  Deprecated. Replaced by 'orderRef'.
  
  orderRef string
  
  Order reference number. Default is from Odoo.
  
  sellerOrderRef string
  
  Order reference number. Also could be from retailers, e.g. Youzan.
  
  domesticDeliveryCompany string
  
  the domestic delivery vender for sinotrans
  
  deliveryStatus string
  
  The delivery status of one package
  
  Values are PREPARE_ORDER, SORT_ORDER, PACK_ORDER, ORDER_OUTBOUND, DELIVERY, FLIGHT_DEPARTURE, FLIGHT_ARRIVE, CUSTOM_CLEAR, CUSTOM_CLEAR_COMPLETE, CUSTOM_CLEAR_FAILURE, DOMESTIC_DELIVERY, DOMESTIC_IN_TRANSIT, DOMESTIC_SIGNING, DOMESTIC_SUCCESS, DOMESTIC_RETURNED, or DOMESTIC_FAILURE.
  
  deliveryNote string
  
  A note marked by the carrier, could be changed at any time.
  
  deliverySlipUrl string
  
  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)
  
  Default value is false.
  
  errorCode string
  
  Error code, returning if waybill creation failed. Available codes which will be progressively clarified: PRODUCT_NOT_EXIST, ORDER_NOT_EXIST, AREA_RESTRICTED, PRODUCT_ERROR, CUSTOMER_ERROR, ADDRESS_ERROR, LOGISTIC_ERROR, OTHERS
  
  errorMessage string
  
  Error message, which will be progressively clarified
- 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]
  
  httpRequestRawData 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}/batch/{batch_id}/create-scan-form

curl \
 -X POST https://nomad.samarkand-global.cn/pilot/ship/{carrier}/batch/{batch_id}/create-scan-form \
 -H "x-ca-key: $API_KEY"

Response example (200)

{
  "code": 42,
  "message": "string",
  "data": {
    "shipmentId": "string",
    "scanFormId": "string",
    "scanFormUrl": "string",
    "trackingReference": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "DELIVERY",
    "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,
    "errorCode": "string",
    "errorMessage": "string"
  },
  "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",
    "trackingReference": "string",
    "waybillId": "string",
    "orderSn": "string",
    "orderRef": "string",
    "sellerOrderRef": "string",
    "domesticDeliveryCompany": "YTO",
    "deliveryStatus": "DELIVERY",
    "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,
    "errorCode": "string",
    "errorMessage": "string"
  },
  "connectorResponses": [
    {
      "input": "{\"product_id\": 12121}",
      "mappingName": "GetProductOp",
      "api": [
        "string"
      ],
      "httpRequestRawData": "-",
      "code": 42,
      "response": "string",
      "responseEn": "string",
      "platform": "youzan",
      "requestCount": 1,
      "responseTime": 1000
    }
  ],
  "responseTime": 1000
}

callback

The callback endpoints of logistics, available provider haiku.

Callback

POST /callback/{store}

The callback endpoints of logistics, available provider haiku

Path parameters

store string Required

ID of the logistics provider.

Body Required

The callback body of logistics

deliveryOrder object
- deliveryOrderCode string
  
  ERP order no
- deliveryOrderId string
  
  Warehouse delivery order no
- warehouseCode string
  
  warehouse code
- orderType string
  
  order type
- status string
- outBizCode string
- confirmType string
- orderConfirmTime string
- operatorCode string
- operatorName string
- operateTime string
- storageFee string
- logisticsCode string
- logisticsName string
- expressCode string

Responses

• 200 object

The order confirmation of logistics has been processed successfully.
- success string
  
  Default value is success.
- errorcode string
- errormsg string
• 400 object

Invalid input.
- success string
  
  Default value is success.
- errorcode string
- errormsg string
• 500 object

Order confirmation failed.
- success string
  
  Default value is success.
- errorcode string
- errormsg string

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": "success",
  "errorcode": "string",
  "errormsg": "string"
}

Response example (400)

{
  "success": "success",
  "errorcode": "string",
  "errormsg": "string"
}

Response example (500)

{
  "success": "success",
  "errorcode": "string",
  "errormsg": "string"
}

inventory

Inventory endpoints of logistics, available supplier jingdong.

Inventory

GET /inventory/product/{carrier}

Query products details from third party logistics company.

Path parameters

carrier string Required

The carrier name

Query parameters

warehouse_goods_no string

Product number used in warehouse.
stock_status string

Stock status, options: 1, Good product; 2, Defective product; 3, Samples.

Values are GOOD, DEFECTIVE, or SAMPLE.
stock_type string

Stock type, options: 1, Normal; 2, Product to be returned; 3, Store reservation; 4, Warehouse lock; 5, Inventory lock.

Values are NORMAL, RETURNED, RESERVATION, WAREHOUSE_LOCK, or INVENTORY_LOCK.
shop_no string

Shop number, required for shop stock query.
page_no integer(int32)

Page number, between 1 and 1000

Minimum value is 1, maximum value is 1000. Default value is 1.
page_size integer(int32)

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

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

Responses

• 200 object

Update products successfully.
- code integer(int32)
- message string
- 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]
  
  httpRequestRawData 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.
- products array[object]
  merchantGoodsNo string
  
  platformGoodsNo string
  
  warehouseGoodsNo string
  
  Warehouse goods No, generated by warehouse.
  
  barcodes string
  
  Barcodes, multiple bar codes are separated by commas.
  
  thirdCategoryNo string
  
  Goods category code of third level, required by Jingdong Logistics.
  
  goodsName string
  
  shopNo string
  
  stockStatus string
  
  stockType string
  
  totalNum string
  
  usableNum string
  
  recordCount string
  
  brandName string
  
  manufacturer string
  
  produceAddress string
  
  grossWeight number(float)
  
  Gross weight, the unit of mass is kilograms.
  
  netWeight number(float)
  
  Net weight, the unit of mass is kilograms.
  
  safeDays integer(int32)
  
  adventDay integer(int32)
- purchases array[object]
  warehousePurchaseNo string
  
  Warehouse purchase No, generated by warehouse.
  
  warehouseGoodsNo string
  
  Warehouse goods No, generated by warehouse.

Nomad Pilot 1.52.0

Body Required

Body Required

Body Required

Body Required

Body Required

Body Required

Body Required

Nomad Pilot
1.52.0