# Capturar incidencias (/docs/developers/api-reference/payroll-calculation/capture-incidences) ## Descripcion general [#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](/docs/developers/api-reference/attendance/capture), 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](/docs/developers/api-reference/attendance/list#estatus-de-autorizacion). Requiere que la API key tenga el permiso **Capturar incidencias del periodo**. ## Endpoint [#endpoint] `POST https://app.integranom.com/api/v1/payroll-calendars/{payroll_calendar_number}/periods/{period_number}/incidences` **Path params:** * `payroll_calendar_number` — entero positivo, el número del calendario. * `period_number` — el periodo, con el formato `{fiscal_year}-{sequence_number}` (por ejemplo `2026-11`). ## Captura para el periodo [#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 [#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. | **cURL** ```bash curl -X POST "https://app.integranom.com/api/v1/payroll-calendars/1/periods/2026-11/incidences" \ -H "Authorization: Bearer TU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "incidence_code": "FALTA", "employee_numbers": [1, 2] }' ``` **Respuesta** ```json { "created": 2, "retros_touched": 0, "recalc_pending": false, "period_number": "2026-11" } ``` ## Después de capturar: recalcula [#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](/docs/developers/api-reference/payroll-calculation/recalculate); hasta entonces el periodo queda con un cálculo **desactualizado**, y [cerrar](/docs/developers/api-reference/payroll-calculation/close) lo rechaza con `STALE_CALCULATION`. ## Errores [#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. |