Waybill Generation

This REST API is used to get AWB (waybill) number from the shipping provider/aggregator in reference to the shipment (shippingPackage).In this POST request, Uniware sends the shipment details, pickup and delivery address details. While the shipping provider/aggregator responds with waybill number and a link to download shippingLabel in PDF format.

Tip

It is recommended to check out Notes for the reader. You might find this helpful as it contains Guidelines for using API references and Terminologies used here.

Flow

Waybill_Flow

Tip

Complete integration flow is available on Basic Overview page.

Basic Information

NAME DETAILS
Usage: Mandatory
Endpoint: /waybill
Request Type: POST
Scheme: HTTPS
Header (content-type) application/json
Header (Authorization): token (got from SP Authentication)

Request Payload (Forward Shipment)

{
  "serviceType": "String",
  "handOverMode": "String",
  "returnShipmentFlag": "false",
  "Shipment": {
    "code": "String",
    "SaleOrderCode": "String",
    "orderCode": "String",
    "channelCode": "String",
    "channelName": "String",
    "source": "unicommerce",
    "customField" : [],
    "invoiceCode": "String",
    "orderDate": "16-Sep-2021 00:00:00",
    "fullFilllmentTat": "18-Sep-2021 00:00:00",
    "weight": "53.4000",
    "length": "30",
    "height": "10",
    "breadth": "15",
    "numberOfBoxes": "1",
    "items": [
      {
        "name": "String",
        "description": "String",
        "quantity": 2,
        "skuCode": "string",
        "itemPrice": 600.00,
        "imageURL": "string",
        "hsnCode": "string",
        "tags": "string",
        "brand": "string",
        "color": "string",
        "category": "string",
        "size": "string",
        "item_details": "string",
        "ean": ""
      },
      {
        "name": "String",
        "description": "String",
        "quantity": 1,
        "skuCode": "string",
        "itemPrice": 600.00,
        "imageURL": "string",
        "hsnCode": "string",
        "tags": "string",
        "brand": "string",
        "color": "string",
        "category": "string",
        "size": "string",
        "item_details": "string",
        "ean": ""
      }
    ]
  },
  "deliveryAddressId": "String",
  "deliveryAddressDetails": {
    "name": "String",
    "email": "String",
    "phone": "8888888888",
    "address1": "String",
    "address2": "String",
    "pincode": "122016",
    "city": "Gurgaon",
    "state": "Haryana",
    "country": "India",
    "stateCode": "HR",
    "countryCode": "IN",
    "gstin": "string",
    "alternatePhone": "9090909090",
    "district": ""
  },
  "pickupAddressId": "String",
  "pickupAddressDetails": {
    "name": "String",
    "email": "String",
    "phone": "9999999999",
    "address1": "String",
    "address2": "String",
    "pincode": "400092",
    "city": "Mumbai",
    "state": "Maharashtra",
    "country": "India",
    "stateCode": "MH",
    "countryCode": "IN",
    "gstin": "string"
  },
  "returnAddressId": "String",
  "returnAddressDetails": {
    "name": "String",
    "email": "String",
    "phone": "9999999999",
    "address1": "String",
    "address2": "String",
    "pincode": "400092",
    "city": "Mumbai",
    "state": "Maharashtra",
    "country": "India",
    "stateCode": "HR",
    "countryCode": "IN",
    "gstin": "string"
  },
  "currencyCode": "INR",
  "paymentMode": "PREPAID",
  "totalAmount": "200.00",
  "collectableAmount": "0",
  "courierName": "String",
  "customField": [
    {
      "name": "String",
      "value": "String"
    },
    {
      "name": "String",
      "value": "String"
    }
  ]
}

Request Payload (Reverse Shipment)

