Primeros Pasos - Nómina

Bienvenido a la API de Nómina de Alegra. Esta guía te lleva desde cero hasta
tu primera llamada exitosa en pocos minutos. No hace falta conocer la
infraestructura interna: solo necesitas una organización habilitada y un
token de integración.

¿Qué puedes hacer con la API?

Calcular, gestionar y emitir nóminas para tus empleados en Colombia, México
y República Dominicana desde tus propios sistemas (ERP, contadores, scripts,
ETL, etc.). Todo lo disponible dentro de la app de Alegra Nómina está
expuesto como endpoint REST.

1. URL base (producción)

https://payroll-calculator-api.alegra.com/v1

Todas las rutas del producto viven bajo este único dominio, en el path
/v1. Cualquier llamada fuera de este host no forma parte de la API
oficial de Nómina.

2. Autenticación con JWT de Integraciones

Cada request debe incluir un JSON Web Token (JWT) emitido por Alegra en
el header Authorization. Estos tokens se generan desde la pantalla de
Integraciones de tu organización y son la única forma válida de hablar
con la API.

GET /v1/organizations/me HTTP/1.1
Host: payroll-calculator-api.alegra.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

2.1 Cómo conseguir tu token

1. Entra a Alegra con un usuario administrador de la organización.
2. Abre Configuración → Integraciones.
3. Selecciona API de Nómina y pulsa Crear token de integración.
4. Copia el JWT y guárdalo en tu bóveda de secretos. Solo se muestra una
   vez, si lo pierdes tendrás que revocarlo y emitir uno nuevo.

Buenas prácticas:

• Nunca lo pongas en el front-end ni lo commitees a un repositorio.
• Si pierdes el token o sospechas que se filtró, revócalo desde
  Integraciones y emite uno nuevo.
• Genera un token por cada integración/consumidor, así puedes revocarlos de
  forma independiente si uno se filtra.

2.2 Claim clave: applicationVersion

El JWT incluye un claim llamado applicationVersion que indica el país
de la nómina asociada a la organización que emitió el token. Solo hay tres
valores posibles:

Este claim define reglas de cálculo, validación y archivos de salida (XML,
CFDI, etc.). Si tu organización opera en varios países, necesitas un token
por cada país, porque un mismo token solo enruta a uno.

2.3 Ejemplo: primera llamada autenticada

Una vez tengas el token, validémoslo con la ruta más simple — leer tu
propia organización:

TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBsaWNhdGlvblZlcnNpb24iOiJjb2xvbWJpYSJ9.LIio419R110abslkbaWbfaMzLChVAjmWqKbR0GBjues"

curl -X GET "https://payroll-calculator-api.alegra.com/v1/organizations/me" \
     -H "Authorization: Bearer ${TOKEN}" \
     -H "Content-Type: application/json"

Si todo está bien, recibirás un HTTP 200 con el JSON de tu organización
y los datos de configuración del país. A partir de ahí ya puedes llamar a
/employees, /payrolls, /electronic-payrolls, etc. con el mismo header.

2.4 Si algo falla en la autenticación

3. Tu recorrido después del handshake

Una vez que GET /v1/organizations/me responda 200, ya tienes lo necesario
para avanzar por los recursos del producto. Un flujo típico de integración
suele verse así:

GET  /v1/organizations/me            → confirmar país y configuración
POST /v1/employees                   → crear empleados
POST /v1/payrolls                   → liquidar nómina
POST /v1/electronic-payrolls        → emitir el documento electrónico (XML/CFDI)
GET  /v1/payrolls/:id               → consultar el resultado

Cada recurso tiene su propio contrato (request, response, validaciones y
errores). Búscalos en las siguientes secciones de esta misma carpeta
docs/api/.

4. Buenas prácticas

• Nunca pongas el token en el front-end ni lo commitees a un repositorio.
  Guárdalo en un gestor de secretos (AWS Secrets Manager, GCP Secret
  Manager, HashiCorp Vault).
• Genera un token por consumidor (proceso, script, sistema) para poder
  revocarlos de forma independiente si uno se filtra.
• Rota los tokens periódicamente desde la pantalla de Integraciones.
• Maneja los reintentos con cuidado en operaciones de escritura:
  si la respuesta se pierde, vuelve a intentar y verifica el estado del
  recurso antes de crear uno nuevo.
• Registra cada request y response en tus logs para acelerar el
  diagnóstico si reportas un problema al equipo de Alegra.