View Source

This document is for Logistics Aggregators who want to integrate with Increff RMS.

Setup

Contact increff support to get yourself registered as a Logistic aggregator.
A unique logistic aggregator name would need to be added to RMS.
Unique logistic aggregator name would be passed in the request body by RMS while making API calls to the logistic aggregator and also the logistic aggregator would pass this field in its request body while making API calls to RMS.

Credentials

Credential Headers that will be used by RMS while making API calls to Logistic Aggregator will be provided by logistic aggregator on an organisation level. These are called outbond calls for RMS.

For example, there are 2 increff omni clients who want to use RMS.

Orgs are created for them: org-1 and org-2.
They both want to use a logistic aggregator - say logistic-aggregator-1.
Then Logistic-aggregator-1 will have to provide separate credentials for org-1 and org-2.

Following credentials will be used by a logistic aggregator to make API calls to RMS. These are called inbound calls for RMS

These will be provided by the Increff team to the logistic aggregator. There will be separate credentials for each organization.

authDomainName
- authUsername
- authPassword

URLs values to be provided by Logistic Aggregator

Increff RMS will configure these url on its side. Still the request response will be shared by Increff RMS.

Generate Shipping Label URL
Get Shipping Label URL
Generate Return AWB URL
Get Return AWB URL
Get Couriers URL

URLs values provided by RMS

Client will have to configure this end point on their side and provide us the URL so we can make apis calls.

Push Notification URL

Flows

Forward Order Flow

Get Couriers API call

RMS will make this API call to the logistic aggregator APIs to get the list of couriers to use.
This priority of the couriers can also be sent in the response based on which the courier will be selected during the generate shipping label call.

Generate Shipping Label API call

RMS will make this API call to logistic aggregator APIs to generate the AWB and the shipping label PDF against a reference number.
From this list of couriers fetched in the Get Courier Recommendation API, RMS will choose the courier with the highest priority and will pass it in the payload of the generate shipping label call.
The logistic aggregator will generate the AWB and shipping label against this courier passed. It will also return a unique id by which the logistic aggregator will identify the order.

Get Shipping Label API call

RMS will use this API call to get the AWB and shipping label details. It will use the unique id returned by the logistic aggregator in the generate shipping label call as a request param to get these details.

Notification Flow

Logistic Aggregators can push the statuses of the orders (both forward and return) to RMS.
These notifications will be stored in RMS and forwarded to any system (proxy/client’s system).

API Interfaces

Get Courier Recommendation API

Outbound | POST

Request

{
   "pickupPincode": "560102",
   "dropPincode": "110019",
   "paymentType": "PREPAID",
   "shipmentType": "FORWARD",
   "orderAmount": 1200
}

Response

{
  "couriers": [
    {
      "courierId": 1001,
      "courierName": "Delhivery",
      "priority": 1
    },
    {
      "courierId": 1002,
      "courierName": "Fedex",
      "priority": 2
    }
  ]
}

Generate Shipping Label API

Outbound | POST

Request

{
  "pickupAddress": {
    "firstName": "Ram",
    "lastName": "Patel",
    "middleName": "",
    "addressLine1": "1205, 15th Main Road",
    "addressLine2": "HSR layout",
    "addressLine3": "",
    "city": "Bangalore",
    "state": "Karnataka",
    "zip": "560102",
    "country": "India",
    "email": "abc@gmail.com",
    "phone": "9999999999"
  },
  "dropAddress": {
    "firstName": "Shyam",
    "lastName": "Sharma",
    "middleName": "",
    "addressLine1": "A-101, Balaji Residency",
    "addressLine2": "Stadium road",
    "addressLine3": "Motera",
    "city": "Ahmedabad",
    "state": "Gujarat",
    "zip": "395007",
    "country": "India",
    "email": "abc@gmail.com",
    "phone": "9999999999"
  },
  "orderDetails": {
    "orderNumber": "asdf1234",
    "paymentType": "PREPAID",
    "orderAmount": 230,
    "orderDate": "2022-03-16T12:31:02+05:30",
    "shipmentType": "FORWARD",
    "orderLineItems": [
      {
        "name": "jeans",
        "sku": "sku-1",
        "sellingPricePerUnit": 100,
        "quantity": 1
      },
      {
        "name": "t-shirt",
        "sku": "sku-2",
        "sellingPricePerUnit": 130,
        "quantity": 1
      }
    ]
  },
  "shipmentDimension": {
    "length": 50,
    "breadth": 50,
    "height": 50,
    "weight": 200
  },
  "courierId": 1,
  "warehouseCode": "wh-1"
}

