Copy page

Documentación

Registrar novedades del período

Las novedades son todos los conceptos que afectan el pago de una persona en un período: vacaciones, incapacidades, licencias, horas extras y recargos, ingresos adicionales, deducciones y préstamos. Esta guía explica cómo registrarlos sobre la nómina activa de una persona.

---

Paso 1: Verifica o crea el período activo

Las nóminas de cada persona se generan automáticamente cuando existe un período activo. Si tu empresa ya tiene un período en curso, puedes ir directo al Paso 2.

Para verificar si hay un período activo:

Code
curl --location 'https://nominapp-api-stage.herokuapp.com/v1/{company_id}/current_period' \
--header 'Authorization: Bearer TU_API_ACCESS_TOKEN' \
--header 'Accept: application/json'

Si recibes 404, no hay período activo. Créalo con:

Code
curl --location --request POST 'https://nominapp-api-stage.herokuapp.com/v1/{company_id}/periods' \
--header 'Authorization: Bearer TU_API_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "period": {
    "type": "next"
  }
}'

Al crear el período, las nóminas de todas las personas activas se generan automáticamente.

---

Paso 2: Obtén el ID de la nómina

Las novedades se registran sobre una nómina específica — necesitas el payroll_id de la persona en el período actual.

Code
curl --location 'https://nominapp-api-stage.herokuapp.com/v1/{company_id}/payrolls?search=Patricia+Olivera' \
--header 'Authorization: Bearer TU_API_ACCESS_TOKEN' \
--header 'Accept: application/json'

Ejemplo de respuesta:

Code
{
  "data": [
    {
      "id": "486a6163-82cb-556f-97b2-f9e98cdfc0a4",
      "worker": {
        "id": "6626a96f-32b2-5890-bc03-af9d8b2854f7",
        "full_name": "Patricia Olivera Rosales"
      },
      "contract": {
        "id": "0a9b9419-d4b1-5dcb-945b-4f802df84a23",
        "base_salary": 2500000
      }
    }
  ]
}

---

Paso 3: Consulta los conceptos disponibles

Cada novedad se registra bajo un concepto de nómina — necesitas el payroll_concept_id del concepto que quieres usar.

El parámetro category es obligatorio e indica qué tipo de conceptos retorna:

category	Qué retorna
novelties	Vacaciones, incapacidades y licencias
overtime	Horas extras y recargos
salary_income	Ingresos salariales adicionales
non_salary_income	Ingresos no salariales
occasional_non_salary_income	Ingresos no salariales ocasionales
deductions	Deducciones
loan	Préstamos

Ejemplo — Conceptos de novedades

Code
curl --location 'https://nominapp-api-stage.herokuapp.com/v1/{company_id}/payroll_concepts?category=novelties&contract_category=employee&novelty_initial_day=2024-01-02' \
--header 'Authorization: Bearer TU_API_ACCESS_TOKEN' \
--header 'Accept: application/json'

Respuesta:

Code
{
  "data": {
    "holidays": [
      {
        "id": "d4e5f6a7-b8c9-0123-defa-123456789012",
        "name": "Vacaciones disfrutadas",
        "coded_name": "enjoyed_days"
      }
    ],
    "incapacities": [
      {
        "id": "e5f6a7b8-c9d0-1234-efab-234567890123",
        "name": "Incapacidad laboral",
        "coded_name": "labor_incapacity"
      }
    ],
    "licenses": []
  }
}

Ejemplo — Conceptos de horas extras

Code
curl --location 'https://nominapp-api-stage.herokuapp.com/v1/{company_id}/payroll_concepts?category=overtime&period_id=640191cc-59a7-5090-b5e9-1036dc2053f9' \
--header 'Authorization: Bearer TU_API_ACCESS_TOKEN' \
--header 'Accept: application/json'

Respuesta:

Code
{
  "data": {
    "extra_hours": [
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "Hora extra diurna",
        "coded_name": "daily_hour"
      }
    ],
    "surcharges": [
      {
        "id": "c3d4e5f6-a7b8-9012-cdef-012345678901",
        "name": "Recargo nocturno",
        "coded_name": "nightly_surcharge"
      }
    ],
    "others": []
  }
}

