Capturar
Captura una incidencia de asistencia para varios empleados en un rango de fechas.
Descripcion general
Este endpoint captura un tipo de incidencia (falta, vacaciones, horas extra, retardo, etc.) para un conjunto de empleados a lo largo de un rango de fechas. Las incidencias se registran en el registro global de asistencia, del que cada corrida de nómina lee. Los periodos abiertos ya calculados se recalculan solos con cada captura, así que sus recibos reflejan el registro de inmediato. Si ese recálculo automático no se completa, la respuesta llega con recalc_pending: true y el periodo queda desactualizado hasta que lo recalcules.
Referencias por número/código: los empleados por employee_numbers y el tipo por incidence_code. El catálogo de tipos es global y fijo de la plataforma — el mismo conjunto de códigos para todas las razones sociales (consulta Listar tipos de incidencia).
Una fecha que caiga dentro de un periodo cerrado no se aplica en silencio: se convierte en un ajuste retroactivo que corrige la nómina en el siguiente periodo, y debes confirmarlo con confirm_retro: true (ver más abajo).
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 asistencia.
Endpoint
https://app.integranom.com/api/v1/attendanceCaptura una incidencia en un rango
Un tipo de incidencia, un conjunto de empleados, un rango de fechas. Para un tipo de día (falta, vacaciones, incapacidad) se crea una entrada por día con cantidad 1, o 0.5 en vacaciones de medio día. Vacaciones pagadas (VACATION_PAID) y los permisos con y sin goce (LEAVE_PAID, LEAVE_UNPAID) solo crean entradas en los días hábiles del horario de cada empleado: sus días de descanso y los días festivos de ley se omiten (sin horario ni rotación asignados, cuenta el predeterminado de la organización; sin ninguno, solo los festivos), y una fecha de medio día que cae en uno de ellos se ignora. El ejemplo captura una falta el 3 y el 4 de junio para dos empleados → created: 4.
created es el número de entradas registradas; retros_touched, cuántos ajustes retroactivos se crearon o refrescaron (0 cuando ninguna fecha cae en un periodo cerrado). El rango no puede exceder 366 días.
Campos del cuerpo
| Campo | Tipo | Requerido | Notas |
|---|---|---|---|
incidence_code | string | Sí | Código del tipo de incidencia en el catálogo global (p. ej. LATENESS). |
employee_numbers | integer[] | Sí | 1–500 empleados. Cada uno debe tener un empleo activo o pendiente. |
start_date / end_date | string (YYYY-MM-DD) | Sí | Rango (inclusivo). end_date ≥ start_date. Máximo 366 días. |
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 que las fechas dentro de un periodo cerrado se registren como ajuste retroactivo. Ver abajo. |
Fechas dentro de un periodo cerrado (ajuste retroactivo)
Cerrar un periodo es definitivo. Una incidencia dentro de sus fechas no reescribe la nómina ya pagada: se registra como un ajuste retroactivo que corrige la diferencia en el siguiente periodo.
Por eso, si alguna fecha cae en un periodo cerrado, la captura se rechaza con 409 RETRO_CONFIRMATION_REQUIRED (con retro_periods, los periodos afectados). Reenvíala con confirm_retro: true para aceptar y registrar el ajuste — la respuesta trae retros_touched mayor a 0.
Cantidad (según la unidad del tipo)
| Unidad del tipo | quantity | Comportamiento |
|---|---|---|
days de vacaciones (VACATION_PAID, VACATION_UNPAID) | Opcional | Una entrada por día: 0.5 es medio día y cualquier otro valor se registra como 1. |
Demás days (falta, incapacidad, permiso…) | Se ignora | Una entrada por día con cantidad 1. |
hours (horas extra) | Requerida | Las horas capturadas por día del rango. |
count (retardos) | Requerida | El número de ocurrencias por día del rango. |
Forma de la respuesta
200 — { "created": number, "retros_touched": number, "recalc_pending": boolean }.
| Campo | Significado |
|---|---|
created | Entradas registradas en el registro global (reenvíos idénticos no se duplican; sobre horas extra rechazadas sin checadas vinculadas, la respuesta es 409 OVERTIME_REJECTED). |
retros_touched | Ajustes retroactivos creados o refrescados por fechas dentro de un periodo cerrado. |
recalc_pending | true si el recálculo en tiempo real de algún periodo abierto no se completó: la incidencia quedó registrada, pero los recibos de ese periodo van desfasados hasta volver a calcularlo. |
Errores
| Status | Código | Causa |
|---|---|---|
400 | — | Cuerpo mal formado o inválido. |
400 | EMPLOYEE_NOT_FOUND | Algún employee_number no existe en la organización. |
400 | NO_ACTIVE_EMPLOYMENT | Algún empleado no tiene empleo activo o pendiente. |
400 | INCIDENCE_NOT_FOUND | Sin tipo activo con ese incidence_code en el catálogo global. |
400 | RANGE_TOO_LARGE | El rango excede 366 días. |
400 | NO_CHARGEABLE_DAYS | En vacaciones pagadas o permisos, todas las fechas del rango son días de descanso o festivos para los empleados. No se captura nada. |
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 asistencia. |
409 | DAY_CONFLICT | Algún empleado ya tiene otro estatus de día en una de las fechas (los tipos de día son mutuamente excluyentes). Con disability_folio, también cuenta una incapacidad del mismo tipo ya capturada. No se captura nada. |
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 | Alguna fecha cae en un periodo 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. |