Detalle | Nominex

Descripcion general

Este endpoint devuelve la información de un periodo: sus fechas, su estado y —cuando ya fue calculado— los totales de la corrida y el detalle por empleado.

Si el periodo aún no se ha abierto, la respuesta llega con status: "unopened", totals en null y entries vacío: el periodo existe, simplemente no tiene resultados todavía.

Requiere que la API key tenga el permiso Listar periodos de nómina.

Endpoint

GEThttps://app.integranom.com/api/v1/payroll-calendars/{payroll_calendar_number}/periods/{period_number}

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-14). Un calendario puede abarcar más de un año fiscal, por eso el identificador lleva el año.

Devuelve el periodo con sus totales y una fila por empleado. entries trae todos los empleados de la corrida (no está paginado); para un desglose completo por concepto, usa la exportación a Excel.

Consulta un periodo sin abrir

Un periodo que nunca se ha corrido no es un error: responde 200 con status: "unopened", sin totales ni detalle. Para correrlo, llama a calcular — abre el periodo y lo calcula en una sola llamada.

Campos de la respuesta

Campo	Tipo	Descripcion
`period_number`	string	Identificador del periodo (`{fiscal_year}-{sequence_number}`).
`payroll_calendar_number`	integer	Calendario al que pertenece.
`calendar_name`	string	Nombre del calendario.
`legal_entity_number`	integer	Razón social del calendario.
`frequency`	string	Frecuencia del calendario (`weekly`, `biweekly`, `semimonthly`, `monthly`).
`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	`unopened`, `draft`, `calculated` o `closed`.
`payroll_run_number`	integer \| null	Número de corrida.
`employee_count`	integer \| null	Empleados incluidos en la corrida.
`recalc_pending`	boolean	`true` cuando la corrida quedó desfasada del registro de incidencias: las cifras de esta respuesta no reflejan el estado vigente hasta que se vuelva a calcular. Ver abajo.
`totals`	objeto \| null	Totales de la corrida. `null` mientras no esté calculada.
`entries`	array	Una fila por empleado. Vacío mientras no esté calculada.

`totals`

Campo	Descripcion
`total_perceptions`	Percepciones totales.
`total_non_cash`	Percepciones no monetarias (por ejemplo, una prestación en especie). Los vales de despensa en tarjeta no cuentan aquí cuando el recibo los descuenta en Vales de despensa entregados.
`total_withheld_food_vouchers`	Vales de despensa entregados en tarjeta que la corrida descuenta en Vales de despensa entregados. Ya están incluidos en `total_deductions`.
`total_deductions`	Deducciones totales.
`total_isr`	ISR retenido.
`total_subsidio`	Subsidio para el empleo aplicado contra el ISR en toda la corrida. Ya está descontado de `total_isr`. El subsidio que excede el ISR se paga como la percepción Subsidio para el empleo, sin pasar del subsidio del periodo (con la tarifa del periodo, en proporción a los días pagados), y está incluido en `total_perceptions`. En algunas nóminas cerradas, ese excedente quedó como informativo, no se pagó y no está incluido.
`total_imss_worker`	IMSS a cargo del trabajador.
`total_net`	Neto a depositar.
`total_imss_employer`	IMSS patronal.
`total_infonavit`	INFONAVIT patronal.
`total_isn`	Impuesto sobre nómina.
`total_employer_cost`	Costo patronal.
`total_company_cost`	Costo total para la empresa.
`deduction_lines`	Desglose de las deducciones por concepto (`code`, `name`, `amount`).
`employer_lines`	Desglose del costo patronal por concepto.
`imss_employer_lines`	IMSS patronal desglosado por rama (cuota fija, riesgo de trabajo, invalidez y vida, guarderías, retiro, cesantía y vejez, …). Ver abajo.

`entries`

Campo	Descripcion
`employee_number`	Número del empleado dentro de la organización.
`employee_name`	Nombre completo del empleado.
`total_perceptions`	Percepciones del empleado en el periodo.
`total_deductions`	Deducciones del empleado.
`isr`	ISR retenido al empleado.
`imss_worker`	IMSS a cargo del empleado.
`net_pay`	Neto a depositar al empleado.
`has_retro_adjustment`	`true` si el recibo incluye líneas de ajuste retroactivo.
`period_days`	Días que abarca el periodo.
`paid_days`	Días pagados de sueldo.
`absence_days`	Días de falta descontados.
`disability_days`	Días de incapacidad.
`incidence_count_internal`	Incidencias del periodo capturadas dentro de la plataforma.
`incidence_count_external`	Incidencias del periodo provenientes de una fuente externa (API, reloj checador).
`daily_salary`	Salario diario.
`sbc_daily`	Salario base de cotización diario.
`subsidio`	Subsidio para el empleo aplicado contra el ISR del empleado. Ya está descontado de `isr`. El subsidio que excede el ISR se paga como la percepción Subsidio para el empleo, sin pasar del subsidio del periodo (con la tarifa del periodo, en proporción a los días pagados), y está incluido en `total_perceptions`. En algunas nóminas cerradas, ese excedente quedó como informativo, no se pagó y no está incluido.
`withheld_food_vouchers`	Vales de despensa entregados en tarjeta que el recibo descuenta en Vales de despensa entregados.
`other_deductions`	Deducciones distintas de ISR e IMSS trabajador. Incluye `withheld_food_vouchers`.
`imss_employer`	IMSS patronal del empleado.
`infonavit_employer`	INFONAVIT patronal del empleado.
`isn`	Impuesto sobre nómina del empleado.
`total_employer_cost`	Costo patronal del empleado.
`total_company_cost`	Costo total para la empresa por ese empleado.

IMSS patronal por rama (`imss_employer_lines`)

employer_lines trae el IMSS patronal como una sola cifra. imss_employer_lines lo abre por rama de seguro, que es el desglose que piden la conciliación con el SUA y la contabilidad por centro de costo.

Campo	Descripcion
`lines`	Una entrada por rama, con `code`, `name` e `amount`.
`partial`	`true` cuando alguna corrida no conserva los insumos congelados necesarios para reconstruir el desglose. Esos empleados no aparecen en `lines`, pero sus cuotas sí están en `total_imss_employer`: en ese caso la suma de `lines` es menor que el total.

El desglose se recalcula con la misma función del motor que se usó al calcular la nómina, sobre los insumos congelados de la corrida — no es una reestimación.

Sincronización pendiente (`recalc_pending`)

Los periodos abiertos son una ventana viva sobre el registro de incidencias: cada captura vuelve a calcular la corrida en tiempo real, así que normalmente recalc_pending llega en false.

Llega en true cuando esa actualización automática no se completó o el registro se modificó fuera de la plataforma. Las cifras siguen siendo las del último cálculo — vuelve a calcular con recalculate para aplicar el estado vigente. Cerrar un periodo desfasado está bloqueado, así que nada desactualizado se paga.

Todos los importes se devuelven como string para no perder precisión decimal.

Errores

Status	Causa
`400`	`payroll_calendar_number` inválido, o `period_number` con formato incorrecto (debe ser `{fiscal_year}-{sequence_number}`, por ejemplo `2026-14`).
`401`	API key ausente o inválida.
`403`	La API key no tiene el permiso Listar periodos de nómina.
`404`	El calendario o el periodo no existen en esta organización.

Listar periodos GET

Página anterior

Calcular periodo POST

Página siguiente