# Detalle (/docs/developers/api-reference/payroll-calculation/detail) ## Descripcion general [#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 [#endpoint] `GET https://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. ## Consulta un periodo calculado [#consulta-un-periodo-calculado] *** 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](/docs/developers/api-reference/payroll-calculation/export-excel). **cURL** ```bash curl -X GET "https://app.integranom.com/api/v1/payroll-calendars/1/periods/2026-14" \ -H "Authorization: Bearer TU_API_KEY" \ -H "Content-Type: application/json" ``` **Respuesta** ```json { "period_number": "2026-14", "fiscal_year": 2026, "sequence_number": 14, "payroll_calendar_number": 1, "calendar_name": "Quincenal 2026", "legal_entity_number": 1, "frequency": "semimonthly", "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": "calculated", "payroll_run_number": 14, "employee_count": 277, "calculated_at": "2026-07-13T17:10:00.000Z", "closed_at": null, "recalc_pending": false, "totals": { "total_perceptions": "2575969.97", "total_non_cash": "0", "total_withheld_food_vouchers": "0", "total_deductions": "360871.85", "total_isr": "291712.52", "total_subsidio": "0", "total_imss_worker": "69159.31", "total_net": "2215098.20", "total_imss_employer": "1843299.76", "total_infonavit": "135150.09", "total_isn": "0", "total_employer_cost": "1978450.07", "total_company_cost": "4554420.09", "deduction_lines": [ { "code": "isr", "name": "ISR retenido", "amount": "291712.52" }, { "code": "imss_worker", "name": "IMSS trabajador", "amount": "69159.31" } ], "employer_lines": [ { "code": "imss_employer", "name": "IMSS patronal", "amount": "1843299.76" }, { "code": "infonavit_employer", "name": "INFONAVIT patronal", "amount": "135150.09" } ], "imss_employer_lines": { "partial": false, "lines": [ { "code": "imss_e_cuota_fija", "name": "Cuota fija enf. y mat.", "amount": "412508.31" }, { "code": "imss_e_riesgo_trabajo", "name": "Riesgo de trabajo", "amount": "108420.55" }, { "code": "imss_e_invalidez_vida", "name": "Invalidez y vida", "amount": "96331.12" }, { "code": "imss_e_guarderias", "name": "Guarderías y prest. sociales", "amount": "88190.42" } ] } }, "entries": [ { "employee_number": 1, "employee_name": "Juan Carlos Pérez López", "total_perceptions": "6000", "total_deductions": "627.05", "isr": "473.46", "imss_worker": "153.6", "net_pay": "5372.95", "has_retro_adjustment": false, "period_days": 16, "paid_days": 15, "absence_days": 1, "disability_days": 0, "incidence_count_internal": 1, "incidence_count_external": 0, "daily_salary": "375", "sbc_daily": "393.75", "subsidio": "0", "withheld_food_vouchers": "0", "other_deductions": "0", "imss_employer": "1063.13", "infonavit_employer": "0", "isn": "0", "total_employer_cost": "1063.13", "total_company_cost": "7063.13" } ] } ``` ## Consulta un periodo sin abrir [#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](/docs/developers/api-reference/payroll-calculation/calculate) — abre el periodo y lo calcula en una sola llamada. **cURL** ```bash curl -X GET "https://app.integranom.com/api/v1/payroll-calendars/1/periods/2026-20" \ -H "Authorization: Bearer TU_API_KEY" \ -H "Content-Type: application/json" ``` **Respuesta** ```json { "period_number": "2026-20", "fiscal_year": 2026, "sequence_number": 20, "payroll_calendar_number": 1, "calendar_name": "Quincenal 2026", "legal_entity_number": 1, "frequency": "semimonthly", "start_date": "2026-10-16T00:00:00.000Z", "end_date": "2026-10-31T00:00:00.000Z", "pay_date": "2026-11-05T00:00:00.000Z", "days_in_period": 16, "accrual_month": 10, "status": "unopened", "payroll_run_number": null, "employee_count": null, "calculated_at": null, "closed_at": null, "totals": null, "entries": [] } ``` ## Campos de la respuesta [#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` [#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` [#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`) [#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`) [#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](/docs/developers/api-reference/payroll-calculation/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 [#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. |