Skip to main content

​
Zones API

The Zones API provides CRUD operations for managing geographical zones (zonas), which are used to group and organize units by location or region.

​
Endpoints

​
Get All Zones

Retrieves a list of all zones in the organization. 
curl -X GET "https://api.integra.com/zonas" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Request

Method: GET Endpoint: /zonas Headers:
  • Authorization: Bearer token (required)

​
Response

Status Code: 200 OK
Response Example
{
  "data": [
    {
      "id": 1,
      "nombre": "Zona Norte",
      "activo": true
    },
    {
      "id": 2,
      "nombre": "Zona Sur",
      "activo": true
    },
    {
      "id": 3,
      "nombre": "Zona Centro",
      "activo": false
    }
  ],
  "message": "Zonas"
}

​
Create Zone

Registers a new geographical zone. 
curl -X POST "https://api.integra.com/zonas" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Zona Este"
  }'

​
Request

Method: POST Endpoint: /zonas Headers:
  • Authorization: Bearer token (required)
  • Content-Type: application/json (required)
Body Parameters:
FieldTypeRequiredDescription
nombreStringYesName of the zone (cannot be blank)

​
Response

Status Code: 200 OK
Response Example
{
  "data": true,
  "message": "Zona registrada"
}

​
Update Zone

Updates an existing zone, including its name and active status. 
curl -X PUT "https://api.integra.com/zonas" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "nombre": "Zona Norte Actualizada",
    "activo": true
  }'

​
Request

Method: PUT Endpoint: /zonas Headers:
  • Authorization: Bearer token (required)
  • Content-Type: application/json (required)
Body Parameters:
FieldTypeRequiredDescription
idIntegerYesID of the zone to update
nombreStringYesUpdated name of the zone (cannot be blank)
activoBooleanYesActive status of the zone

​
Response

Status Code: 200 OK
Response Example
{
  "data": true,
  "message": "Zona actualizada"
}

​
Delete Zone

Permanently deletes a zone from the system.
Deleting a zone is a permanent operation. Ensure that no units are assigned to this zone before deletion, as this may cause referential integrity issues.
curl -X DELETE "https://api.integra.com/zonas/3" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Request

Method: DELETE Endpoint: /zonas/{id} Path Parameters:
ParameterTypeDescription
idIntegerID of the zone to delete
Headers:
  • Authorization: Bearer token (required)

​
Response

Status Code: 200 OK
Response Example
{
  "data": true,
  "message": "Zona eliminada"
}

​
Entity Structure

​
Zone Entity

FieldTypeDescription
idIntegerUnique identifier for the zone
nombreStringName of the zone
activoBooleanIndicates if the zone is active

​
Status Values

  • activo: true - The zone is active and can be assigned to units
  • activo: false - The zone is inactive and should not be used for new assignments

​
Relationships

Zones are geographical groupings that:
  • Can contain multiple organizational units
  • Help organize units by region or location
  • Are referenced when creating or updating units
  • May be used for reporting and analytics purposes

​
Validation Rules

​
Create Zone

  • nombre: Required, cannot be blank or null

​
Update Zone

  • id: Required, must reference an existing zone
  • nombre: Required, cannot be blank or null
  • activo: Required, must be a boolean value

​
Error Responses

​
Validation Error

Status Code: 400 Bad Request 
{
  "error": "Validation failed",
  "details": [
    {
      "field": "nombre",
      "message": "Debe establecer un nombre para la zona"
    }
  ]
}

​
Not Found Error

Status Code: 404 Not Found 
{
  "error": "Zone not found",
  "message": "No zone found with the specified ID"
}

​
Referential Integrity Error

Status Code: 409 Conflict 
{
  "error": "Cannot delete zone",
  "message": "This zone is referenced by one or more units and cannot be deleted"
}

​
Use Cases

​
Regional Organization

Zones can be used to organize units by geographical regions:
  • North, South, East, West zones
  • State or province-based zones
  • Metropolitan vs. rural zones
  • International vs. domestic zones

​
Operational Management

Zones enable:
  • Regional reporting and analytics
  • Zone-specific supervisor assignments
  • Geographical performance tracking
  • Resource allocation by region

​
Best Practices

  1. Naming Convention: Use clear, descriptive names for zones (e.g., “Zona Norte”, “Región Metropolitana”)
  2. Status Management: Instead of deleting zones with existing units, set them to inactive (activo: false)
  3. Referential Integrity: Before deleting a zone, ensure no units reference it
  4. Hierarchical Organization: Consider zone hierarchy if needed (e.g., regions containing zones)

​
Get States (Geographic)

Retrieve the list of Mexican states (estados) for geographic reference. This is a read-only catalog used for address and location information.

​
Authentication

This endpoint is publicly accessible and does not require authentication.

​
Response

​
data
array
Array of state objects
​
message
string
Success message: “Estados registrados”

​
Example Request

cURL
curl -X GET "https://api.integra.example/estados"

​
Example Response

{
  "data": [
    {
      "id": 1,
      "nombre": "Aguascalientes"
    },
    {
      "id": 2,
      "nombre": "Baja California"
    },
    {
      "id": 9,
      "nombre": "Ciudad de México"
    }
  ],
  "message": "Estados registrados",
  "success": true
}
This catalog contains all 32 Mexican states and is used for address validation and geographic filtering throughout the system.
  • Units API - Manage organizational units that belong to zones
  • Employees API - Manage employees assigned to units within zones

Build docs developers (and LLMs) love

Get started for freeTalk to us