Observation Management

Query Observations by Filter

Retrieve observations with flexible filtering options.

Endpoint

GET /observaciones/filtro

Query Parameters

supervisorId

integer

Filter by supervisor ID

unidadId

integer

Filter by unit ID

areaId

integer

Filter by area ID

departamentoResponsableId

integer

Filter by responsible department ID

departamentoColaboradorId

integer

Filter by collaborator department ID

departamentoGeneraId

integer

Filter by originating department ID

zonaId

integer

Filter by geographic zone ID

prioridad

string

Filter by priority: ALTA, MEDIA, BAJA

tipoObservacionId

integer

Filter by observation type ID

estatusId

integer

Filter by status ID

folio

string

Filter by observation folio/tracking number

usuarioCreadorId

integer

Filter by creator user ID

creadoDesde

datetime

Filter by creation date from (ISO 8601)

creadoHasta

datetime

Filter by creation date until (ISO 8601)

pagina

integer

Page number for pagination (zero-based)

filas

integer

Number of rows per page

privado

boolean

Filter by private/public status

Response

data

array

Show ResumenObservacion

integer

Observation ID

folioObservacion

string

Unique tracking number/folio

unidadId

integer

Unit ID where observation was made

unidadNombreCompleto

string

Full unit name

tipoObservacionNombre

string

Observation type name (e.g., Seguridad, Calidad)

estatusNombre

string

Current status name

estatusColorBg

string

Background color for status (hex code)

departamentoOrigenNombre

string

Originating department name

titulo

string

Observation title/brief description

prioridad

string

Priority level: ALTA, MEDIA, BAJA

requiereSeguimiento

boolean

Whether follow-up is required

creado

string

Creation timestamp (ISO 8601)

modificado

string

Last modification timestamp (ISO 8601)

message

string

Success message

Example Request

cURL

curl -X GET "http://localhost:8081/comialex/api/integra/observaciones/filtro?unidadId=5&prioridad=ALTA&estatusId=1" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example Response

{
  "data": [
    {
      "id": 123,
      "folioObservacion": "OBS-2026-001234",
      "unidadId": 5,
      "unidadNombreCompleto": "Planta Principal - Producción",
      "tipoObservacionNombre": "Seguridad",
      "estatusNombre": "Abierta",
      "estatusColorBg": "#FF5722",
      "departamentoOrigenNombre": "Producción",
      "titulo": "Fuga de líquido en línea 3",
      "prioridad": "ALTA",
      "requiereSeguimiento": true,
      "creado": "2026-03-05T14:30:00",
      "modificado": "2026-03-05T14:30:00"
    },
    {
      "id": 124,
      "folioObservacion": "OBS-2026-001235",
      "unidadId": 5,
      "unidadNombreCompleto": "Planta Principal - Producción",
      "tipoObservacionNombre": "Equipo",
      "estatusNombre": "En Proceso",
      "estatusColorBg": "#FFC107",
      "departamentoOrigenNombre": "Mantenimiento",
      "titulo": "Vibración anormal en motor A2",
      "prioridad": "ALTA",
      "requiereSeguimiento": true,
      "creado": "2026-03-05T15:45:00",
      "modificado": "2026-03-05T16:20:00"
    }
  ],
  "message": "Observaciones recuperadas",
  "success": true
}

Query Unit Observations

Retrieve public observations for a specific unit.

Endpoint

GET /observaciones/unidad/filtro

This endpoint automatically sets privado=false, returning only public observations visible to all unit members.

Query Parameters

Same as the general filter endpoint, but the privado parameter is automatically set to false.

unidadId

integer

required

Unit ID (required for this endpoint)

prioridad

string

Filter by priority: ALTA, MEDIA, BAJA

tipoObservacionId

integer

Filter by observation type ID

estatusId

integer

Filter by status ID

creadoDesde

datetime

Filter by creation date from (ISO 8601)

creadoHasta

datetime

Filter by creation date until (ISO 8601)

Response

Same structure as the general filter endpoint.

Example Request

cURL

curl -X GET "http://localhost:8081/comialex/api/integra/observaciones/unidad/filtro?unidadId=5&prioridad=ALTA" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Use this endpoint for displaying observations on unit-specific dashboards or kiosk screens where only public information should be shown.

Update Observation Status

Update the status of an observation.

Endpoint

PUT /observaciones/actualizarEstatus/{id}/{estatusId}

Path Parameters

integer

required

Observation ID to update

estatusId

integer

required

New status ID to assign

Response

data

null

No data returned on success

message

string

Success message: “Estatus actualizado”

Example Request

cURL

curl -X PUT http://localhost:8081/comialex/api/integra/observaciones/actualizarEstatus/123/3 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example Response

{
  "data": null,
  "message": "Estatus actualizado",
  "success": true
}

The system automatically records who updated the status and when. Check the modificado timestamp in subsequent queries.

Common Use Cases

Dashboard: High Priority Open Items

