Capturar incidencias
Captura una incidencia para los empleados del periodo, en su ventana de fechas.
Descripcion general
Este endpoint captura un tipo de incidencia para empleados de un periodo, dentro de su ventana de fechas. Es la misma captura que Asistencia → Capturar, acotada a un periodo por comodidad.
Las incidencias se registran en el registro global de asistencia, del que la corrida lee. Si el periodo está abierto y ya calculado, se recalcula solo con la captura. Si el periodo está cerrado, una captura dentro de sus fechas se convierte en un ajuste retroactivo y requiere confirm_retro: true.
Las horas extra (OVERTIME_DOUBLE_HOURS y OVERTIME_TRIPLE_HOURS) capturadas por la API se crean pendientes de autorizar: no se pagan hasta que las autorizan todos los niveles configurados en la organización (jefe directo, Recursos Humanos o los dos). Su estatus se consulta en el campo approval_status de Listar asistencia.
Requiere que la API key tenga el permiso Capturar incidencias del periodo.
Endpoint
https://app.integranom.com/api/v1/payroll-calendars/{payroll_calendar_number}/periods/{period_number}/incidencesPath params:
payroll_calendar_number— entero positivo, el número del calendario.period_number— el periodo, con el formato{fiscal_year}-{sequence_number}(por ejemplo2026-11).
Captura para el periodo
El cuerpo es el mismo de la captura global, sin el rango obligatorio: start_date / end_date son opcionales y por omisión abarcan todo el periodo. Si los envías, deben caer dentro de la ventana del periodo (de lo contrario 409 DATE_OUT_OF_PERIOD).
Cuando el periodo ya está abierto, la captura se restringe a su plantilla (los empleados de la corrida): un employee_number que no esté en ella se rechaza con NOT_IN_ROSTER.
Campos del cuerpo
| Campo | Tipo | Requerido | Notas |
|---|---|---|---|
incidence_code | string | Sí | Código del tipo, resuelto en la razón social de los empleados. |
employee_numbers | integer[] | Sí | 1–500 empleados, misma razón social. Con el periodo abierto, deben estar en la plantilla. |
start_date / end_date | string (YYYY-MM-DD) | No | Por omisión, la ventana del periodo. Si se envían, deben caer dentro de ella. |
quantity | number | Condicional | Requerida para tipos hours y count. En VACATION_PAID y VACATION_UNPAID, 0.5 registra medio día por fecha y cualquier otro valor se registra como 1 (día completo, por omisión); en los demás tipos days se ignora y se registra 1. |
notes | string | No | Máximo 500 caracteres. |
disability_folio | string | No | Folio del certificado de incapacidad, máximo 30 caracteres. Solo para tipos de incapacidad y un solo empleado. Se guarda en mayúsculas. Un folio pertenece a un solo empleado y sus días deben ser consecutivos. |
confirm_retro | boolean | No | Autoriza el ajuste retroactivo si el periodo está cerrado. |
Después de capturar: recalcula
Un periodo abierto ya calculado se recalcula solo con cada captura: no necesitas hacer nada más para que los resultados la reflejen.
La respuesta lo confirma con recalc_pending: false. Cuando llega en true — el recálculo automático no se completó — llama a recalcular; hasta entonces el periodo queda con un cálculo desactualizado, y cerrar lo rechaza con STALE_CALCULATION.
Errores
| Status | Código | Causa |
|---|---|---|
400 | — | payroll_calendar_number / period_number inválidos, o cuerpo mal formado. |
400 | EMPLOYEE_NOT_FOUND / NO_ACTIVE_EMPLOYMENT | Empleado inexistente o sin empleo activo/pendiente. |
400 | NOT_IN_ROSTER | Un empleado no pertenece a la corrida del periodo. |
400 | LEGAL_ENTITY_MISMATCH | Los empleados no comparten la razón social del tipo. |
400 | INCIDENCE_NOT_FOUND | Sin tipo activo con ese código en la razón social. |
400 | RANGE_TOO_LARGE | El rango excede 366 días. |
400 | DISABILITY_FOLIO_NOT_ALLOWED | Se envió disability_folio con un tipo que no es incapacidad. |
400 | DISABILITY_FOLIO_MULTIPLE_EMPLOYEES | Se envió disability_folio para más de un empleado. |
401 | — | API key ausente o inválida. |
403 | — | La API key no tiene el permiso Capturar incidencias del periodo. |
404 | — | El calendario o el periodo no existen en esta organización. |
409 | DATE_OUT_OF_PERIOD | Una fecha cae fuera de la ventana del periodo. |
409 | DAY_CONFLICT | Algún empleado ya tiene otro estatus de día en una de las fechas. Con disability_folio, también cuenta una incapacidad del mismo tipo ya capturada. |
409 | OVERTIME_REJECTED | Algún empleado ya tiene horas extra rechazadas de ese tipo, sin checadas vinculadas, en una de las fechas. No se captura nada; el registro rechazado se corrige en la plataforma, en Incidencias de tiempo: cambia sus horas para enviarlo de nuevo a autorización, o elimínalo y vuelve a capturar. |
409 | RETRO_CONFIRMATION_REQUIRED | El periodo está cerrado. Reenvía con confirm_retro: true. |
409 | DISABILITY_FOLIO_TAKEN | El folio ya está registrado para otro empleado. No se captura nada. |
409 | DISABILITY_FOLIO_NOT_CONSECUTIVE | El empleado ya tiene ese folio en fechas que no son consecutivas con las enviadas. No se captura nada. |