Waybill Generation

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

The waybill generation will be applicable for both the forward and reverse delivery. 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 to use at Uniware Shipper setting at “Pickup Address Id”, else Blank ""
    • pickupAddressDetails : Seller Address Details from uniware with “Pickup Address Id” is set as blank, else Blank {}
    • returnAddressId : Blank ""
    • returnAddressDetails : Seller address details from uniware
    • returnShipmentFlag : false

  • In Case of Reverse Delivery (from customer to seller)

    • deliveryAddressId : Seller Address Id provided by shipper to use at Uniware Shipper setting at “Pickup Address Id”, else Blank ""
    • deliveryAddressDetails : Seller Address Details from uniware with “Pickup Address Id” is set as blank, else Blank {}
    • pickupAddressId : Blank ""
    • pickupAddressDetails : Customer Address Details from source order data
    • returnShipmentFlag : true

In Case: 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.

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",
      "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"
         },
         {
            "name": "String",
            "description": "String",
            "quantity": 1,
            "skuCode": "string",
            "itemPrice": 600.00,
            "imageURL": "string",
            "hsnCode": "string",
            "tags": "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",
      "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",

   },
   "currencyCode": "INR",
   "paymentMode": "PREPAID",
   "totalAmount": "200.00",
   "collectableAmount": "0",
   "courierName": "String"
}

Request Payload (Reverse Shipment)

{
   "serviceType": "String",
   "handOverMode": "String",
   "returnShipmentFlag": "true",
   "Shipment": {
      "code": "String",
      "SaleOrderCode" : "String",
      "orderCode": "String",
      "channelCode" : "String",
      "channelName" : "String",
      "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,
            "tags": "string"
         },
         {
            "name": "String",
            "description": "String",
            "quantity": 1,
            "tags": "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",
      "gstin": "string"
   },
   "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 (air, road) Opt. -
2 handOverMode string - Opt. Allowable: Drop, Pickup
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 Shipment code/id or reference no. Yes -
4.2 SaleOrderCode string Sale order code/id/No Yes -
4.3 orderCode string Display sale order code/id/No Yes -
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 -
5 deliveryAddressId string Always blank Opt Forward: Blank "", Reverse: seller address ID
6 deliveryAddressDetails list Customer address details Yes Forward: Customer address details, Reverse: seller 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 -
7 pickupAddressId string Seller address ID, if pickupAddressId is provided by Shipper Opt. Forward: Seller address ID, Reverse: Blank ""
8 pickupAddressDetails list Seller address details, if pickupAddressId is set Blank Yes Forward: Seller address details, Reverse: customer address details
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. Forward: Blank "", Reverse: in case of returnShipmentFlag = true, this param would not be passed by UC
10 returnAddressDetails list Seller address details Yes Forward: Seller address details from Pickup Address/Return Mapping, Reverse: in case of returnShipmentFlag = true, this param would 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 - 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 agency allocated to the shipment. Opt. Filled only in case shipping provider assigns self-service.

Response Payload

{
"status": "SUCCESS",
"waybill": "String",
"shippingLabel": "label url link",
"courierName": "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 If shipping provider provides own 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
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 can be made 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.

Unicommerce Website

Copyright © 2023 Unicommerce eSolutions Pvt. Ltd.