curl -X GET "http://localhost:8081/comialex/api/integra/observaciones/filtro?prioridad=ALTA&estatusId=1" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Unit Safety Board: Public Observations

curl -X GET "http://localhost:8081/comialex/api/integra/observaciones/unidad/filtro?unidadId=5&tipoObservacionId=1" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Monthly Report: All Resolved Observations

curl -X GET "http://localhost:8081/comialex/api/integra/observaciones/filtro?estatusId=3&creadoDesde=2026-03-01T00:00:00&creadoHasta=2026-03-31T23:59:59" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Track Specific Observation by Folio

curl -X GET "http://localhost:8081/comialex/api/integra/observaciones/filtro?folio=OBS-2026-001234" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Priority Levels

Priority	Spanish	Description	Typical Response Time
ALTA	Alta	High priority, immediate attention	< 24 hours
MEDIA	Media	Medium priority, timely response	2-3 days
BAJA	Baja	Low priority, standard handling	1 week

Status Workflow Examples

Safety Incident Flow

Report Created

Status: Abierta (Open)Employee or supervisor creates observation documenting the incident.

Investigation Started

Status: En Proceso (In Progress)Safety team begins investigation and corrective action.

Issue Resolved

Status: Resuelta (Resolved)Corrective actions completed, awaiting verification.

Case Closed

Status: Cerrada (Closed)Verification complete, observation archived.

Quality Issue Flow

Issue Identified

Status: Abierta (Open)Quality control identifies defect or non-conformance.

Root Cause Analysis

Status: En Proceso (In Progress)Team investigates cause and develops corrective action.

Corrected

Status: Resuelta (Resolved)Issue corrected, process updated.

Verified

Status: Cerrada (Closed)Quality verified, no recurrence.

Filtering Best Practices

Combine Multiple Filters

For precise queries, combine multiple filters:

curl -X GET "http://localhost:8081/comialex/api/integra/observaciones/filtro?unidadId=5&prioridad=ALTA&estatusId=1&tipoObservacionId=2" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

This retrieves: High priority, open, safety observations in unit 5.

Use Date Ranges for Reports

curl -X GET "http://localhost:8081/comialex/api/integra/observaciones/filtro?creadoDesde=2026-03-01T00:00:00&creadoHasta=2026-03-31T23:59:59" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Pagination for Large Datasets

# First page (20 items)
curl -X GET "http://localhost:8081/comialex/api/integra/observaciones/filtro?pagina=0&filas=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Second page
curl -X GET "http://localhost:8081/comialex/api/integra/observaciones/filtro?pagina=1&filas=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Error Handling

Invalid Status ID

{
  "success": false,
  "message": "Estatus no encontrado",
  "timestamp": 1709644800000
}

HTTP Status: 404 Not Found

Observation Not Found

{
  "success": false,
  "message": "Observación no encontrada",
  "timestamp": 1709644800000
}

HTTP Status: 404 Not Found

Unauthorized Access

Attempting to view private observations without permission:

{
  "success": false,
  "message": "Acceso denegado",
  "timestamp": 1709644800000
}

HTTP Status: 403 Forbidden

Observations Overview

Learn about observation concepts

Authentication

JWT tokens and access control

Authentication

Attendance

Employees

Organization

Credentials

Access Control

Kiosk

Reports

Observations

​Query Observations by Filter

​Endpoint

​Query Parameters

​Response

​Example Request

​Example Response

​Query Unit Observations

​Endpoint

​Query Parameters

​Response

​Example Request

​Update Observation Status

​Endpoint

​Path Parameters

​Response

​Example Request

​Example Response

​Common Use Cases

​Dashboard: High Priority Open Items

​Unit Safety Board: Public Observations

​Monthly Report: All Resolved Observations

​Track Specific Observation by Folio

​Priority Levels

​Status Workflow Examples

​Safety Incident Flow

​Quality Issue Flow

​Filtering Best Practices

​Combine Multiple Filters

​Use Date Ranges for Reports

​Pagination for Large Datasets

​Error Handling

​Invalid Status ID

​Observation Not Found

​Unauthorized Access

​Related Endpoints

Observations Overview

Authentication

Build docs developers (and LLMs) love

Query Observations by Filter

Endpoint

Query Parameters

Response

Example Request

Example Response

Query Unit Observations

Endpoint

Query Parameters

Response

Example Request

Update Observation Status

Endpoint

Path Parameters

Response

Example Request

Example Response

Common Use Cases

Dashboard: High Priority Open Items

Unit Safety Board: Public Observations

Monthly Report: All Resolved Observations

Track Specific Observation by Folio

Priority Levels

Status Workflow Examples

Safety Incident Flow

Quality Issue Flow

Filtering Best Practices

Combine Multiple Filters

Use Date Ranges for Reports

Pagination for Large Datasets

Error Handling

Invalid Status ID

Observation Not Found

Unauthorized Access

Related Endpoints