Onboarding Pincode

The Service provides APIs for managing partners and their location coverage data. This service enables the creation and management of partners and their serviceable areas.

Base URL

For Serviceability Service:

# Production
https://apis.prayog.io/serviceability/v1

# Sandbox
https://sandbox-apis.prayog.io/serviceability/v1

For Partner Service:

# Production
https://apis.prayog.io/partner/v1

# Sandbox
https://sandbox-apis.prayog.io/partner/v1

Available Endpoints

• POST /partners
• GET /partners
• POST /partners/{partner_id}/location-coverages

API Endpoints

1. Create Partner (POST)

Creates a new partner in the system.

Endpoint

POST /partners

Request Body

Field	Type	Required	Description
code	string	Yes	Unique partner code (snake_case format)
name	string	Yes	Partner name (title case format)
partner_type_code	string	Yes	Type of partner (e.g., “direct”, “aggregator”)
global_rating	number	Yes	Global rating (1-5)
global_priority	number	Yes	Global priority (1-5)
parent_id	string	No	ID of parent partner (for aggregator partners)

Example Request

curl --request POST \
  --url https://apis.prayog.io/partner/v1/partners/ \
  --header 'content-type: application/json' \
  --data '{
    "code": "beacon_movers",
    "name": "Beacon Movers",
    "partner_type_code": "direct",
    "global_rating": 3,
    "global_priority": 3
  }'

Success Response (201 Created)

{
  "id": "7904de1b-2ba0-46c5-bb8c-394a5f2f0f40",
  "code": "beacon_movers",
  "name": "Beacon Movers",
  "partner_type_code": "direct",
  "global_rating": 3,
  "global_priority": 3
}

Error Response (409 Conflict)

{
  "error": {
    "code": "PARTNER_ALREADY_EXISTS",
    "message": "Partner with this code already exists"
  }
}

---

2. List Partners (GET)

Retrieves a list of partners with pagination support.

Endpoint

GET /partners

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
limit	integer	No	Items per page (default: 100)
partner_type_code	string	No	Filter by partner type (e.g., “aggregator”)

Example Request

curl --request GET \
  --url 'https://apis.prayog.io/partner/v1/partners?partner_type_code=aggregator'

Success Response (200 OK)

{
  "data": [
    {
      "id": "partner_id",
      "code": "partner_name",
      "name": "Partner Name",
      "partner_type_code": "aggregator",
      "global_rating": 3,
      "global_priority": 3
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 100
}

---

3. Create Partner Location Coverage (POST)

Creates location coverage for a partner, defining their serviceable areas.

Endpoint

POST /partners/{partner_id}/location-coverages

Path Parameters

Parameter	Type	Required	Description
partner_id	string	Yes	ID of the partner

Request Body

Field	Type	Required	Description
postal_code	string	Yes	Postal code for coverage
tat_days	integer	Yes	Turnaround time in days
delivery_mode	string	Yes	Delivery mode (“air” or “surface”)
country_code	string	Yes	Country code (e.g., “in”)
product_type	string	Yes	Product type (e.g., “travel_free”)
parcel_category_code	string	Yes	Category code (e.g., “ecomm”)
pickup	boolean	Yes	Whether pickup is available
delivery	boolean	Yes	Whether delivery is available
cod_available	boolean	Yes	Whether COD is available
insurance	boolean	Yes	Whether insurance is available

Example Request

curl --request POST \
  --url https://apis.prayog.io/serviceability/v1/partners/be9fdb7c-3767-4a3f-854a-037fb745916a/location-coverages \
  --header 'content-type: application/json' \
  --data '{
    "postal_code": "713333",
    "tat_days": 4,
    "delivery_mode": "air",
    "country_code": "in",
    "product_type": "travel_free",
    "parcel_category_code": "ecomm",
    "pickup": true,
    "delivery": true,
    "cod_available": true,
    "insurance": false
  }'

Success Response (201 Created)

{
  "id": "coverage_id",
  "postal_code": "713333",
  "tat_days": 4,
  "delivery_mode": "air",
  "country_code": "in",
  "product_type": "travel_free",
  "parcel_category_code": "ecomm",
  "pickup": true,
  "delivery": true,
  "cod_available": true,
  "insurance": false
}

Error Response (409 Conflict)

{
  "error": {
    "code": "COVERAGE_ALREADY_EXISTS",
    "message": "Location coverage already exists for this partner and postal code"
  }
}

---

Error Codes

Code	HTTP Status	Description
INVALID_REQUEST	400	Invalid request format or missing required fields
PARTNER_NOT_FOUND	404	Partner not found
PARTNER_ALREADY_EXISTS	409	Partner with this code already exists
COVERAGE_ALREADY_EXISTS	409	Location coverage already exists
INTERNAL_SERVER_ERROR	500	Internal server error

---

Best Practices

1. Partner Creation

   • Use snake_case for partner codes
   • Use title case for partner names
   • Set appropriate global rating and priority (1-5)
   • Specify parent_id for aggregator partners

2. Location Coverage

   • Create separate entries for air and surface modes
   • Ensure postal codes are valid
   • Set appropriate TAT days based on delivery mode
   • Configure pickup and delivery availability accurately
   • Specify correct product_type and parcel_category_code

3. Error Handling

   • Implement retry logic for failed requests
   • Handle 409 Conflict responses appropriately
   • Validate input data before making API calls

4. Rate Limiting

   • Add delays between API calls to avoid rate limiting
   • Implement exponential backoff for retries
   • Monitor API response times and adjust accordingly