Autenticación — API de Solerba

La API de Solerba utiliza autenticación basada en tokens Bearer (OAuth 2.0) para proteger el acceso a los recursos de facturación electrónica de tu organización.

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.

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": "invoices:read invoices:write"
  }'

Respuesta exitosa

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "invoices:read invoices: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/solerba/invoices \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Scopes disponibles

Scope	Descripción	Permisos
invoices:read	Lectura de facturas	Consultar CFDI emitidos, obtener XML/PDF, ver estado de facturas y cancelaciones.
invoices:write	Emisión de facturas	Crear y timbrar CFDI (ingreso, egreso, pago, traslado), cancelar facturas, emitir notas de crédito y complementos de pago.
catalogs:read	Lectura de catálogos	Consultar catálogos de clientes, productos/servicios, regímenes fiscales y claves SAT.
reports:read	Lectura de reportes	Consultar reportes fiscales, de ingresos, resúmenes de impuestos y exportar datos.

Principio de mínimo privilegio

Si solo necesitas consultar facturas emitidas para un dashboard externo, usa invoices:read. Reserva invoices:write para aplicaciones que necesiten emitir comprobantes. Combina varios scopes separándolos con espacios.

Combinaciones comunes de scopes

Caso de uso	Scopes recomendados
Dashboard de facturación	invoices:read reports:read
Sistema de facturación	invoices:read invoices:write catalogs:read
Sistema contable	invoices:read reports:read catalogs:read
Integración completa	invoices:read invoices:write catalogs:read reports:read

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"
  }'

Manejo de expiración

Implementa un mecanismo de renovación automática en tu aplicación. Cuando recibas un error 401, solicita un nuevo token antes de reintentar la petición. Evita solicitar un token nuevo en cada petición, ya que esto consume tu límite de tasa innecesariamente.

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 para esta operación.
429	rate_limited	Se excedió el límite de peticiones por minuto.

Ejemplo de error

{
  "error": "forbidden",
  "message": "El scope 'invoices:write' es requerido para timbrar facturas.",
  "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: 295
X-RateLimit-Reset: 1709145600

Consejo

Para operaciones de facturación masiva, usa el endpoint de batch (/invoices/batch) en lugar de crear facturas individuales. Esto es más eficiente y consume menos de tu límite de tasa.

Ambientes

Ambiente	Base URL	Descripción
Producción	https://api.zelta.dev/v1/solerba	Facturas reales timbradas ante el SAT
Sandbox	https://sandbox.api.zelta.dev/v1/solerba	Facturas de prueba sin timbrado real

Ambiente de pruebas

El ambiente sandbox usa RFC genéricos de prueba del SAT y no genera CFDI válidos ante la autoridad fiscal. Úsalo para desarrollo e integración. Nunca uses credenciales de producción en sandbox ni viceversa.