Parameter Name	Data Type	Description	Mandatory
`pickupAddress`	Object	Address from where the shipment is picked up (eg. the warehouse address)	yes
`pickupAddress.city`	String	City of warehouse address	yes
`pickupAddress.country`	String	Country of warehouse address	yes
`pickupAddress.email`	String	Email	no
`pickupAddress.firstName`	String	First Name	yes
`pickupAddress.lastName`	String	Last Name	no
`pickupAddress.middleName`	String	Middle Name	no
`pickupAddress.phone`	String	Phone Number	no
`pickupAddress.state`	String	State	yes
`pickupAddress.addressLine1`	String	1st line of warehouse address	yes
`pickupAddress.addressLine2`	String	2nd line of warehouse address	no
`pickupAddress.addressLine3`	String	3rd line of warehouse address	no
`pickupAddress.zip`	String	Zip/Pin code of warehouse address	yes
`dropAddress`	Object	Shipping Address of customer	yes
`dropAddress.city`	String	City of customer	yes
`dropAddress.country`	String	Country of customer	yes
`dropAddress.email`	String	Email of customer	no
`dropAddress.firstName`	String	First Name of customer	yes
`dropAddress.lastName`	String	Last Name of customer	no
`dropAddress.middleName`	String	Middle name of customer	no
`dropAddress.phone`	String	Phone Number of customer	no
`dropAddress.state`	String	State of customer	yes
`dropAddress.addressLine1`	String	1st line of customer address	yes
`dropAddress.addressLine2`	String	2nd line of customer address	no
`dropAddress.addressLine3`	String	3rd line of customer address	no
`dropAddress.zip`	String	Zip/Pin code of customer	yes
`orderDetails`	Object	Order Details	yes
`orderDetails.paymentType`	String	PREPAID / COD	yes
`orderDetails.orderDate`	Date	Order Date	yes
`orderDetails.orderNumber`	String	The order id for which the shipping label is being generated	Yes
`orderDetails.orderAmount`	Double	The total order amount	Yes
`orderDetails.shipmentType`	String	Can be FORWARD or RETURN, based on the order type	yes
`orderDetails.orderLineItemList`	Object[]	Order Line Items	yes
`orderDetails.orderLineItemList.sku`	String	SKU of the product	yes
`orderDetails.orderLineItemList.sellingPricePerUnit`	Double	Selling price of the product	yes
`orderDetails.orderLineItemList.name`	String	Name of the product	yes
`orderDetails.orderLineItemList.quantity`	Integer	Quantity of the product	yes
`shipmentDimension`	Object	Package Dimensions	yes
`shipmentDimension.breadth`	Integer	Breadth of package in cm	yes
`shipmentDimension.height`	Integer	Height of package in cm	yes
`shipmentDimension.length`	Integer	Length of package in cm	yes
`shipmentDimension.weight`	Integer	Weight of package in grams	yes
`warehouseCode`	String	Warehouse Code	no
`courierId`	Integer	Courier Id for which the shipping label is being generated	yes

Response

{
  "orderId": "11012",
  "orderNumber": "asdf1234",
  "awb": "71902671",
  "carrierName": "Delhivery",
  "shippingLabelUrl": "https://shipping-label-pdf.com/asdf1234"
}

Parameter Name	Data Type	Description	Mandatory
`orderId`	String	This is the unique order id with which the logistic aggregator identifies each order	yes
`orderNumber`	String	This is the order number passed in the request body. This is the order number with which RMS uniquely identifies each order	yes
`awb`	String	The tracking number assigned for the order	yes
`carrierName`	String	The carrier of this order	yes
`shippingLabelUrl`	String	The shipping label pdf url	yes

Get Shipping Label API

The field “orderId” returned in the generate shipping label API call will be used as request param to get the shipping label details in this call.

The url will be something like this: {GET_SHIPPING_LABEL_URL}?orderId=11012

Outbound | GET

Response

Same as Generate Shipping Label API call

Generate Return AWB API

Outbound | POST

Request

This is almost the same as the generate shipping label request body.
One additional field is there - returnReason. This is a mandatory field.
The orderNumber passed would be a unique string that is used to uniquely identify each return order.
The shipment type passed would be ‘RETURN’ in this case.