---

Paso 4: Registra la novedad

Vacaciones, incapacidades y licencias

El endpoint maneja crear, actualizar y eliminar en una sola petición, la acción se determina automáticamente según los campos que envíes:

Envías	Acción
Sin id, con initial_day y end_day	Crear
Con id, con initial_day y end_day	Actualizar fechas
Con id, sin fechas	Eliminar

Ejemplo — Registrar vacaciones:

Code
curl --location --request PUT 'https://nominapp-api-stage.herokuapp.com/v1/{company_id}/payrolls/486a6163-82cb-556f-97b2-f9e98cdfc0a4/novelties' \
--header 'Authorization: Bearer TU_API_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "novelties": [
    {
      "payroll_concept_id": "e5f6a7b8-c9d0-1234-efab-234567890123",
      "initial_day": "2024-01-02",
      "end_day": "2024-01-16"
    }
  ]
}'

Ejemplo — Eliminar una novedad:

Code
curl --location --request PUT 'https://nominapp-api-stage.herokuapp.com/v1/{company_id}/payrolls/486a6163-82cb-556f-97b2-f9e98cdfc0a4/novelties' \
--header 'Authorization: Bearer TU_API_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "novelties": [
    {
      "id": "d4e5f6a7-b8c9-0123-defa-123456789012"
    }
  ]
}'

La nómina se recalcula automáticamente después de cada cambio. Consulta todos los campos disponibles en la referencia del endpoint.

---

Horas extras y recargos

El endpoint maneja crear, actualizar y eliminar en una sola petición, la acción se determina automáticamente según la cantidad que envíes:

Envías	Acción
payroll_concept_id + quantity > 0	Crear o actualizar
payroll_concept_id + quantity: 0	Eliminar

Ejemplo — Registrar horas extras diurnas:

Code
curl --location --request PUT 'https://nominapp-api-stage.herokuapp.com/v1/{company_id}/payrolls/486a6163-82cb-556f-97b2-f9e98cdfc0a4/overtime_items' \
--header 'Authorization: Bearer TU_API_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "items": [
    {
      "payroll_concept_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "quantity": 4.0
    }
  ]
}'

---

Errores comunes

Concepto inválido para el contrato o la fecha

HTTP 422 — el payroll_concept_id no aplica para ese tipo de contrato o la fecha está fuera de vigencia.

Code
{
  "error": [
    {
      "message": "payroll_concept_id es inválido",
      "code": "0101",
      "object": "payroll_concept_id",
      "index": 0
    }
  ]
}

Consulta los conceptos con los filtros contract_category y novelty_initial_day (Paso 3).

---

Fechas faltantes al crear

HTTP 422 — se intentó crear una novedad sin incluir las fechas.

Code
{
  "error": [
    {
      "message": "initial_day no puede estar en blanco",
      "code": "0102",
      "object": "initial_day",
      "index": 0
    },
    {
      "message": "end_day no puede estar en blanco",
      "code": "0102",
      "object": "end_day",
      "index": 0
    }
  ]
}

Incluye initial_day y end_day en formato YYYY-MM-DD.

---

Fechas cruzadas con una novedad existente

HTTP 422 — ya existe una novedad en ese rango de fechas.

Code
{
  "error": [
    {
      "message": "No es posible tener dos elementos con fechas cruzadas",
      "code": "0144",
      "object": "initial_day",
      "index": 0
    }
  ]
}

Consulta las novedades activas con GET /v1/{company_id}/payrolls/{payroll_id}/novelties antes de crear.

---

Nómina no encontrada

HTTP 404 — el payroll_id no existe o no pertenece al período activo.

Code
{
  "error": [
    {
      "message": "Nómina no existe",
      "code": "0001",
      "object": "payroll",
      "index": 0
    }
  ]
}

Verifica que estés usando el payroll_id del período activo (Paso 2).

---

Referencias