Zones API

Manage geographical zones for organizational units

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

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

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:

Field	Type	Required	Description
nombre	String	Yes	Name 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

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:

Field	Type	Required	Description
id	Integer	Yes	ID of the zone to update
nombre	String	Yes	Updated name of the zone (cannot be blank)
activo	Boolean	Yes	Active 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

curl -X DELETE "https://api.integra.com/zonas/3" \
  -H "Authorization: Bearer YOUR_TOKEN"

Request

Method: DELETE

Endpoint: /zonas/{id}

Path Parameters:

Parameter	Type	Description
id	Integer	ID 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

Field	Type	Description
id	Integer	Unique identifier for the zone
nombre	String	Name of the zone
activo	Boolean	Indicates 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

Show Estado

id · integer

State ID

nombre · string

State name (e.g., “Jalisco”, “Ciudad de México”)

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.

---

Related Endpoints

• Units API - Manage organizational units that belong to zones
• Employees API - Manage employees assigned to units within zones