{
  "serviceType": "String",
  "handOverMode": "String",
  "returnShipmentFlag": "true",
  "Shipment": {
    "code": "String",
    "SaleOrderCode": "String",
    "orderCode": "String",
    "channelCode": "String",
    "channelName": "String",
    "source": "unicommerce",
    "customField" : [],
    "orderDate": "16-Sep-2021 00:00:00",
    "fullFilllmentTat": "18-Sep-2021 00:00:00",
    "weight": "53.4000",
    "length": "30",
    "height": "10",
    "breadth": "15",
    "items": [
      {
        "name": "String",
        "description": "String",
        "quantity": 2,
        "skuCode": "string",
        "itemPrice": 600.00,
        "imageURL": "string",
        "hsnCode": "string",
        "tags": "string",
        "brand": "string",
        "color": "string",
        "category": "string",
        "size": "string",
        "item_details": "string",
        "ean": "string",
        "return_reason": "string"
      },
      {
        "name": "String",
        "description": "String",
        "quantity": 1,
        "skuCode": "String",
        "itemPrice": 600.00,
        "imageURL": "String",
        "hsnCode": "String",
        "tags": "String",
        "brand": "String",
        "color": "String",
        "category": "String",
        "size": "String",
        "item_details": "String",
        "ean": "String",
        "return_reason": "String"
      }
    ]
  },
  "deliveryAddressId": "String",
  "deliveryAddressDetails": {
    "name": "String",
    "email": "String",
    "phone": "8888888888",
    "address1": "String",
    "address2": "String",
    "pincode": "122016",
    "city": "Gurgaon",
    "state": "Haryana",
    "country": "India",
    "stateCode": "HR",
    "countryCode": "IN",
    "gstin": "string"
  },
  "pickupAddressId": "String",
  "pickupAddressDetails": {
    "name": "String",
    "email": "String",
    "phone": "9999999999",
    "address1": "String",
    "address2": "String",
    "pincode": "400092",
    "city": "Mumbai",
    "state": "Maharashtra",
    "country": "India",
    "stateCode": "MH",
    "countryCode": "IN",
    "district": "String",
    "alternatePhone": "9090909090"
  },
  "currencyCode": "INR",
  "paymentMode": "PREPAID",
  "totalAmount": "200.00",
  "collectableAmount": "0",
  "courierName": "String"  
}

Request Payload Details

LEVEL PARAMETER TYPE DESCRIPTION MANDATORY NOTES
1 serviceType string Mode of shipment delivery e.g. air, road, surface or Service type B2B, B2C Opt. This can be any keyword defined by shipper with seller for respective service type at shipper configuration page in UC
2 handOverMode string Mode of shipment handover e.g. Drop, Pickup Opt. Allowable: Drop, Pickup This can be any keyword defined by shipper with seller for respective shipping at shipper configuration page in UC
3 returnShipmentFlag string true for reverse delivery Yes Allowable: “false” (Forward Delivery), “true” (Reverse Delivery)
4 Shipment list List of items in a shipment Yes -
4.1 code string Uniware driven Shipment code/id or reference no. Yes it will be unique at seller’s UC warehouse level
4.2 SaleOrderCode string Channel driven Sale order code/id/No Yes it will be unique at channel level
4.3 orderCode string Channel driven Display sale order code/id/No Yes it can be duplicate at channel level
4.4 channelCode string Channel Source Code Opt. Channel source code that is created by UC backend team
4.5 channelName string Channel Name Opt. Channel name that is created by Seller
4.6 invoiceCode string Sale Invoice code Opt. This field is only passed in forward delivery ( not in reverse )
4.7 orderDate date Date of order Yes Format: dd-mmm-yyyy HH:mm:ss Eg: 16-Sep-2021 00:00:00
4.8 fullFilllmentTat date Turnaround time for delivery Yes Format: dd-mmm-yyyy HH:mm:ss Eg: 18-Sep-2021 00:00:00
4.9 weight Float Unit: gm Yes Eg:53.4000, max value cannot have more than 6 digits and 4 decimal places
4.10 length string Unit: mm Yes Eg: 100
4.11 height string Unit: mm Yes Eg: 100
4.12 breadth string Unit: mm Yes Eg: 300
4.14 numberOfBoxes string child box count associated with one shipment, Default: 1 Yes This field is only passed in forward delivery ( not in reverse )
4.13 items array Details of items in shipment Yes -
4.13.1 name string Item name Yes -
4.13.2 description string Item description Yes -
4.13.3 quantity integer Item quantity Yes -
4.13.4 skuCode string Uniware SKU Code Yes This field is only passed in forward delivery ( not in reverse )
4.13.5 itemPrice float Single item price including taxes and without discount Yes This field is only passed in forward delivery ( not in reverse )
4.13.6 imageURL string Item Image URL Opt This field is only passed in forward delivery ( not in reverse )
4.13.7 hsnCode string Item 6 digit uniform code that classifies products worldwide Opt This field is only passed in forward delivery ( not in reverse )
4.13.8 tags string Item tags available at the item in Uniware Opt -
4.13.9 brand string Item brand Opt -
4.13.10 color string Item color Opt -
4.13.11 category string Item category Opt -
4.13.12 size string Item size Opt -
4.13.12 item_details string it can be certificate, imei, itemSealId, serialNumber, weight Opt Sample Value: “item_details” : ”{“weight”:“12”,“Imei”:“9123456876543”},{“weight”:“11”,“Imei”:“123456789012345”}” Values are provided by tenant while creating SKU
4.13.14 ean string Item EAN Opt International Article Number (also known as European Article Number)
4.13.15 return_reason string Item return reason Opt This field is only passed in case of reverse shipment
4.14 source string Integrator identity Opt. Hardcore value i.e, “unicommerce”
4.15 customField string customField Opt. If needed seller needs to congifured for respective shipping at shipper configuration in UC, For further information, please refer to the FAQs listed below.
5 deliveryAddressId string Delivery Address Id Opt Check faq Q3 below, Forward: Blank ""
6 deliveryAddressDetails list Delivery address details Yes Check faq Q3 below, Forward: Customer address details
6.1 name string Receiver name Yes -
6.2 email string Receiver Email Opt -
6.3 phone string Receiver Contact no. Yes -
6.4 address1 string Receiver Address Yes -
6.5 address2 string Receiver Address Opt. -
6.6 pincode string Receiver Pincode Yes -
6.7 city string Receiver City Yes -
6.8 state string Receiver State Yes -
6.9 country string Receiver Country Yes -
6.10 stateCode string 2 digit ISO code for state Yes -
6.11 countryCode string 2 digit ISO code for country Yes -
6.12 gstin string gstin no. Opt -
6.13 alternatePhone string Alternate Phone Opt -
6.14 district string End Customer District Opt -
7 pickupAddressId string Pickup Address ID Opt. Check faq Q3 below
8 pickupAddressDetails list Pickup Address Details Yes Check faq Q3 below
8.1 name string Sender name Yes -
8.2 email string Sender Email Opt. -
8.3 phone string Sender Contact no. Yes -
8.4 address1 string Sender Address Yes -
8.5 address2 string Sender Address Opt. -
8.6 pincode string Sender Pincode Yes -
8.7 city string Sender City Yes -
8.8 state string Sender State Yes -
8.9 country string Sender Country Yes -
8.10 stateCode string 2 digit ISO code for state Yes -
8.11 countryCode string 2 digit ISO code for country Yes -
8.12 gstin string gstin no. Opt -
9 returnAddressId string Seller address ID Opt. Check faq Q3 below, Reverse: in case of returnShipmentFlag = true, this param will not be passed by UC
10 returnAddressDetails list Seller address details Yes Check faq Q3 below, Reverse: in case of returnShipmentFlag = true, this param will not be passed by UC
10.1 name string Sender name Yes -
10.2 email string Sender Email Opt. -
10.3 phone string Sender Contact no. Yes -
10.4 address1 string Sender Address Yes -
10.5 address2 string Sender Address Opt. -
10.6 pincode string Sender Pincode Yes -
10.7 city string Sender City Yes -
10.8 state string Sender State Yes -
10.9 country string Sender Country Yes -
10.10 stateCode string 2 digit ISO code for state Yes -
10.11 countryCode string 2 digit ISO code for country Yes -
11 currencyCode string Three letter currency code Yes Currency Codes
12 paymentMode string Mode of payment Yes Allowable: COD, PREPAID
13 totalAmount string order value Yes Eg: 200.00
14 collectableAmount string Amount to be collected at time of delivery Yes Eg: 0.00 for Prepaid mode
15 courierName string Name of actual courier allocated Opt. -

