Copy page

Documentación

Registrar una persona y su contrato

Esta guía explica cómo registrar una persona en la empresa lista para incluirse en nómina. El proceso tiene tres pasos: consultar los catálogos necesarios, crear la persona con su contrato, y verificar que quedó registrada correctamente.

---

Paso 1: Consulta las instituciones de seguridad social

El contrato requiere los IDs de la EPS, fondo de pensiones, fondo de cesantías y ARL.

Obtener instituciones de seguridad social

Ejemplo de petición:

Code
curl --location 'https://nominapp-api-stage.herokuapp.com/v1/institutions?category=health_provider' \
--header 'Authorization: Bearer TU_API_ACCESS_TOKEN' \
--header 'Accept: application/json'

Cambia category según la institución que necesites:

Valor	Institución
health_provider	EPS
pension_provider	Fondo de pensiones
severance_provider	Fondo de cesantías
arl	Administradora de riesgos laborales
compensation_fund	Caja de compensación familiar

Ejemplo de respuesta:

Code
{
  "data": [
    {
      "id": "91c77755-5ca2-42fc-8221-f4f2c030bb6c",
      "name": "Sura EPS",
      "code": "EPS037"
    },
    {
      "id": "b3d12f44-9e1a-4a2b-bc91-2d3e5f6a7b8c",
      "name": "Nueva EPS",
      "code": "EPS002"
    }
  ]
}

---

Paso 2: Crea la persona

La persona y su primer contrato se crean en una sola petición. No es necesario crear primero la persona y luego el contrato por separado.

Campos requeridos

Campo	Descripción
name	Nombre de la persona
last_name	Apellido de la persona
document_type	Tipo de documento: cc, ce, ti, pa, pep, pt
id_number	Número de documento
initial_day	Fecha de inicio del contrato (YYYY-MM-DD)
category	Tipo de contrato: employee, contractor, apprentice, student, part_time_contract
term	Duración: indefinite, fixed, project
base_salary	Salario base en pesos colombianos
health_provider_id	ID de la EPS
pension_provider_id	ID del fondo de pensiones
severance_provider_id	ID del fondo de cesantías
arl_id	ID de la ARL

Ejemplo de petición:

Code
curl --location --request POST 'https://nominapp-api-stage.herokuapp.com/v1/{company_id}/workers' \
--header 'Authorization: Bearer TU_API_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "worker": {
    "name": "Patricia",
    "last_name": "Olivera Rosales",
    "document_type": "cc",
    "id_number": "52799616",
    "email": "[email protected]",
    "phone": "3009011100",
    "initial_day": "2024-01-15",
    "category": "employee",
    "term": "indefinite",
    "base_salary": 2500000,
    "transport_subsidy": true,
    "wage_category": "ordinary",
    "health_provider_id": "91c77755-5ca2-42fc-8221-f4f2c030bb6c",
    "pension_provider_id": "b86c3b81-3584-5ed6-91a3-f07f54c115e3",
    "severance_provider_id": "16881701-ff67-5895-913b-dfdf4ab03797",
    "arl_id": "c29d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f"
  }
}'

Ejemplo de respuesta:

Code
{
  "data": {
    "id": "6626a96f-32b2-5890-bc03-af9d8b2854f7",
    "name": "Patricia",
    "last_name": "Olivera Rosales",
    "full_name": "Patricia Olivera Rosales",
    "document_type": "cc",
    "id_number": "52799616",
    "email": "[email protected]",
    "active": true,
    "contract": {
      "id": "0a9b9419-d4b1-5dcb-945b-4f802df84a23",
      "category": "employee",
      "term": "indefinite",
      "initial_day": "2024-01-15",
      "end_day": null,
      "base_salary": 2500000
    }
  }
}

---

Paso 3: Verifica el registro

Consulta la persona recién creada para confirmar que quedó activa y con el contrato correcto:

Ejemplo de petición:

Code
curl --location 'https://nominapp-api-stage.herokuapp.com/v1/{company_id}/workers/6626a96f-32b2-5890-bc03-af9d8b2854f7' \
--header 'Authorization: Bearer TU_API_ACCESS_TOKEN' \
--header 'Accept: application/json'

Verifica que:

• active es true
• contract.initial_day es la fecha correcta
• contract.base_salary coincide con lo registrado

---

Errores comunes

Documento ya registrado

HTTP 422 — ya existe una persona con ese número de documento.

Code
{
  "error": [
    {
      "message": "id_number ya está en uso",
      "code": "0103",
      "object": "id_number",
      "index": 0
    }
  ]
}

Verifica si la persona ya está registrada con GET /v1/{company_id}/workers?search={id_number}.

---

ID de institución inválido

HTTP 422 — el ID de la EPS, fondo de pensiones, cesantías o ARL no existe.

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

Consulta el catálogo de instituciones con el category correspondiente (Paso 1).

---

Salario inválido

HTTP 422 — el salario enviado es 0 o negativo.

Code
{
  "error": [
    {
      "message": "base_salary debe ser mayor a 0",
      "code": "0102",
      "object": "base_salary",
      "index": 0
    }
  ]
}

Verifica que el salario esté en pesos colombianos.

---

Fecha de inicio faltante

HTTP 422 — falta la fecha de inicio del contrato.

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

Incluye initial_day en formato YYYY-MM-DD.

---

Referencias