Zone Management Module APIs

The Zone Management Module API is designed to manage and maintain comprehensive zone configurations within the system. This API enables businesses to create, retrieve, and manage zone groups, zone definitions, zone mappings, and zone rules in a structured manner. The system supports different zone types (static, range, rule-based) with tenant-specific assignments and provides comprehensive functionality for managing the complete zone lifecycle while ensuring data consistency and access control across different tenants.

API Documentation

Base URL

# Production
https://apis.prayog.io/gateway/zone-management/api

# Sandbox
https://sandbox-apis.prayog.io/gateway/zone-management/api

Available Endpoints

API Endpoints

1. Create Zone Group

Creates a new zone group to organize related zones.

Endpoint: POST /zone-groups

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Request Body Parameters

Parameter	Required	Type	Description
groupKey	Yes	string	Group key (e.g., courier_zone, delivery_zone)
description	No	string	Group description

Request Body Example

{
  "groupKey": "quick_courier_zones",
  "description": "Zones for quick_courier tenant"
}

Response

{
  "status": "success",
  "message": "Zone group created successfully",
  "data": {
    "id": "67ee7910e0e74a6679a68356",
    "tenantId": "550e8400-e29b-41d4-a716-446655440000",
    "groupKey": "quick_courier_zones",
    "description": "Zones for quick_courier tenant",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

2. Get All Zone Groups

Returns all zone groups for the specified tenant.

Endpoint: GET /zone-groups

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Response

{
  "status": "success",
  "message": "Zone groups retrieved successfully",
  "data": [
    {
      "id": "67ee7910e0e74a6679a68356",
      "tenantId": "550e8400-e29b-41d4-a716-446655440000",
      "groupKey": "quick_courier_zones",
      "description": "Zones for quick_courier tenant",
      "createdAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "67ee7910e0e74a6679a68357",
      "tenantId": "550e8400-e29b-41d4-a716-446655440000",
      "groupKey": "delivery_zone",
      "description": "General delivery zones",
      "createdAt": "2024-01-15T11:00:00.000Z"
    }
  ]
}

3. Get Zone Group by ID

Returns zone group details by ID.

Endpoint: GET /zone-groups/:id

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Path Parameters:

id: Zone group ID (UUID)

Response

{
  "status": "success",
  "message": "Zone group retrieved successfully",
  "data": {
    "id": "67ee7910e0e74a6679a68356",
    "tenantId": "550e8400-e29b-41d4-a716-446655440000",
    "groupKey": "quick_courier_zones",
    "description": "Zones for quick_courier tenant",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

4. Update Zone Group

Updates zone group details.

Endpoint: PATCH /zone-groups/:id

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Request Body Parameters

Parameter	Required	Type	Description
groupKey	No	string	Group key
description	No	string	Group description

Request Body Example

{
  "description": "Updated zones for quick_courier tenant with additional regions"
}

Response

{
  "status": "success",
  "message": "Zone group updated successfully",
  "data": {
    "id": "67ee7910e0e74a6679a68356",
    "tenantId": "550e8400-e29b-41d4-a716-446655440000",
    "groupKey": "quick_courier_zones",
    "description": "Updated zones for quick_courier tenant with additional regions",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

5. Delete Zone Group

Deletes a zone group and all its associated zone definitions.

Endpoint: DELETE /zone-groups/:id

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Path Parameters:

id: Zone group ID (UUID)

Response

{
  "status": "success",
  "message": "Zone group deleted successfully",
  "data": null
}

6. Create Zone Definition

Creates a new zone definition within a zone group.

Endpoint: POST /zone-definitions

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Request Body Parameters

Parameter	Required	Type	Description
groupId	Yes	string	Group ID
zoneCode	Yes	string	Zone code
zoneLabel	No	string	Zone label
identifierType	Yes	string	Identifier type (e.g., pincode, city, distance, weight, location)
zoneType	Yes	enum	Zone type (static, range, rule)

Request Body Example - Static Zone

{
  "groupId": "67ee7910e0e74a6679a68356",
  "zoneCode": "mumbai_central",
  "zoneLabel": "Mumbai Central Zone",
  "identifierType": "pincode",
  "zoneType": "static"
}

Request Body Example - Rule-based Zone

{
  "groupId": "67ee7910e0e74a6679a68356",
  "zoneCode": "local",
  "zoneLabel": "Local (Maharashtra - same city same state)",
  "identifierType": "location",
  "zoneType": "rule"
}

Response

{
  "status": "success",
  "message": "Zone definition created successfully",
  "data": {
    "id": "67ee7910e0e74a6679a68358",
    "groupId": "67ee7910e0e74a6679a68356",
    "zoneCode": "local",
    "zoneLabel": "Local (Maharashtra - same city same state)",
    "identifierType": "location",
    "zoneType": "rule",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

7. Get Zone Definitions by Group

Returns all zone definitions for a specific group.

Endpoint: GET /zone-definitions?groupId=:groupId

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Query Parameters

Parameter	Required	Type	Description
groupId	Yes	string	Group ID

Response

{
  "status": "success",
  "message": "Zone definitions retrieved successfully",
  "data": [
    {
      "id": "67ee7910e0e74a6679a68358",
      "groupId": "67ee7910e0e74a6679a68356",
      "zoneCode": "local",
      "zoneLabel": "Local (Maharashtra - same city same state)",
      "identifierType": "location",
      "zoneType": "rule",
      "createdAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "67ee7910e0e74a6679a68359",
      "groupId": "67ee7910e0e74a6679a68356",
      "zoneCode": "withinState",
      "zoneLabel": "Within State (different city in same state)",
      "identifierType": "location",
      "zoneType": "rule",
      "createdAt": "2024-01-15T10:35:00.000Z"
    }
  ]
}

8. Get Zone Definition by ID

Returns zone definition details by ID.

Endpoint: GET /zone-definitions/:id

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Path Parameters:

id: Zone definition ID (UUID)

Response

{
  "status": "success",
  "message": "Zone definition retrieved successfully",
  "data": {
    "id": "67ee7910e0e74a6679a68358",
    "groupId": "67ee7910e0e74a6679a68356",
    "zoneCode": "local",
    "zoneLabel": "Local (Maharashtra - same city same state)",
    "identifierType": "location",
    "zoneType": "rule",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

9. Update Zone Definition

Updates zone definition details.

Endpoint: PATCH /zone-definitions/:id

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Request Body Parameters

Parameter	Required	Type	Description
zoneCode	No	string	Zone code
zoneLabel	No	string	Zone label
identifierType	No	string	Identifier type
zoneType	No	enum	Zone type (static, range, rule)

Request Body Example

{
  "zoneLabel": "Updated Local Zone (Maharashtra - same city same state)"
}

Response

{
  "status": "success",
  "message": "Zone definition updated successfully",
  "data": {
    "id": "67ee7910e0e74a6679a68358",
    "groupId": "67ee7910e0e74a6679a68356",
    "zoneCode": "local",
    "zoneLabel": "Updated Local Zone (Maharashtra - same city same state)",
    "identifierType": "location",
    "zoneType": "rule",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

10. Delete Zone Definition

Deletes a zone definition and all its mappings.

Endpoint: DELETE /zone-definitions/:id

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Path Parameters:

id: Zone definition ID (UUID)

Response

{
  "status": "success",
  "message": "Zone definition deleted successfully",
  "data": null
}

11. Add Static Mappings

Adds static identifier values (e.g., pincodes, cities) to a zone.

Endpoint: POST /zone-mappings/static

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Request Body Parameters

Parameter	Required	Type	Description
zoneId	Yes	string	Zone ID
identifierValues	Yes	array	Array of identifier values

Request Body Example

{
  "zoneId": "67ee7910e0e74a6679a68358",
  "identifierValues": ["400001", "400002", "400003", "400004", "400005"]
}

Response

{
  "status": "success",
  "message": "Static mappings added successfully",
  "data": {
    "added": 5,
    "skipped": 0,
    "total": 5,
    "conflicts": 0,
    "details": {
      "added": ["400001", "400002", "400003", "400004", "400005"],
      "skipped": [],
      "conflicts": []
    }
  }
}

12. Remove Static Mappings

Removes multiple static mappings from a specific zone.

Endpoint: DELETE /zone-mappings/static

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Request Body Parameters

Parameter	Required	Type	Description
zoneId	Yes	string	Zone ID for verification
mappingIds	Yes	array	Array of mapping IDs to delete

Request Body Example

{
  "zoneId": "67ee7910e0e74a6679a68358",
  "mappingIds": ["mapping-001", "mapping-002", "mapping-003"]
}

Response

{
  "status": "success",
  "message": "Static mappings removed successfully",
  "data": {
    "deleted": 3,
    "total": 3,
    "zoneId": "67ee7910e0e74a6679a68358"
  }
}

13. Add Range Mapping

Adds a range mapping to a zone for numeric values.

Endpoint: POST /zone-mappings/range

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Request Body Parameters

Parameter	Required	Type	Description
zoneId	Yes	string	Zone ID
minValue	Yes	number	Minimum value
maxValue	Yes	number	Maximum value

Request Body Example

{
  "zoneId": "67ee7910e0e74a6679a68360",
  "minValue": 0,
  "maxValue": 5
}

Response

{
  "status": "success",
  "message": "Range mapping added successfully",
  "data": {
    "id": "range-mapping-001",
    "zoneId": "67ee7910e0e74a6679a68360",
    "minValue": 0,
    "maxValue": 5,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

14. Remove Range Mapping

Removes a range mapping by ID.

Endpoint: DELETE /zone-mappings/range/:id

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Path Parameters:

id: Range mapping ID (UUID)

Response

{
  "status": "success",
  "message": "Range mapping removed successfully",
  "data": null
}

15. Get Zone Identifiers

Lists all static and range identifier values mapped to a specific zone with pagination support.

Endpoint: GET /zone-mappings/:zoneId/identifiers

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Query Parameters

Parameter	Required	Type	Description	Default
page	No	number	Page number	1
limit	No	number	Items per page (max: 100)	50
type	No	string	Filter by type (static or range)	-

Example Request:

GET /zone-mappings/67ee7910e0e74a6679a68358/identifiers?page=1&limit=10&type=static

Response

{
  "status": "success",
  "message": "Zone identifier values fetched successfully",
  "data": {
    "zone": {
      "id": "67ee7910e0e74a6679a68358",
      "code": "mumbai_central",
      "label": "Mumbai Central Zone",
      "identifierType": "pincode",
      "zoneType": "static"
    },
    "mappings": [
      {
        "id": "mapping-001",
        "identifierValue": "400001"
      },
      {
        "id": "mapping-002",
        "identifierValue": "400002"
      },
      {
        "id": "mapping-003",
        "identifierValue": "400003"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 25,
      "totalPages": 3,
      "hasNext": true,
      "hasPrev": false
    }
  }
}

16. Create Zone Rule Mapping

Creates a new zone rule mapping or overlay rule.

Endpoint: POST /zone-rule-mappings

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Request Body Parameters

Parameter	Required	Type	Description
zoneId	No	string	Zone ID (required for zone rules, null for overlay rules)
priority	Yes	number	Priority (lower number = higher priority)
ruleExpression	Yes	object	Rule expression in JSON format
isOverlay	No	boolean	Is this an overlay rule?
overlayCode	No	string	Overlay code (required if isOverlay is true)

Request Body Example - Zone Rule

{
  "zoneId": "67ee7910e0e74a6679a68358",
  "priority": 10,
  "ruleExpression": {
    "all": [
      { "eq": ["pickup.country", "IN"] },
      { "eq": ["delivery.country", "IN"] },
      { "eq": ["pickup.state", "MAHARASHTRA"] },
      { "eq": ["delivery.state", "MAHARASHTRA"] },
      { "eqFields": ["pickup.city", "delivery.city"] }
    ]
  },
  "isOverlay": false
}

Request Body Example - Overlay Rule

{
  "priority": 10,
  "ruleExpression": {
    "any": [
      {
        "in": ["delivery.state", ["JAMMU & KASHMIR", "NAGALAND", "ARUNACHAL PRADESH"]]
      },
      { "in": ["delivery.pincode", ["388130", "388131"]] }
    ]
  },
  "isOverlay": true,
  "overlayCode": "ODA"
}

Response

{
  "status": "success",
  "message": "Rule mapping created successfully",
  "data": {
    "id": "rule-mapping-001",
    "zoneId": "67ee7910e0e74a6679a68358",
    "priority": 10,
    "ruleExpression": {
      "all": [
        { "eq": ["pickup.country", "IN"] },
        { "eq": ["delivery.country", "IN"] },
        { "eq": ["pickup.state", "MAHARASHTRA"] },
        { "eq": ["delivery.state", "MAHARASHTRA"] },
        { "eqFields": ["pickup.city", "delivery.city"] }
      ]
    },
    "isOverlay": false,
    "overlayCode": null,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

17. Bulk Create Zone Rule Mappings

Creates multiple zone rule mappings in a single request.

Endpoint: POST /zone-rule-mappings/bulk

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Request Body Parameters

Parameter	Required	Type	Description
zoneRuleMappings	Yes	array	Array of zone rule mappings to create

Request Body Example

{
  "zoneRuleMappings": [
    {
      "zoneId": "67ee7910e0e74a6679a68358",
      "priority": 10,
      "ruleExpression": {
        "all": [
          { "eq": ["pickup.country", "IN"] },
          { "eq": ["delivery.country", "IN"] },
          { "eq": ["pickup.state", "MAHARASHTRA"] },
          { "eq": ["delivery.state", "MAHARASHTRA"] },
          { "eqFields": ["pickup.city", "delivery.city"] }
        ]
      },
      "isOverlay": false
    },
    {
      "zoneId": "67ee7910e0e74a6679a68359",
      "priority": 20,
      "ruleExpression": {
        "all": [
          { "eq": ["pickup.country", "IN"] },
          { "eq": ["delivery.country", "IN"] },
          { "eq": ["pickup.state", "MAHARASHTRA"] },
          { "eq": ["delivery.state", "MAHARASHTRA"] },
          { "eqFields": ["pickup.state", "delivery.state"] },
          { "not": { "eqFields": ["pickup.city", "delivery.city"] } }
        ]
      },
      "isOverlay": false
    }
  ]
}

Response

{
  "status": "success",
  "message": "Rule mappings created successfully",
  "data": [
    {
      "id": "rule-mapping-001",
      "zoneId": "67ee7910e0e74a6679a68358",
      "priority": 10,
      "ruleExpression": {
        "all": [
          { "eq": ["pickup.country", "IN"] },
          { "eq": ["delivery.country", "IN"] },
          { "eq": ["pickup.state", "MAHARASHTRA"] },
          { "eq": ["delivery.state", "MAHARASHTRA"] },
          { "eqFields": ["pickup.city", "delivery.city"] }
        ]
      },
      "isOverlay": false,
      "overlayCode": null,
      "createdAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "rule-mapping-002",
      "zoneId": "67ee7910e0e74a6679a68359",
      "priority": 20,
      "ruleExpression": {
        "all": [
          { "eq": ["pickup.country", "IN"] },
          { "eq": ["delivery.country", "IN"] },
          { "eq": ["pickup.state", "MAHARASHTRA"] },
          { "eq": ["delivery.state", "MAHARASHTRA"] },
          { "eqFields": ["pickup.state", "delivery.state"] },
          { "not": { "eqFields": ["pickup.city", "delivery.city"] } }
        ]
      },
      "isOverlay": false,
      "overlayCode": null,
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

18. Get Zone Rule Mappings

Gets zone rule mappings by zone or overlay rules by tenant.

Endpoint: GET /zone-rule-mappings

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Query Parameters

Parameter	Required	Type	Description
zoneId	No	string	Zone ID (for zone rules)
overlays	No	string	Get overlay rules (true/false)

Example Requests:

GET /zone-rule-mappings?zoneId=67ee7910e0e74a6679a68358
GET /zone-rule-mappings?overlays=true

Response - Zone Rules

{
  "status": "success",
  "message": "Zone rule mappings retrieved successfully",
  "data": [
    {
      "id": "rule-mapping-001",
      "zoneId": "67ee7910e0e74a6679a68358",
      "priority": 10,
      "ruleExpression": {
        "all": [
          { "eq": ["pickup.country", "IN"] },
          { "eq": ["delivery.country", "IN"] },
          { "eq": ["pickup.state", "MAHARASHTRA"] },
          { "eq": ["delivery.state", "MAHARASHTRA"] },
          { "eqFields": ["pickup.city", "delivery.city"] }
        ]
      },
      "isOverlay": false,
      "overlayCode": null,
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Response - Overlay Rules

{
  "status": "success",
  "message": "Overlay rules retrieved successfully",
  "data": [
    {
      "id": "overlay-rule-001",
      "zoneId": null,
      "priority": 10,
      "ruleExpression": {
        "any": [
          {
            "in": ["delivery.state", ["JAMMU & KASHMIR", "NAGALAND", "ARUNACHAL PRADESH"]]
          },
          { "in": ["delivery.pincode", ["388130", "388131"]] }
        ]
      },
      "isOverlay": true,
      "overlayCode": "ODA",
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

19. Update Zone Rule Mapping

Updates zone rule mapping details.

Endpoint: PATCH /zone-rule-mappings/:id

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Request Body Parameters

Parameter	Required	Type	Description
priority	No	number	Priority (lower number = higher priority)
ruleExpression	No	object	Rule expression in JSON format
isOverlay	No	boolean	Is this an overlay rule?
overlayCode	No	string	Overlay code

Request Body Example

{
  "priority": 15,
  "ruleExpression": {
    "all": [
      { "eq": ["pickup.country", "IN"] },
      { "eq": ["delivery.country", "IN"] },
      { "eq": ["pickup.state", "MAHARASHTRA"] },
      { "eq": ["delivery.state", "MAHARASHTRA"] },
      { "eqFields": ["pickup.city", "delivery.city"] }
    ]
  }
}

Response

{
  "status": "success",
  "message": "Rule mapping updated successfully",
  "data": {
    "id": "rule-mapping-001",
    "zoneId": "67ee7910e0e74a6679a68358",
    "priority": 15,
    "ruleExpression": {
      "all": [
        { "eq": ["pickup.country", "IN"] },
        { "eq": ["delivery.country", "IN"] },
        { "eq": ["pickup.state", "MAHARASHTRA"] },
        { "eq": ["delivery.state", "MAHARASHTRA"] },
        { "eqFields": ["pickup.city", "delivery.city"] }
      ]
    },
    "isOverlay": false,
    "overlayCode": null,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

20. Delete Zone Rule Mapping

Deletes a zone rule mapping.

Endpoint: DELETE /zone-rule-mappings/:id

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Path Parameters:

id: Rule mapping ID (UUID)

Response

{
  "status": "success",
  "message": "Rule mapping deleted successfully",
  "data": null
}

21. Resolve Zone

Resolves zones based on static identifiers (pincodes, cities) or range values (distance, weight).

Endpoint: POST /zone-resolution/resolve

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Request Body Parameters

Parameter	Required	Type	Description
resolutionType	Yes	enum	Resolution type (static, range, rule)
identifierType	Yes	string	Identifier type (e.g., pincode, city, distance, weight, location)
input	Yes	string/number/object	Input value for zone resolution

Request Body Example - Static Resolution

{
  "resolutionType": "static",
  "identifierType": "pincode",
  "input": "400001"
}

Request Body Example - Range Resolution

{
  "resolutionType": "range",
  "identifierType": "distance",
  "input": 7.5
}

Request Body Example - Rule Resolution

{
  "resolutionType": "rule",
  "identifierType": "location",
  "input": {
    "pickup": {
      "country": "IN",
      "state": "Maharashtra",
      "city": "Mumbai"
    },
    "delivery": {
      "country": "IN",
      "state": "Maharashtra",
      "city": "Mumbai"
    }
  }
}

Response - Static Resolution

{
  "status": "success",
  "message": "Zone resolved successfully",
  "data": {
    "zoneCode": "mumbai_central",
    "zoneLabel": "Mumbai Central Zone",
    "resolutionType": "static",
    "matchedValue": "400001",
    "metadata": {
      "identifierType": "pincode"
    }
  }
}

Response - Range Resolution

{
  "status": "success",
  "message": "Zone resolved successfully",
  "data": {
    "zoneCode": "local_zone",
    "zoneLabel": "Local Delivery Zone",
    "resolutionType": "range",
    "matchedValue": 7.5,
    "metadata": {
      "identifierType": "distance",
      "range": {
        "min": 0,
        "max": 10
      }
    }
  }
}

Response - Rule Resolution with Overlays

{
  "status": "success",
  "message": "Zone resolved successfully",
  "data": {
    "zoneCode": "local",
    "zoneLabel": "Local (Maharashtra - same city same state)",
    "resolutionType": "rule",
    "matchedValue": {
      "pickup": {
        "country": "IN",
        "state": "Maharashtra",
        "city": "Mumbai"
      },
      "delivery": {
        "country": "IN",
        "state": "Maharashtra",
        "city": "Mumbai"
      }
    },
    "metadata": {
      "identifierType": "location",
      "ruleMatched": "pickup.country == 'IN' AND delivery.country == 'IN' AND pickup.state == 'MAHARASHTRA' AND delivery.state == 'MAHARASHTRA' AND pickup.city == delivery.city"
    },
    "overlays": [
      {
        "overlayCode": "ODA",
        "overlayLabel": "ODA Overlay",
        "reason": "Special location detected",
        "ruleMatched": "delivery.state in ['JAMMU & KASHMIR', 'NAGALAND', 'ARUNACHAL PRADESH']"
      }
    ]
  }
}

Error Codes

Error Code	Title	Description
400	Bad Request	The request payload is invalid or missing required fields.
401	Unauthorized	Authentication token is missing or invalid.
403	Forbidden	The authenticated user does not have permission to access this resource.
404	Not Found	The requested resource does not exist.
409	Conflict	The request conflicts with the current state of the server.
429	Too Many Requests	Rate limit exceeded. Please try again later.
500	Internal Server Error	An unexpected error occurred on the server.

Data Models

Zone Group

id: Unique identifier for the zone group
tenantId: Tenant ID associated with the zone group
groupKey: Group key (e.g., courier_zone, delivery_zone)
description: Group description
createdAt: Creation timestamp

Zone Definition

id: Unique identifier for the zone definition
groupId: Group ID this zone belongs to
zoneCode: Zone code identifier
zoneLabel: Human-readable zone label
identifierType: Type of identifier (pincode, city, distance, weight, location)
zoneType: Zone type (static, range, rule)
createdAt: Creation timestamp

Zone Static Mapping

id: Unique identifier for the static mapping
zoneId: Zone ID this mapping belongs to
identifierValue: Static identifier value (e.g., pincode, city name)
createdAt: Creation timestamp

Zone Range Mapping

id: Unique identifier for the range mapping
zoneId: Zone ID this mapping belongs to
minValue: Minimum value for the range
maxValue: Maximum value for the range
createdAt: Creation timestamp

Zone Rule Mapping

id: Unique identifier for the rule mapping
zoneId: Zone ID (null for overlay rules)
priority: Priority (lower number = higher priority)
ruleExpression: Rule expression in JSON format
isOverlay: Whether this is an overlay rule
overlayCode: Overlay code (for overlay rules)
createdAt: Creation timestamp

Zone Resolution Response

zoneCode: Resolved zone code
zoneLabel: Resolved zone label
resolutionType: Type of resolution (static, range, rule)
matchedValue: The input value that was matched
metadata: Additional metadata about the resolution
overlays: Array of overlay information (if applicable)

Important Notes

X-Tenant-Id Header: All endpoints require the X-Tenant-Id header with a valid UUID. This is mandatory for all requests.
Zone Types: The system supports three types of zones:
- Static: Based on specific identifier values (pincodes, cities)
- Range: Based on numeric ranges (distance, weight)
- Rule: Based on complex rule expressions
Rule Expressions: Rule expressions use JSON format with logical operators (all, any, not) and comparison operators (eq, in, eqFields).
Overlay Rules: Overlay rules are tenant-wide rules that can apply additional logic on top of zone resolution.
Priority System: Rule mappings use a priority system where lower numbers have higher priority.
Pagination: The zone identifiers endpoint supports pagination with configurable page size (max 100 items per page).
Cascade Deletion: Deleting a zone group will cascade delete all associated zone definitions and mappings.
Conflict Handling: When adding static mappings, the system reports conflicts if identifiers are already mapped to other zones.

Example Usage

Below are examples of how to use the Zone Management API with cURL.

Create a Complete Zone Setup

Step 1: Create Zone Group

curl --location 'https://apis.prayog.io/gateway/zone-management/api/zone-groups' \
--header 'X-Tenant-Id: 550e8400-e29b-41d4-a716-446655440000' \
--header 'Content-Type: application/json' \
--data '{
  "groupKey": "quick_courier_zones",
  "description": "Zones for quick_courier tenant"
}'

Response:

{
  "status": "success",
  "message": "Zone group created successfully",
  "data": {
    "id": "67ee7910e0e74a6679a68356",
    "tenantId": "550e8400-e29b-41d4-a716-446655440000",
    "groupKey": "quick_courier_zones",
    "description": "Zones for quick_courier tenant",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Step 2: Create Zone Definitions

curl --location 'https://apis.prayog.io/gateway/zone-management/api/zone-definitions' \
--header 'X-Tenant-Id: 550e8400-e29b-41d4-a716-446655440000' \
--header 'Content-Type: application/json' \
--data '{
  "groupId": "67ee7910e0e74a6679a68356",
  "zoneCode": "local",
  "zoneLabel": "Local (Maharashtra - same city same state)",
  "identifierType": "location",
  "zoneType": "rule"
}'

Response:

{
  "status": "success",
  "message": "Zone definition created successfully",
  "data": {
    "id": "67ee7910e0e74a6679a68358",
    "groupId": "67ee7910e0e74a6679a68356",
    "zoneCode": "local",
    "zoneLabel": "Local (Maharashtra - same city same state)",
    "identifierType": "location",
    "zoneType": "rule",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Step 3: Add Static Mappings

curl --location 'https://apis.prayog.io/gateway/zone-management/api/zone-mappings/static' \
--header 'X-Tenant-Id: 550e8400-e29b-41d4-a716-446655440000' \
--header 'Content-Type: application/json' \
--data '{
  "zoneId": "67ee7910e0e74a6679a68358",
  "identifierValues": ["400001", "400002", "400003", "400004", "400005"]
}'

Response:

{
  "status": "success",
  "message": "Static mappings added successfully",
  "data": {
    "added": 5,
    "skipped": 0,
    "total": 5,
    "conflicts": 0,
    "details": {
      "added": ["400001", "400002", "400003", "400004", "400005"],
      "skipped": [],
      "conflicts": []
    }
  }
}

Step 4: Create Rule Mapping

curl --location 'https://apis.prayog.io/gateway/zone-management/api/zone-rule-mappings' \
--header 'X-Tenant-Id: 550e8400-e29b-41d4-a716-446655440000' \
--header 'Content-Type: application/json' \
--data '{
  "zoneId": "67ee7910e0e74a6679a68358",
  "priority": 10,
  "ruleExpression": {
    "all": [
      { "eq": ["pickup.country", "IN"] },
      { "eq": ["delivery.country", "IN"] },
      { "eq": ["pickup.state", "MAHARASHTRA"] },
      { "eq": ["delivery.state", "MAHARASHTRA"] },
      { "eqFields": ["pickup.city", "delivery.city"] }
    ]
  },
  "isOverlay": false
}'

Response:

{
  "status": "success",
  "message": "Rule mapping created successfully",
  "data": {
    "id": "rule-mapping-001",
    "zoneId": "67ee7910e0e74a6679a68358",
    "priority": 10,
    "ruleExpression": {
      "all": [
        { "eq": ["pickup.country", "IN"] },
        { "eq": ["delivery.country", "IN"] },
        { "eq": ["pickup.state", "MAHARASHTRA"] },
        { "eq": ["delivery.state", "MAHARASHTRA"] },
        { "eqFields": ["pickup.city", "delivery.city"] }
      ]
    },
    "isOverlay": false,
    "overlayCode": null,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Step 5: Resolve Zone

curl --location 'https://apis.prayog.io/gateway/zone-management/api/zone-resolution/resolve' \
--header 'X-Tenant-Id: 550e8400-e29b-41d4-a716-446655440000' \
--header 'Content-Type: application/json' \
--data '{
  "resolutionType": "static",
  "identifierType": "pincode",
  "input": "400001"
}'

Response:

{
  "status": "success",
  "message": "Zone resolved successfully",
  "data": {
    "zoneCode": "mumbai_central",
    "zoneLabel": "Mumbai Central Zone",
    "resolutionType": "static",
    "matchedValue": "400001",
    "metadata": {
      "identifierType": "pincode"
    }
  }
}

Resolve Zone with Rule-based Resolution

Rule-based Zone Resolution

curl --location 'https://apis.prayog.io/gateway/zone-management/api/zone-resolution/resolve' \
--header 'X-Tenant-Id: 550e8400-e29b-41d4-a716-446655440000' \
--header 'Content-Type: application/json' \
--data '{
  "resolutionType": "rule",
  "identifierType": "location",
  "input": {
    "pickup": {
      "country": "IN",
      "state": "Maharashtra",
      "city": "Mumbai"
    },
    "delivery": {
      "country": "IN",
      "state": "Maharashtra",
      "city": "Mumbai"
    }
  }
}'

Response:

{
  "status": "success",
  "message": "Zone resolved successfully",
  "data": {
    "zoneCode": "local",
    "zoneLabel": "Local (Maharashtra - same city same state)",
    "resolutionType": "rule",
    "matchedValue": {
      "pickup": {
        "country": "IN",
        "state": "Maharashtra",
        "city": "Mumbai"
      },
      "delivery": {
        "country": "IN",
        "state": "Maharashtra",
        "city": "Mumbai"
      }
    },
    "metadata": {
      "identifierType": "location",
      "ruleMatched": "pickup.country == 'IN' AND delivery.country == 'IN' AND pickup.state == 'MAHARASHTRA' AND delivery.state == 'MAHARASHTRA' AND pickup.city == delivery.city"
    },
    "overlays": [
      {
        "overlayCode": "ODA",
        "overlayLabel": "ODA Overlay",
        "reason": "Special location detected",
        "ruleMatched": "delivery.state in ['JAMMU & KASHMIR', 'NAGALAND', 'ARUNACHAL PRADESH']"
      }
    ]
  }
}

Get Zone Identifiers with Pagination

Get Zone Identifiers

curl --location 'https://apis.prayog.io/gateway/zone-management/api/zone-mappings/67ee7910e0e74a6679a68358/identifiers?page=1&limit=10&type=static' \
--header 'X-Tenant-Id: 550e8400-e29b-41d4-a716-446655440000'

Response:

{
  "status": "success",
  "message": "Zone identifier values fetched successfully",
  "data": {
    "zone": {
      "id": "67ee7910e0e74a6679a68358",
      "code": "mumbai_central",
      "label": "Mumbai Central Zone",
      "identifierType": "pincode",
      "zoneType": "static"
    },
    "mappings": [
      {
        "id": "mapping-001",
        "identifierValue": "400001"
      },
      {
        "id": "mapping-002",
        "identifierValue": "400002"
      },
      {
        "id": "mapping-003",
        "identifierValue": "400003"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 25,
      "totalPages": 3,
      "hasNext": true,
      "hasPrev": false
    }
  }
}

Understanding Zone Management Concepts

Zone Types Explained

1. Static Zones 📍

What it is: Zones based on specific identifier values like pincodes, city names, or other discrete identifiers.

Real Examples:

Pincode-based: 400001, 400002, 400003 → Mumbai Central Zone
City-based: Mumbai, Pune, Delhi → Metro Zone
Area-based: Bandra, Andheri, Powai → Mumbai Suburban Zone

When to use: When you have specific, known locations that should map to zones.

Configuration Example:

{
  "zoneCode": "mumbai_central",
  "zoneLabel": "Mumbai Central Zone",
  "identifierType": "pincode",
  "zoneType": "static"
}

2. Range Zones 🚗

What it is: Zones based on numeric ranges for continuous values like distance, weight, or time.

Real Examples:

Distance-based: 0-5km → Local Zone, 5-15km → Metro Zone
Weight-based: 0-1kg → Light Zone, 1-5kg → Standard Zone
Time-based: 0-24hrs → Same Day, 24-48hrs → Next Day

When to use: When you need to categorize based on measurable ranges.

Configuration Example:

{
  "zoneCode": "local_zone",
  "zoneLabel": "Local Delivery Zone",
  "identifierType": "distance",
  "zoneType": "range",
  "minValue": 0,
  "maxValue": 5
}

3. Rule-based Zones 📜

What it is: Zones based on complex rule expressions that can evaluate multiple conditions.

Real Examples:

Weight + Distance: Weight >= 5kg AND Distance <= 10km → Heavy Local Zone
Service Type + Holiday: ServiceType == “express” AND IsHoliday == true → Holiday Express Zone
Time + Location: Time >= “09:00” AND Location == “metro” → Business Hours Metro Zone

When to use: When you need complex logic that combines multiple factors.

Configuration Example:

{
  "zoneCode": "heavy_local_zone",
  "zoneLabel": "Heavy Local Zone",
  "identifierType": "weight",
  "zoneType": "rule",
  "ruleExpression": {
    "field": "weight",
    "operator": ">",
    "value": 5
  }
}

Overlay Rules Explained

What it is: Additional rules that can be applied on top of zone resolution to provide extra context or modifications.

Real Examples:

Holiday Surcharge: Apply additional charges during holidays
Express Service: Modify delivery time for express services
Weather Conditions: Adjust zones based on weather alerts
Peak Hours: Apply different rates during peak delivery hours

Configuration Example:

{
  "priority": 1,
  "ruleExpression": {
    "and": [
      {
        "field": "isHoliday",
        "operator": "==",
        "value": true
      },
      {
        "field": "serviceType",
        "operator": "==",
        "value": "express"
      }
    ]
  },
  "isOverlay": true,
  "overlayCode": "holiday_express_surcharge"
}

Rule Expression Syntax

Logical Operators

AND: All conditions must be true
OR: At least one condition must be true
NOT: Negates a condition

Comparison Operators

==: Equals
!=: Not equals
>: Greater than
<: Less than
>=: Greater than or equal
<=: Less than or equal

Example Rule Expressions

Simple Condition:

{
  "field": "weight",
  "operator": ">=",
  "value": 5
}

Complex AND Condition:

{
  "and": [
    {
      "field": "weight",
      "operator": ">=",
      "value": 5
    },
    {
      "field": "distance",
      "operator": "<=",
      "value": 10
    },
    {
      "field": "serviceType",
      "operator": "==",
      "value": "express"
    }
  ]
}

Complex OR Condition:

{
  "or": [
    {
      "field": "isHoliday",
      "operator": "==",
      "value": true
    },
    {
      "field": "isWeekend",
      "operator": "==",
      "value": true
    }
  ]
}

Nested Conditions:

{
  "and": [
    {
      "field": "weight",
      "operator": ">=",
      "value": 5
    },
    {
      "or": [
        {
          "field": "isHoliday",
          "operator": "==",
          "value": true
        },
        {
          "field": "isWeekend",
          "operator": "==",
          "value": true
        }
      ]
    }
  ]
}

Zone Resolution Process

Step-by-Step Resolution:

Input Validation: Validate the input parameters and resolution type
Static Resolution: Check if input matches any static identifier values
Range Resolution: Check if input falls within any range mappings
Rule Resolution: Evaluate rule expressions against the input
Overlay Application: Apply any matching overlay rules
Result Compilation: Combine all results and return the final zone

Resolution Priority:

Static (highest priority)
Range (medium priority)
Rule (lowest priority)
Overlay (applied on top of any match)

Common Use Cases

1. E-commerce Delivery Zones

{
  "groupKey": "delivery_zone",
  "zones": [
    {
      "zoneCode": "mumbai_central",
      "zoneType": "static",
      "identifierType": "pincode",
      "mappings": ["400001", "400002", "400003"]
    },
    {
      "zoneCode": "mumbai_suburban",
      "zoneType": "static",
      "identifierType": "pincode",
      "mappings": ["400050", "400051", "400052"]
    },
    {
      "zoneCode": "local_delivery",
      "zoneType": "range",
      "identifierType": "distance",
      "minValue": 0,
      "maxValue": 5
    }
  ]
}

2. Logistics Weight-based Zones

{
  "groupKey": "logistics_zone",
  "zones": [
    {
      "zoneCode": "light_zone",
      "zoneType": "range",
      "identifierType": "weight",
      "minValue": 0,
      "maxValue": 1
    },
    {
      "zoneCode": "standard_zone",
      "zoneType": "range",
      "identifierType": "weight",
      "minValue": 1,
      "maxValue": 5
    },
    {
      "zoneCode": "heavy_zone",
      "zoneType": "rule",
      "identifierType": "weight",
      "ruleExpression": {
        "field": "weight",
        "operator": ">",
        "value": 5
      }
    }
  ]
}

3. Service-based Zones with Overlays

{
  "groupKey": "service_zone",
  "zones": [
    {
      "zoneCode": "standard_service",
      "zoneType": "rule",
      "identifierType": "serviceType",
      "ruleExpression": {
        "field": "serviceType",
        "operator": "==",
        "value": "standard"
      }
    }
  ],
  "overlays": [
    {
      "overlayCode": "holiday_surcharge",
      "ruleExpression": {
        "field": "isHoliday",
        "operator": "==",
        "value": true
      }
    },
    {
      "overlayCode": "express_premium",
      "ruleExpression": {
        "field": "serviceType",
        "operator": "==",
        "value": "express"
      }
    }
  ]
}

Best Practices

1. Zone Group Organization

Use descriptive group keys (e.g., courier_zone, delivery_zone)
Group related zones together
Use consistent naming conventions

2. Zone Definition

Use clear, descriptive zone codes
Provide meaningful zone labels
Choose appropriate identifier types
Select the right zone type for your use case

3. Rule Expressions

Keep rules simple and readable
Use appropriate logical operators
Test rules thoroughly
Document complex rule logic

4. Performance Considerations

Use static zones for frequently accessed data
Optimize rule expressions for performance
Consider caching for complex rule evaluations
Use pagination for large mapping lists

5. Error Handling

Always validate input parameters
Handle edge cases in rule expressions
Provide meaningful error messages
Log resolution attempts for debugging

Troubleshooting Common Issues

1. Zone Not Resolving

Check if the input matches the identifier type
Verify the zone is active and properly configured
Ensure the resolution type is correct
Check for typos in static mappings

2. Rule Not Matching

Verify the rule expression syntax
Check field names and operators
Test with sample data
Review rule priority settings

3. Overlay Not Applying

Ensure overlay rules are properly configured
Check overlay rule conditions
Verify overlay code is correct
Review overlay priority settings

4. Performance Issues

Optimize rule expressions
Use static zones where possible
Implement caching strategies
Monitor resolution times

Missing API Endpoints

I notice there are some missing API endpoints in the current documentation. Let me add the missing ones:

16. Create Zone Rule Mapping

Creates a new zone rule mapping or overlay rule.

Endpoint: POST /zone-rule-mappings

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Request Body Parameters

Parameter	Required	Type	Description
zoneId	No	string	Zone ID (required for zone rules, null for overlay rules)
priority	Yes	number	Priority (lower number = higher priority)
ruleExpression	Yes	object	Rule expression in JSON format
isOverlay	No	boolean	Is this an overlay rule?
overlayCode	No	string	Overlay code (required if isOverlay is true)

Request Body Example - Zone Rule

{
  "zoneId": "67ee7910e0e74a6679a68358",
  "priority": 10,
  "ruleExpression": {
    "all": [
      { "eq": ["pickup.country", "IN"] },
      { "eq": ["delivery.country", "IN"] },
      { "eq": ["pickup.state", "MAHARASHTRA"] },
      { "eq": ["delivery.state", "MAHARASHTRA"] },
      { "eqFields": ["pickup.city", "delivery.city"] }
    ]
  },
  "isOverlay": false
}

Request Body Example - Overlay Rule

{
  "priority": 10,
  "ruleExpression": {
    "any": [
      {
        "in": ["delivery.state", ["JAMMU & KASHMIR", "NAGALAND", "ARUNACHAL PRADESH"]]
      },
      { "in": ["delivery.pincode", ["388130", "388131"]] }
    ]
  },
  "isOverlay": true,
  "overlayCode": "ODA"
}

Response

{
  "status": "success",
  "message": "Rule mapping created successfully",
  "data": {
    "id": "rule-mapping-001",
    "zoneId": "67ee7910e0e74a6679a68358",
    "priority": 10,
    "ruleExpression": {
      "all": [
        { "eq": ["pickup.country", "IN"] },
        { "eq": ["delivery.country", "IN"] },
        { "eq": ["pickup.state", "MAHARASHTRA"] },
        { "eq": ["delivery.state", "MAHARASHTRA"] },
        { "eqFields": ["pickup.city", "delivery.city"] }
      ]
    },
    "isOverlay": false,
    "overlayCode": null,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

17. Bulk Create Zone Rule Mappings

Creates multiple zone rule mappings in a single request.

Endpoint: POST /zone-rule-mappings/bulk

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Request Body Parameters

Parameter	Required	Type	Description
zoneRuleMappings	Yes	array	Array of zone rule mappings to create

Request Body Example

{
  "zoneRuleMappings": [
    {
      "zoneId": "67ee7910e0e74a6679a68358",
      "priority": 10,
      "ruleExpression": {
        "all": [
          { "eq": ["pickup.country", "IN"] },
          { "eq": ["delivery.country", "IN"] },
          { "eq": ["pickup.state", "MAHARASHTRA"] },
          { "eq": ["delivery.state", "MAHARASHTRA"] },
          { "eqFields": ["pickup.city", "delivery.city"] }
        ]
      },
      "isOverlay": false
    },
    {
      "zoneId": "67ee7910e0e74a6679a68359",
      "priority": 20,
      "ruleExpression": {
        "all": [
          { "eq": ["pickup.country", "IN"] },
          { "eq": ["delivery.country", "IN"] },
          { "eq": ["pickup.state", "MAHARASHTRA"] },
          { "eq": ["delivery.state", "MAHARASHTRA"] },
          { "eqFields": ["pickup.state", "delivery.state"] },
          { "not": { "eqFields": ["pickup.city", "delivery.city"] } }
        ]
      },
      "isOverlay": false
    }
  ]
}

Response

{
  "status": "success",
  "message": "Rule mappings created successfully",
  "data": [
    {
      "id": "rule-mapping-001",
      "zoneId": "67ee7910e0e74a6679a68358",
      "priority": 10,
      "ruleExpression": {
        "all": [
          { "eq": ["pickup.country", "IN"] },
          { "eq": ["delivery.country", "IN"] },
          { "eq": ["pickup.state", "MAHARASHTRA"] },
          { "eq": ["delivery.state", "MAHARASHTRA"] },
          { "eqFields": ["pickup.city", "delivery.city"] }
        ]
      },
      "isOverlay": false,
      "overlayCode": null,
      "createdAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "rule-mapping-002",
      "zoneId": "67ee7910e0e74a6679a68359",
      "priority": 20,
      "ruleExpression": {
        "all": [
          { "eq": ["pickup.country", "IN"] },
          { "eq": ["delivery.country", "IN"] },
          { "eq": ["pickup.state", "MAHARASHTRA"] },
          { "eq": ["delivery.state", "MAHARASHTRA"] },
          { "eqFields": ["pickup.state", "delivery.state"] },
          { "not": { "eqFields": ["pickup.city", "delivery.city"] } }
        ]
      },
      "isOverlay": false,
      "overlayCode": null,
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

18. Get Zone Rule Mappings

Gets zone rule mappings by zone or overlay rules by tenant.

Endpoint: GET /zone-rule-mappings

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "550e8400-e29b-41d4-a716-446655440000"
}

Query Parameters

Parameter	Required	Type	Description
zoneId	No	string	Zone ID (for zone rules)
overlays	No	string	Get overlay rules (true/false)

Example Requests:

GET /zone-rule-mappings?zoneId=67ee7910e0e74a6679a68358
GET /zone-rule-mappings?overlays=true

Response - Zone Rules

{
  "status": "success",
  "message": "Zone rule mappings retrieved successfully",
  "data": [
    {
      "id": "rule-mapping-001",
      "zoneId": "67ee7910e0e74a6679a68358",
      "priority": 10,
      "ruleExpression": {
        "all": [
          { "eq": ["pickup.country", "IN"] },
          { "eq": ["delivery.country", "IN"] },
          { "eq": ["pickup.state", "MAHARASHTRA"] },
          { "eq": ["delivery.state", "MAHARASHTRA"] },
          { "eqFields": ["pickup.city", "delivery.city"] }
        ]
      },
      "isOverlay": false,
      "overlayCode": null,
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Response - Overlay Rules

{
  "status": "success",
  "message": "Overlay rules retrieved successfully",
  "data": [
    {
      "id": "overlay-rule-001",
      "zoneId": null,
      "priority": 10,
      "ruleExpression": {
        "any": [
          {
            "in": ["delivery.state", ["JAMMU & KASHMIR", "NAGALAND", "ARUNACHAL PRADESH"]]
          },
          { "in": ["delivery.pincode", ["388130", "388131"]] }
        ]
      },
      "isOverlay": true,
      "overlayCode": "ODA",
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

This comprehensive API documentation now covers all the exposed Swagger endpoints in your Zone Management Service, following the same format and structure as your sample documentation. The documentation includes detailed examples, error handling, data models, and practical usage scenarios to help developers understand and implement the zone management functionality effectively.

Zone Management Module APIs

API Documentation

Base URL

Available Endpoints

Zone Groups

Zone Definitions

Zone Mappings

Zone Rule Mappings

Zone Resolution

API Endpoints

1. Create Zone Group

Request Body Parameters

2. Get All Zone Groups

3. Get Zone Group by ID

4. Update Zone Group

Request Body Parameters

5. Delete Zone Group

6. Create Zone Definition

Request Body Parameters

7. Get Zone Definitions by Group

Query Parameters

8. Get Zone Definition by ID

9. Update Zone Definition

Request Body Parameters

10. Delete Zone Definition

11. Add Static Mappings

Request Body Parameters

12. Remove Static Mappings

Request Body Parameters

13. Add Range Mapping

Request Body Parameters

14. Remove Range Mapping

15. Get Zone Identifiers

Query Parameters

16. Create Zone Rule Mapping

Request Body Parameters

17. Bulk Create Zone Rule Mappings

Request Body Parameters

18. Get Zone Rule Mappings

Query Parameters

19. Update Zone Rule Mapping

Request Body Parameters

20. Delete Zone Rule Mapping

21. Resolve Zone

Request Body Parameters

Error Codes

Data Models

Zone Group

Zone Definition

Zone Static Mapping

Zone Range Mapping

Zone Rule Mapping

Zone Resolution Response

Important Notes

Example Usage

Create a Complete Zone Setup

Resolve Zone with Rule-based Resolution

Get Zone Identifiers with Pagination

Understanding Zone Management Concepts

Zone Types Explained

1. Static Zones 📍

2. Range Zones 🚗

3. Rule-based Zones 📜

Overlay Rules Explained

Rule Expression Syntax

Logical Operators

Comparison Operators

Example Rule Expressions

Zone Resolution Process

Step-by-Step Resolution:

Resolution Priority:

Common Use Cases

1. E-commerce Delivery Zones

2. Logistics Weight-based Zones

3. Service-based Zones with Overlays

Best Practices

1. Zone Group Organization

2. Zone Definition

3. Rule Expressions

4. Performance Considerations