Skip to main content

​
Units API

The Units API provides comprehensive CRUD operations for managing organizational units (unidades), which represent physical locations, branches, or operational sites within the organization.

​
Endpoints

​
Create Unit

Registers a new organizational unit. 
curl -X POST "https://api.integra.com/unidades/registrar" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clave": "UN001",
    "nombre": "Sucursal Centro",
    "localizacion": "Centro Histórico",
    "telefono": "5551234567",
    "activo": true,
    "direccion": "Av. Principal 123, Col. Centro",
    "email": "[email protected]",
    "idZona": 1,
    "idEstado": 5,
    "idSupervisor": 10
  }'

​
Request

Method: POST Endpoint: /unidades/registrar Headers:
  • Authorization: Bearer token (required)
  • Content-Type: application/json (required)
Required Permissions: UNIDADES_CREAR Body Parameters:
FieldTypeRequiredConstraintsDescription
claveStringYes1-10 charactersUnique code for the unit
nombreStringYes1-100 charactersName of the unit
localizacionStringNoMax 80 charactersLocation description
telefonoStringNoMax 15 charactersContact phone number
activoBooleanNo-Active status of the unit
direccionStringNoMax 255 charactersPhysical address
emailStringNoMax 100 charactersContact email
idZonaIntegerYes-Zone ID where the unit is located
idEstadoIntegerYes-State/Province ID
idSupervisorIntegerYes-ID of the employee supervising this unit

​
Response

Status Code: 200 OK
Response Example
{
  "data": {
    "id": 45,
    "clave": "UN001",
    "nombre": "Sucursal Centro",
    "nombreCompleto": "UN001 - Sucursal Centro",
    "activo": true,
    "operativa": true,
    "contacto": {
      "direccion": "Av. Principal 123, Col. Centro",
      "telefono": "5551234567",
      "email": "[email protected]",
      "localizacion": "Centro Histórico",
      "zona": {
        "id": 1,
        "nombre": "Zona Norte"
      }
    },
    "supervisor": {
      "id": 10,
      "nombre": "Juan Pérez"
    }
  },
  "message": "Unidad registrada"
}

​
Update Unit

Updates an existing organizational unit. 
curl -X PUT "https://api.integra.com/unidades/actualizar" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 45,
    "clave": "UN001",
    "nombre": "Sucursal Centro Actualizada",
    "localizacion": "Centro Histórico",
    "telefono": "5551234567",
    "activo": true,
    "direccion": "Av. Principal 123, Col. Centro",
    "email": "[email protected]",
    "idZona": 1,
    "idEstado": 5,
    "idSupervisor": 10
  }'

​
Request

Method: PUT Endpoint: /unidades/actualizar Headers:
  • Authorization: Bearer token (required)
  • Content-Type: application/json (required)
Required Permissions: UNIDADES_EDITAR Body Parameters: Same as Create Unit, plus:
FieldTypeRequiredConstraintsDescription
idIntegerYesMin value: 1ID of the unit to update

​
Response

Status Code: 200 OK
Response Example
{
  "data": null,
  "message": "Unidad actualizada"
}

​
Update Unit Status

Enables or disables a unit. 
# Enable unit
curl -X PUT "https://api.integra.com/unidades/estatus/45/true" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Disable unit
curl -X PUT "https://api.integra.com/unidades/estatus/45/false" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Request

Method: PUT Endpoint: /unidades/estatus/{id}/{estatus} Path Parameters:
ParameterTypeDescription
idIntegerID of the unit
estatusBooleantrue to enable, false to disable
Headers:
  • Authorization: Bearer token (required)

​
Response

Status Code: 200 OK
Response Example (Enable)
{
  "data": null,
  "message": "Unidad habilitada"
}
Response Example (Disable)
{
  "data": null,
  "message": "Unidad deshabilitada"
}

​
Delete Unit

Permanently deletes a unit from the system.
Deleting a unit is a permanent operation. Ensure the unit is no longer needed and has no critical dependencies before deletion.
curl -X DELETE "https://api.integra.com/unidades/45" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Request

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

​
Response

Status Code: 200 OK
Response Example
{
  "data": null,
  "message": "Unidad eliminada"
}

​
Entity Structure

​
Unit Entity

FieldTypeDescription
idIntegerUnique identifier for the unit
claveStringUnique code for the unit (1-10 characters)
nombreStringShort name of the unit
nombreCompletoStringFull name combining code and name
activoBooleanWhether the unit is active
operativaBooleanWhether the unit is operational
contactoObjectContact information (see below)
requiereCamaraBooleanWhether the unit requires camera integration
codigoAutorizacionKioscoStringAuthorization code for kiosk mode
requiereResetBooleanWhether the unit requires reset
versionKioscoIntegerVersion of the kiosk software
supervisorObjectSupervisor employee information
tiempoCompensacionTimeCompensation time configuration
tiempoEsperaKioscoIntegerKiosk wait time in seconds

​
Contact Object

FieldTypeDescription
direccionStringPhysical address
telefonoStringContact phone number
emailStringContact email
localizacionStringLocation description
estadoObjectState/Province information
zonaObjectZone information

​
Zone Object

FieldTypeDescription
idIntegerZone identifier
nombreStringZone name

​
Relationships

Units have the following relationships:
  • Zone: Each unit belongs to a zone (idZona)
  • State: Each unit is located in a state/province (idEstado)
  • Supervisor: Each unit has an assigned supervisor employee (idSupervisor)
  • Operating Schedules: Units can have multiple operating schedules defining their hours of operation
  • Employees: Multiple employees can be assigned to a unit
  • Kiosk Configuration: Units can have kiosk mode settings for employee check-in/out

​
Validation Rules

​
Create/Update Unit

  • clave: Required, 1-10 characters, must be unique
  • nombre: Required, 1-100 characters
  • localizacion: Optional, max 80 characters
  • telefono: Optional, max 15 characters
  • direccion: Optional, max 255 characters
  • email: Optional, max 100 characters, must be valid email format
  • idZona: Required, must reference an existing zone
  • idEstado: Required, must reference an existing state
  • idSupervisor: Required, must reference an existing employee

​
Error Responses

​
Validation Error

Status Code: 400 Bad Request 
{
  "error": "Validation failed",
  "details": [
    {
      "field": "clave",
      "message": "La clave debe tener entre 1 y 10 caracteres."
    },
    {
      "field": "email",
      "message": "El email no puede exceder los 100 caracteres."
    }
  ]
}

​
Not Found Error

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

​
Unauthorized Error

Status Code: 403 Forbidden 
{
  "error": "Insufficient permissions",
  "message": "You do not have permission to perform this action"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us