Copy page

Documentación

Inicio rápido

En esta guía vas a crear una cuenta en el ambiente de pruebas y harás tu primera llamada autenticada a la API. No necesitas nada instalado aparte de curl o un cliente HTTP como Postman.

---

Paso 1: Crea tu cuenta

Envía una petición POST a /v1/registries. Este endpoint registra tu usuario y tu empresa al mismo tiempo.

Campo	Tipo	Descripción	Requerido
name	string	Nombre del usuario	✅
company_name	string	Nombre de la empresa	✅
email	string	Correo electrónico	✅
password	string	Contraseña en Base64	✅
terms_accepted	boolean	Debe ser true	✅
phone	string	Número de celular	❌
payroll_frequency	string	monthly, fortnightly, mixed	❌
workers_number	string	1-19, 20-49, 50-99, 100-149, 150-200, over_200	❌
company_id_number	string	Número de identificación de la empresa	❌

Ejemplo de petición:

Code
curl --location 'https://nominapp-api-stage.herokuapp.com/v1/registries' \
--header 'Authorization: Basic bm9taW5hcHA6ZjhjZWMwYjctNjQzYi00NDVjLTlkMWMtZDI2ZDBkMTZmZjE1' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "registry": {
    "name": "Mi Nombre",
    "company_name": "Mi Empresa",
    "email": "[email protected]",
    "password": "RHVtbXlQYXNzMUA=",
    "terms_accepted": true
  }
}'

Si la petición es exitosa, recibirás esto:

Code
{
  "data": {
    "user": {
      "id": "3a4b8cc7-fb8c-4eac-94fb-c0b6b39bbcf1",
      "email": "[email protected]"
    },
    "company": {
      "id": "32668bfe-78a4-498d-a62b-3e8c1693d723",
      "name": "Mi Empresa",
      "id_number": null
    }
  }
}

Guarda el company_id (data.company.id), lo vas a necesitar en los siguientes pasos.

---

Paso 2: Inicia sesión

La API soporta dos métodos de autenticación:

Método	Cuándo usarlo
Bearer token	Integraciones servidor a servidor, scripts, Postman
Cookies	Apps web donde el navegador maneja la sesión automáticamente

En esta guía usamos Bearer token, es el método recomendado para integraciones. Las cookies son una alternativa para apps web donde el navegador maneja la sesión automáticamente. Para profundizar en ambos métodos consulta la documentación de autenticación.

Para iniciar sesión envía una petición POST a /v1/sessions usando tu api_token.

2.1 Genera el header de autenticación codificando tu email y api_token en Base64:

Code
echo -n "[email protected]:TU_API_TOKEN" | base64
# Resultado: bWlAZW1haWwuY29tOlRVX0FQSV9UT0tFTg==

2.2 Haz la petición. El campo auth_type: bearer en el body es obligatorio — indica a la API que devuelva el token en la respuesta en lugar de setear cookies:

Code
curl --location --request POST 'https://nominapp-api-stage.herokuapp.com/v1/sessions' \
--header 'Authorization: Basic bWlAZW1haWwuY29tOlRVX0FQSV9UT0tFTg==' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{"auth_type": "bearer"}'

Ejemplo de respuesta:

Code
{
  "data": {
    "user": {
      "active": true,
      "company_id": "32668bfe-...",
      "email": "[email protected]",
      "role": "admin",
      ...
    },
    "created_at": 1742000000000,
    "is_new_user": true,
    "api_access_token": "eyJhbGciOiJIUzI1NiJ9...",
    "api_access_token_expires_at": "2026-03-19T20:00:00Z"
  }
}

---

Paso 3: Haz tu primera llamada autenticada

Usa el api_access_token y el company_id del paso 1 para consultar los datos de tu empresa:

Ejemplo de petición:

Code
curl --location 'https://nominapp-api-stage.herokuapp.com/v1/companies/32668bfe-78a4-498d-a62b-3e8c1693d723' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...' \
--header 'Accept: application/json'

Ejemplo de respuesta:

Code
{
  "data": {
    "id": "32668bfe-78a4-498d-a62b-3e8c1693d723",
    "name": "Mi Empresa",
    "id_number": null,
    "onboarding": {
      "onboarding_step": "company_data",
      "user_area": null,
      "workers_number": null
    }
  }
}

---

Paso 4: Configura tu empresa

Antes de usar la mayoría de los endpoints de nómina, periodos y personas, necesitas completar el onboarding. Son 3 llamadas al mismo endpoint PATCH /v1/companies/{company_id}.

Cómo funciona onboarding_step

Cada request incluye el campo onboarding_step, que indica a qué estado debe avanzar el onboarding — no el paso actual, sino el siguiente.

Llamada	onboarding_step	Qué configuras
1	user_area	Datos básicos de la empresa
2	invite_admin	Área del usuario
3	finished	Finaliza el onboarding

---

4.1 Completa los datos básicos de la empresa

Campo	Descripción	Valores
id_number	Número de identificación de la empresa	—
verification_digit	Dígito de verificación del NIT	—
document_type	Tipo de documento	ni, cc, ce, ti, pa
phone	Teléfono de contacto	—
economic_sector_id	ID del sector económico	GET /v1/economic_sectors
workers_number	Rango de personas activas	1-19, 20-49, 50-99, 100-149, 150-200, over_200
payroll_frequency	Frecuencia de liquidación	monthly, fortnightly, mixed

Ejemplo de petición:

Code
curl --location --request PATCH 'https://nominapp-api-stage.herokuapp.com/v1/companies/32668bfe-78a4-498d-a62b-3e8c1693d723' \
--header 'Authorization: Bearer TU_API_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "company": {
    "id_number": "236793492",
    "verification_digit": "8",
    "document_type": "ni",
    "phone": "3112233112",
    "economic_sector_id": "fa1d5fdf-8594-4332-8e12-a67a687dcd93",
    "workers_number": "20-49",
    "payroll_frequency": "monthly",
    "onboarding_step": "user_area"
  }
}'

---

4.2 Define el área del usuario

Indica a qué área pertenece el usuario que está configurando la empresa.

Valor	Área
general_management	Gerencia general
administrative	Administrativa
accounting	Contabilidad
hr	Recursos humanos
student	Estudiante
other	Otra (requiere user_area_other_info con al menos 5 caracteres)

Ejemplo de petición:

Code
curl --location --request PATCH 'https://nominapp-api-stage.herokuapp.com/v1/companies/32668bfe-78a4-498d-a62b-3e8c1693d723' \
--header 'Authorization: Bearer TU_API_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "company": {
    "user_area": "hr",
    "onboarding_step": "invite_admin"
  }
}'

---

4.3 Finaliza el onboarding

Con esta última llamada el onboarding queda completo y todos los endpoints de la API quedan disponibles.

Ejemplo de petición:

Code
curl --location --request PATCH 'https://nominapp-api-stage.herokuapp.com/v1/companies/32668bfe-78a4-498d-a62b-3e8c1693d723' \
--header 'Authorization: Bearer TU_API_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "company": {
    "onboarding_step": "finished"
  }
}'

Ejemplo de respuesta:

Code
{
  "data": {
    "id": "32668bfe-78a4-498d-a62b-3e8c1693d723",
    "name": "Mi Empresa",
    "onboarding": {
      "onboarding_step": "finished",
      "user_area": "hr",
      "workers_number": "20-49"
    },
    "onboarding_first_steps": {
      "first_worker": false,
      "first_payroll": false,
      "first_user": false,
      "company_data_configured": false,
      "finished_all_steps": false
    }
  }
}

---

¿Qué sigue?