Nomad Pilot API documentation

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
}