Crear
Crea calendarios de nómina (uno por razón social).
Descripcion general
Este endpoint crea calendarios de nómina dentro de tu organización. Cada objeto de creación lleva un arreglo legal_entity_numbers y crea un calendario por cada razón social de ese arreglo, cada uno con sus propios periodos generados automáticamente a partir de frequency y year. Por este comportamiento de fan-out, y a diferencia de otros endpoints, la respuesta siempre usa la envoltura { summary, created } (nunca un objeto suelto), incluso cuando envías un solo objeto. Acepta un objeto o un arreglo de objetos; el total de calendarios resultantes —la suma de las longitudes de todos los legal_entity_numbers— no puede exceder 100.
Endpoint
https://app.integranom.com/api/v1/payroll-calendarsSolicitud unica — fan-out por razon social
Envía un objeto con legal_entity_numbers. El ejemplo crea dos calendarios idénticos —uno para la razón social 1 y otro para la 2—, cada uno con sus propios periodos.
Aunque envíes un solo objeto, la respuesta siempre es la envoltura { summary, created }. summary.total es el número de calendarios que se intentaron crear (la suma de las longitudes de legal_entity_numbers) y summary.created cuántos se crearon.
{
"legal_entity_numbers": [1, 2],
"name": "Quincenal 2026",
"frequency": "semimonthly",
"isr_tariff_frequency": "semimonthly",
"year": 2026,
"pay_day_offset": 3
}Solicitud por lote
Envía un arreglo de objetos de creación. El fan-out se aplica a cada objeto por separado: el total de calendarios resultantes es la suma de las longitudes de todos los legal_entity_numbers y no puede exceder 100.
Si cualquier fila falla la validación, ningún calendario se crea y la respuesta lista los problemas por fila.
[
{ "legal_entity_numbers": [1], "name": "Quincenal 2026", "frequency": "semimonthly",
"isr_tariff_frequency": "semimonthly", "year": 2026, "pay_day_offset": 3 },
{ "legal_entity_numbers": [1], "name": "Semanal 2026", "frequency": "weekly",
"isr_tariff_frequency": "weekly", "year": 2026, "pay_day_offset": 5 }
]Reglas de los campos
| Campo | Tipo | Requerido | Notas |
|---|---|---|---|
legal_entity_numbers | arreglo de enteros positivos | Sí | Al menos un elemento (≥ 1). Una razón social por elemento; se crea un calendario para cada una. |
name | string | Sí | 3–60 caracteres. Único por razón social. |
frequency | string | Sí | Uno de weekly | biweekly | semimonthly | monthly. Inmutable tras crear. |
isr_tariff_frequency | string | No | Tabla del SAT con la que se retiene el ISR. Si se omite, usa monthly. Sólo se admiten ese valor (cada periodo se calcula solo) o monthly (se acumula el mes y se descuenta lo ya retenido). Cualquier otro valor se rechaza. |
applies_seventh_day_discount | boolean | No | Si las faltas y ausencias sin goce descuentan además un sexto del día de descanso (séptimo día proporcional). Si se omite, usa true. Un valor que no sea booleano se rechaza con 400. |
month_day_factor | number | No | Días del mes del calendario: 30 o 30.4 (el número, no texto). Con ellos se convierte a diario el sueldo mensual, se fijan los días que paga una nómina mensual y se proyecta el mes en la tarifa mensual del ISR. Si se omite, cada calendario toma el valor por defecto de su razón social (el mes del catálogo factor_dias_mes, o 30 si no es 30 ni 30.4). Cualquier otro valor se rechaza con 400 y el mensaje Los días del mes deben ser 30 o 30.4. |
year | integer | Sí | Entre 2026 y 2100. Año fiscal usado para generar los periodos; los parámetros fiscales de la plataforma empiezan en 2026. |
pay_day_offset | integer | Sí | Entre -15 y 15. Días desde el fin del periodo hasta la fecha de pago; un valor negativo paga antes del cierre del periodo. Cada periodicidad tiene un mínimo para que el pago nunca caiga antes del inicio del periodo: 0 en daily, -6 en weekly, -7 en decennial, -13 en biweekly, -12 en semimonthly y -15 en monthly. Un valor menor se rechaza con 400. |
first_period_start_day | string | No | Fecha AAAA-MM-DD en que inicia el primer periodo. Solo para weekly y biweekly, entre el 1 de diciembre del año anterior a year y el 31 de enero de year. Si se omite, el primer periodo inicia el 1 de enero. Con otra periodicidad, o fuera de ese rango, se rechaza con 400. El anchor_date de la respuesta es el inicio del primer periodo. |
timezone | string | No | Por defecto America/Mexico_City. Inmutable tras crear. |
Forma de las respuestas
201 — siempre la envoltura
Sea el cuerpo un objeto o un arreglo, la respuesta siempre envuelve los resultados en summary + created[].
{
"summary": { "total": 2, "created": 2 },
"created": [
{ "payroll_calendar_number": 3, "legal_entity_number": 1, "...": "..." },
{ "payroll_calendar_number": 4, "legal_entity_number": 2, "...": "..." }
]
}Errores
400 — validación fallida (objeto único)
Para fallas de validación de campos, errors es un objeto indexado por campo:
{
"message": "Validation failed.",
"errors": { "name": ["El nombre debe tener entre 3 y 60 caracteres."] }
}400 — validación fallida (lote)
Reporte por fila. Ningún calendario del lote fue creado.
{
"message": "Validation failed.",
"summary": { "total": 2, "with_errors": 1 },
"errors": [
{
"index": 1,
"payroll_calendar": { "name": "Semanal 2026" },
"issues": [
{
"field": "legal_entity_numbers",
"code": "LEGAL_ENTITY_NOT_FOUND",
"message": "Legal entity '99' does not exist in the organization."
}
]
}
]
}index— posición 0-based de la fila que falló dentro del arreglo enviado.payroll_calendar.name— extraído de tu entrada para que identifiques la fila sin contar.issues[]— todos los problemas de esa fila listados juntos para corregirlos antes de reintentar.
400 — total excede el máximo
Se devuelve cuando la suma de las longitudes de todos los legal_entity_numbers supera 100.
409 — nombre duplicado
Se devuelve cuando el name ya existe para alguna de las razones sociales dadas.
{
"message": "A payroll calendar with this 'name' already exists for one of the given legal entities."
}Vocabulario de códigos de error
Estos códigos aparecen dentro de issues[].code (o como code en el cuerpo de error en single) y son estables — tu cliente puede ramificar lógica con base en ellos:
| Codigo | Significado |
|---|---|
INVALID_INPUT | Falla genérica de validación de campos (formato, longitud, tipo, rango). |
LEGAL_ENTITY_NOT_FOUND | Un legal_entity_number no existe en la organización. |