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 datapickupAddressId
: 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 uniwarereturnShipmentFlag
: 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 datareturnShipmentFlag
: 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
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 | 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 | 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 | 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.