# Listar periodos (/docs/developers/api-reference/payroll-calculation/list-periods) ## Descripcion general [#descripcion-general] Este endpoint devuelve los **periodos** de un calendario de nómina, con el estado de cada uno y el resultado de su corrida cuando ya fue calculada. Es el punto de partida del flujo de cálculo: aquí identificas qué periodo vas a correr, recalcular, exportar o cerrar. Los periodos los genera automáticamente el calendario al crearse (por ejemplo, 24 periodos para un calendario quincenal). No se crean ni se eliminan por API. Requiere que la API key tenga el permiso **Listar periodos de nómina**. ## Estados de un periodo [#estados-de-un-periodo] El estado no se guarda en el periodo: se **deriva** de su corrida. | Estado | Significado | | ------------ | -------------------------------------------------------------------- | | `unopened` | El periodo existe pero nunca se ha abierto. Aún no tiene corrida. | | `draft` | Tiene una corrida abierta que todavía no se calcula. | | `calculated` | Ya tiene resultados. Se puede recalcular, exportar o cerrar. | | `closed` | Periodo cerrado. Es el estado final: la API no expone la reapertura. | ## Endpoint [#endpoint] `GET https://app.integranom.com/api/v1/payroll-calendars/{payroll_calendar_number}/periods` **Path param:** `payroll_calendar_number` — entero positivo, el número del calendario dentro de la organización. Lo obtienes de [Calendarios de nómina → Listar](/docs/developers/api-reference/payroll-calendars/list). ## Consulta los periodos de un calendario [#consulta-los-periodos-de-un-calendario] *** Devuelve todos los periodos del calendario, paginados de 20 en 20 y ordenados por año fiscal y número de periodo. Un calendario semanal tiene 52 periodos por año, así que recorre las páginas con `page`. ## Query params [#query-params] | Parametro | Tipo | Requerido | Default | Descripcion | | ------------- | ------------------------------------------------- | --------- | ------- | ---------------------------------------------------------------------- | | `page` | integer ≥ 1 | No | 1 | Página solicitada. El tamaño de página es fijo en 20. | | `fiscal_year` | integer (`YYYY`) | No | - | Filtra por año fiscal. Útil cuando el calendario abarca más de un año. | | `status` | `unopened` \| `draft` \| `calculated` \| `closed` | No | - | Filtra por el estado derivado del periodo. | **cURL** ```bash curl -X GET "https://app.integranom.com/api/v1/payroll-calendars/1/periods" \ -H "Authorization: Bearer TU_API_KEY" \ -H "Content-Type: application/json" ``` **Respuesta** ```json { "count": 24, "page": 1, "page_size": 20, "total_pages": 2, "next": "?page=2", "previous": null, "results": [ { "period_number": "2026-1", "fiscal_year": 2026, "sequence_number": 1, "start_date": "2026-01-01T00:00:00.000Z", "end_date": "2026-01-15T00:00:00.000Z", "pay_date": "2026-01-20T00:00:00.000Z", "days_in_period": 15, "accrual_month": 1, "status": "closed", "payroll_run_number": 1, "employee_count": 277, "net_total": "2062145.72", "calculated_at": "2026-01-16T18:30:34.193Z", "closed_at": "2026-01-16T18:51:21.898Z" }, { "period_number": "2026-2", "fiscal_year": 2026, "sequence_number": 2, "start_date": "2026-01-16T00:00:00.000Z", "end_date": "2026-01-31T00:00:00.000Z", "pay_date": "2026-02-05T00:00:00.000Z", "days_in_period": 16, "accrual_month": 1, "status": "unopened", "payroll_run_number": null, "employee_count": null, "net_total": null, "calculated_at": null, "closed_at": null } ] } ``` ## Encuentra el siguiente periodo por correr [#encuentra-el-siguiente-periodo-por-correr] *** Filtra por `status` para localizar el periodo que te interesa sin recorrer todas las páginas: `draft` para el que ya está abierto y falta calcular (al cerrar un periodo ordinario, el siguiente se abre solo si ya está generado), `unopened` para los que todavía no se abren, `calculated` para los que ya tienen resultados y aún puedes cerrar. **cURL** ```bash curl -X GET "https://app.integranom.com/api/v1/payroll-calendars/1/periods?status=unopened&fiscal_year=2026" \ -H "Authorization: Bearer TU_API_KEY" \ -H "Content-Type: application/json" ``` **Respuesta** ```json { "count": 11, "page": 1, "page_size": 20, "total_pages": 1, "next": null, "previous": null, "results": [ { "period_number": "2026-14", "fiscal_year": 2026, "sequence_number": 14, "start_date": "2026-07-16T00:00:00.000Z", "end_date": "2026-07-31T00:00:00.000Z", "pay_date": "2026-08-05T00:00:00.000Z", "days_in_period": 16, "accrual_month": 7, "status": "unopened", "payroll_run_number": null, "employee_count": null, "net_total": null, "calculated_at": null, "closed_at": null } ] } ``` ## Campos de cada fila [#campos-de-cada-fila] | Campo | Tipo | Descripcion | | -------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `period_number` | string | Identificador del periodo dentro del calendario, con el formato `{fiscal_year}-{sequence_number}` (por ejemplo `2026-14`). Es el que usas en la URL de los demás endpoints. | | `fiscal_year` | integer | Año fiscal del periodo. | | `sequence_number` | integer | Número de periodo dentro del año (1 = primer periodo). | | `start_date` | string (fecha) | Inicio del periodo. | | `end_date` | string (fecha) | Fin del periodo. | | `pay_date` | string (fecha) | Fecha de pago. | | `days_in_period` | integer | Días que abarca el periodo. | | `accrual_month` | integer | Mes de acumulación del periodo, de `1` a `12`: el mes de la ventana mensual de ISR en que cuenta. Los periodos que nunca tuvieron un mes asignado devuelven el mes de su fecha de fin. | | `status` | string | Estado derivado: `unopened`, `draft`, `calculated` o `closed`. | | `payroll_run_number` | integer \| null | Número de corrida. `null` si el periodo no se ha abierto. | | `employee_count` | integer \| null | Empleados incluidos en la corrida. `null` si no se ha abierto. | | `net_total` | string \| null | Neto a depositar de la corrida. `null` mientras no esté calculada. | | `calculated_at` | string (fecha) \| null | Última vez que se calculó. | | `closed_at` | string (fecha) \| null | Fecha de cierre. | Los importes se devuelven como **string** para no perder precisión decimal. ## Errores [#errores] | Status | Causa | | ------ | --------------------------------------------------------------------------------------------------- | | `400` | `payroll_calendar_number` inválido en la URL, o valor inválido en `page`, `fiscal_year` o `status`. | | `401` | API key ausente o inválida. | | `403` | La API key no tiene el permiso **Listar periodos de nómina**. | | `404` | El calendario no existe en esta organización. |