Listar periodos
Consulta los periodos de un calendario y el estado de cada uno.
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
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
https://app.integranom.com/api/v1/payroll-calendars/{payroll_calendar_number}/periodsPath param: payroll_calendar_number — entero positivo, el número del calendario dentro de la organización. Lo obtienes de Calendarios de nómina → Listar.
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
| 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. |
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.
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
| 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. |