{

“pickupAddress”:{

“firstName”:”Ram”,

“lastName”:”Patel”,

“middleName”:””,

“addressLine1”:”1205, 15th Main Road”,

“addressLine2”:“HSR layout”,

“addressLine3”:””,

“city”:”Bangalore”,

“state”:”Karnataka”,

“zip”:”560102”,

“country”:”India”,

“email”:”abc@gmail.com”,

“phone”:”9999999999”

},

“dropAddress”:{

“firstName”:”Shyam”,

“lastName”:”Sharma”,

“middleName”:””,

“addressLine1”:”A-101, Balaji Residency”,

“addressLine2”:“Stadium road”,

“addressLine3”:”Motera”,

“city”:”Ahmedabad”,

“state”:”Gujarat”,

“zip”:”395007”,

“country”:”India”,

“email”:”abc@gmail.com”,

“phone”:”9999999999”

},

“orderDetails”:{

“orderNumber”:”asdf1234”, //returnOrderNumber

“paymentType”:”PREPAID”,

“orderAmount”:230.00,

“orderDate”:”2022-03-16T12:31:02+05:30”, //returnOrderDate

“shipmentType”:”RETURN”,

“orderLineItems”:[

{

“name”:”jeans”,

“sku”: “sku-1”,

“sellingPricePerUnit”:100.00,

“quantity”:1

},

{

“name”:”t-shirt”,

“sku”:”sku-2”,

“sellingPricePerUnit”:130.00,

“quantity”:1

}

]

},

“shipmentDimension”:{

“length”:50.00,

“breadth”:50.00,

“height”:50.00,

“weight”:200.00

}

“courierId”:1

“warehouseCode”:”wh-1”,

“returnReason”:”Wrong product”

}

Response

{

“orderId”:”11012”,

“orderNumber”:”asdf1234”,

“returnAwb”:”71902671”,

“carrierName”:”Delhivery”

}

Parameter Name	Data Type	Description	Mandatory
`orderId`	String	This is the unique order id with which the logistic aggregator identifies each return order	yes
`orderNumber`	String	This is the return order number passed in the request body. This is the order number with which RMS uniquely identifies each return order	yes
`returnAwb`	String	The tracking number assigned for the return order	yes
`carrierName`	String	The carrier of this return order	yes

Get Return AWB API

Outbound | GET

Response

Same as generate return awb api response

Push Notification API

Inbound | POST | /rms-magic/notification/push

Request

{

“forwardOrderCode”:”asdf1234”,

“forwardAwb”:”12541231”,

“notificationType”:”IN_TRANSIT”,

“shipmentType”:”FORWARD”,

“logisticAggregatorName”:”NARVAR”,

“warehouseCode”:”wh-1”,

“returnOrderInfo”:null,

“items”:[

“sku”:”sku-1”,

“quantity”:1

]

}

Return Notification

{

“forwardOrderId”:”asdf1234”,

“forwardAwb”:”12541231”,

“notificationType”:”RETURN_PICKUP”,

“shipmentType”:”RETURN”,

“logisticAggregatorName”:”NARVAR”,

“warehouseCode”:”wh-1”,

“returnOrderInfo”: {

“returnOrderId”:”return-asdf1234”,

“returnAwb”:”return1235123”,

“carrierName”:”Delhivery Reverse”

},

“lineItems”:[

“sku”:”sku-1”,

“quantity”:1

]

}

Parameter Name	Data Type	Description	Mandatory
`forwardOrderId`	String	This is the unique forward order id with which the logistic aggregator identifies each order	yes
`forwardAwb`	String	This is the tracking number of the forward order	no
`carrierName`	String	This is the carrier who is handling the forward order shipment. This is required when the notification type is of a forward order (IN_TRANSIT,DELIVERED etc.)	no
`notificationType`	String	The notification type for this order that is being pushed	yes
`shipmentType`	String	If the notification being pushed is for the forward order or a return order	yes
`logisticAggregatorName`	String	The logistic aggregator name	yes
`warehouseCode`	String	The warehouse code for this order	no
`returnOrderInfo`	Object	The return order details if the notification is for a return order	no
`returnOrderInfo.returnOrderId`	String	The return order id with which the logistic aggregator identifies the return order	yes
`returnOrderInfo.returnAwb`	String	The return awb of the return order	yes
`returnOrderInfo.carrierName`	String	The carrier of the return order	yes
`lineItems`	List	The list of items for the order whose notification is being sent	yes
`lineItems.sku`	String	The SKU of the item	yes
`lineItems.quantity`	Integer	The quantity of the item	yes

Notification Type list

Notification Type

OUT_FOR_PICKUP

PICKED_UP

OUT_FOR_DELIVERY

FAILED_DELIVERY

DELIVERED

RTO

AWB_GENERATED

CANCELLED

RETURN_ORDER_PLACED

RTO_DELIVERED

EXCHANGE_PICKUP

EXCHANGE_DELIVERED

PICKUP_CANCELLED

SHIPMENT_STUCK

SLA_BREACHED

LOST

DAMAGED

READY_TO_SHIP

PICKUP_SCHEDULED

SHIPPED

UNFULFILLABLE

PICKUP_QUEUE

PICKUP_RESCHEDULED

PICKUP_ERROR

CANCELLATION_REQUESTED

TRANSIT

UNDELIVERED

DELAYED

PARTIAL_DELIVERED

FULFILLED

ARCHIVED

REACHED_DESTINATION_HUB

MISROUTED

RTO_ACKNOWLEDGED