Response Payload

{
"status": "SUCCESS",
"waybill": "String",
"shippingLabel": "label url link",
"courierName": "String",
"routingCode": "String"  
}

Response Payload (Error)

{
   "status":"FAILED",
   "reason":"String",
   "message":"String"
}

NOTE:

It is mandatory to send the shipping label in .pdf format. It is anticipated from shipping provider to send a link to dowload pdf file in `shippingLabel’.

Response Payload Details

PARAMETER TYPE - DESCRIPTION NOTES
status string Status of the API request Allowable: SUCCESS, FAILED
waybill string Shipment tracking number -
shippingLabel string Path of the shipping label for .pdf format in Forward case only, If shipping provider provides shipping label. Eg. https://bucket.s3.amazonaws.1653544351.pdf
courierName string Name of shipping provider For shipping aggregator, pass LSP name here. Else, pass your shipper company name in case of Direct LSP
routingCode string Shipper pickup routing code -
reason string Reason of failure Categorisation of failure reason. E.g. WRONG INPUT, Address issue
message string Definded failure error message Case-1: Specific to non serviceable, the Message must be: “Delivery Pincode is not serviceable” Case-2: For any other Specific cases, you can pass the readable error message e.g. Wallet balance is low, Service is inactive

Error Codes

Refer Response Codes section to know about specific errors codes.

FAQs/Notes

Q1. How is a unique order key can be made or used on label by shipping privider?
Ans. A unique Order key need to be made at shipper end by concatenation of SaleOrderCode_code but ideally you should consume all 3 fields i.e. code, SaleOrderCode and orderCode. Since sellers sometimes need orderCode (Display Order Code) with order id to shown on label pdf too.

Q2. How can numberOfBoxes param be used by shipping privider?
Ans. The numberOfBoxes param indicates the number of parts (boxes) that the seller uses to pack goods into multiple boxes for a single shipment. Here as a shipping provider if you have a concept of child-parent AWBs along with Multi-Page Label PDF Then please send only the parent AWB along with only the Label PDF containing multiple pages having child AWBs print. UC will not store child AWB.Tracking will be done only with respect to parent AWB.

Q3. What is the use for “customField” param here?
Ans. This customField is a customized configuration at Seller account level and mapping stored at shipper connector level, where tenant can mention the comma separated name of the fields.

For Forward Journey: Custom field defined at shipping package level , Sale order level and box level can be sent in the request.
For Reverse Journey: Custom field defined at reverse pickup level and Sale order level can be sent in the request

To configure the mapping of UC and Shipper Key, the json mapping provided at Shipping Provider connector on uniware:

1- SaleOrder Custom Field Mapping (For Forward Journey)
2- ShippingPackage Custom Field Mapping (For Forward Journey)
3- Box Custom Field Mapping (For Forward Journey)
4- ReversePickup Custom Field Mapping (For Reverse Journey)
5- SaleOrder Custom Field Mapping For ReversePickup (For Reverse Journey)

Example:
Sample value configured in connectors:
At shipping package level : {‘UCkey’:‘SPkey’,‘UCkey2’:‘SPkey2’}
At sale order level : {‘UCkey3’:‘SPkey3’,‘UCkey4’:‘SPkey4’}

Here, UCkey is key defined in UC and SPkey is the parameter expected by courier

Parameter in the request will be like:

“customField”: [ { “name”: “SPkey”, “value”: “XYZ” }, { “name”: “SPkey2”, “value”: “ABC” }, { “name”: “SPkey3”, “value”: “XYZ” }, { “name”: “SPkey4”, “value”: “ABC” } ]

All of the configured Custom fields at different level will be sent in the single array that is customField in the Request

If value of any of the UCkey is not found then in the request blank array that is customField is sent as given below:
“customField” : []

Q4. How can the shipping provider distinguish whether the pickup request is for a forward AWB or a reverse AWB?
Ans. This waybill generation API is equipped to manage pickup requests for both forward and reverse delivery scenarios using the returnShipmentFlag. The forward delivery means the shipment is delivered to the customer, whereas the reverse delivery is when the shipment is sent back to seller.

  • In case of Forward Delivery (from seller to customer)

    • deliveryAddressId : Blank ""
    • deliveryAddressDetails: Customer Address Details from source order data
    • pickupAddressId : Seller Address Id provided by shipper (defined at courier end) used at Uniware Shipper setting at “Pickup Address Id” or at Facility alias, else Blank ""
    • pickupAddressDetails : Seller Address Details from uniware with “Pickup Address Id” and Facility alias are set as blank, else Blank {}
    • returnAddressId : Seller Address Id provided by shipper (defined at courier end) used at Uniware Shipper setting at “Pickup Address Id” or at Facility alias, else Blank ""
    • returnAddressDetails : Seller address details from uniware with “Pickup Address Id” and Facility alias are set as blank, else Blank {}
    • returnShipmentFlag : false
Param Name Case1 Case2 Case3
deliveryAddressId Blank Blank Blank
deliveryAddressDetails Cx address Cx address Cx address
pickupAddressId Blank Facility alias Pickup Address Id
pickupAddressDetails Actual address Blank Blank
returnAddressId Blank Facility alias Pickup Address Id
returnAddressDetails Actual address Blank Blank
returnShipmentFlag false false false
  • In case of Reverse Delivery (from customer to seller)

    • deliveryAddressId : Seller Address Id provided by shipper (defined at courier end) used at Uniware Shipper setting at “Pickup Address Id” or at Facility alias, else Blank ""
    • deliveryAddressDetails : Seller Address Details from uniware with “Pickup Address Id” and Facility alias are set as blank, else Blank {}
    • pickupAddressId : Blank ""
    • pickupAddressDetails : Customer Address Details from source order data
    • returnShipmentFlag : true
Param Name Case1 Case2 Case3
deliveryAddressId Blank Facility alias Pickup Address Id
deliveryAddressDetails Seller address Blank Blank
pickupAddressId Blank Blank Blank
pickupAddressDetails Cx address Cx address Cx address
returnShipmentFlag true true true

NOTE:

In case of Marketplaces/Sellers where they may have Delivery from Location A to Customer at Location B, while the returns for that particular facility (Location A) might be taking place at another location, Location C. These values (PickupAddress, ReturnAddress, deliveryAddress) will be pushed on the basis of Channel Return Facility Mapping set by the seller’s user. If there are no such setting by the user, then current flow of Reverse Delivery (from customer to the seller) works.

Q5. What will be the response payload for this API?
Ans. It is mandatory to send the waybill label in .pdf format Eg. https://bucket.s3.amazonaws.1653544351.pdf This should be done only once a downloadable print is available at this location, along with all requested details in the response payload to avoid parsing errors.

Unicommerce Website

Copyright © 2024 Unicommerce eSolutions Pvt. Ltd.