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

Tip

Complete integration flow is available on Basic Overview page.

Basic Information

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": "",
    "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

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

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

• 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

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. How does UC manage the forward or reverse AWB when it is updated on the shipper’s side after being assigned to their system?
Ans. UC only considers the AWB received via this API call response, and it will not change throughout the further journey. Shippers must ensure that the AWB remains consistent. If any changes occur, they must link the updated AWB to the old one for tracking purposes.

Q6. 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.