Integrating with RMS for a Logistics Aggregator

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"
}

Response

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

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”

}

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

  ]

}

Notification Type list