Autenticación — API de Zelta Nómina

La API de Zelta Nómina utiliza autenticación basada en tokens Bearer (OAuth 2.0) para proteger el acceso a los datos sensibles de nómina y empleados.

Obtener un token de acceso

Paso 1: Crear una aplicación API

1. Ve a Ajustes > API > Aplicaciones.
2. Haz clic en + Nueva aplicación.
3. Completa los datos:
   • Nombre de la aplicación
   • URL de redirección (para flujo OAuth)
   • Scopes requeridos
4. Guarda y copia tu client_id y client_secret.

Seguridad

El client_secret solo se muestra una vez al momento de crearlo. Guárdalo en un lugar seguro. Si lo pierdes, deberás generar uno nuevo. Dado que la API maneja datos sensibles de nómina, se recomienda rotar las credenciales periódicamente.

Paso 2: Solicitar un token

curl -X POST https://api.zelta.dev/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "tu_client_id",
    "client_secret": "tu_client_secret",
    "scope": "nomina:read nomina:write"
  }'

Respuesta exitosa

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "nomina:read nomina:write"
}

Paso 3: Usar el token

Incluye el token en el header Authorization de cada petición:

curl -X GET https://api.zelta.dev/v1/nomina/employees \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Scopes disponibles

Scope	Descripción	Permisos
nomina:read	Lectura de datos de nómina	Consultar empleados, periodos, recibos y reportes.
nomina:write	Escritura de datos de nómina	Crear/actualizar empleados, registrar incidencias, ejecutar cálculos.
nomina:admin	Administración completa	Eliminar registros, timbrar CFDI, gestionar configuración fiscal.

Principio de mínimo privilegio

Solicita únicamente los scopes que tu aplicación necesita. Los datos de nómina son información sensible; restringe el acceso al mínimo necesario.

Renovación de tokens

Los tokens tienen una vigencia de 1 hora (3600 segundos). Para renovar:

curl -X POST https://api.zelta.dev/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "tu_refresh_token",
    "client_id": "tu_client_id"
  }'

Errores de autenticación

Código HTTP	Error	Descripción
401	unauthorized	Token ausente, expirado o inválido.
403	forbidden	El token no tiene los scopes necesarios.
429	rate_limited	Se excedió el límite de peticiones.

Ejemplo de error

{
  "error": "forbidden",
  "message": "El scope 'nomina:admin' es requerido para timbrar CFDI.",
  "hint": "Solicita un nuevo token con el scope adecuado."
}

Límites de tasa (Rate Limiting)

Plan	Límite
Starter	60 peticiones/minuto
Business	300 peticiones/minuto
Enterprise	1,000 peticiones/minuto

Los headers de respuesta incluyen información sobre tu consumo:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 290
X-RateLimit-Reset: 1709145600

Consejo

Para procesar nóminas masivas vía API, utiliza los endpoints de operaciones en lote (batch) que permiten enviar múltiples registros en una sola petición.