Saltar al contenido principal

Headers de Autenticación

Todas las peticiones a la API de Lummy requieren headers HTTP específicos para autenticación e identificación.

Headers Requeridos​

HeaderTipoObligatorioDescripción
x-organization-idstring (UUID)✅ID único de tu organización
Authorizationstring✅Token de autenticación (Bearer Token)
x-idempotencystring (UUID)✅UUID único para prevenir duplicados
Content-Typestring✅Siempre application/json

x-organization-id​

Identifica tu organización dentro de Lummy. Lo encuentras en el dashboard:

Dashboard → Configuración → Información de la Organización

x-organization-id: 550e8400-e29b-41d4-a716-446655440000

Authorization​

El token de acceso obtenido en el login debe enviarse en este header con el prefijo Bearer.

Authorization: Bearer eyJraWQiOiJ...
Seguridad
  • Nunca compartas tu Access Token públicamente
  • Siempre usa HTTPS para proteger el token en tránsito
  • El token expira después de cierto tiempo; asegúrate de renovarlo

x-idempotency​

UUID único que garantiza que una factura no se duplique si reenvías la misma petición.

x-idempotency: 7c9e6679-7425-40de-944b-e07fc1f90ae7

¿Cómo Funciona?​

Si envías dos requests con el mismo x-idempotency:

  • La primera petición crea la factura
  • La segunda petición retorna la misma factura sin duplicar (HTTP 200 o 201)

Si envías dos requests con diferente x-idempotency:

  • Cada petición crea una factura nueva (si los datos son válidos)

Generación de UUIDs​

import { v4 as uuidv4 } from 'uuid';

const idempotencyKey = uuidv4();
// '7c9e6679-7425-40de-944b-e07fc1f90ae7'

Headers Opcionales​

HeaderTipoDescripción
x-branch-idstring (UUID)Especifica una sucursal específica (por defecto: matriz)
x-user-idstring (UUID)ID del usuario que realiza la acción (para auditoría)

Ejemplo Completo​

POST /invoices HTTP/1.1
Host: sandbox-api.lummy.com
Content-Type: application/json
Authorization: Bearer eyJraWQiOiJ...
x-organization-id: 550e8400-e29b-41d4-a716-446655440000
x-idempotency: 7c9e6679-7425-40de-944b-e07fc1f90ae7
x-branch-id: 123e4567-e89b-12d3-a456-426614174000
x-user-id: 987fcdeb-51a2-43d7-8c9e-d5a1b2c3d4e5

{
  "tipoDeComprobante": "I",
  ...
}

Errores Comunes​

❌ 401 Unauthorized - Token Inválido o Expirado​

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Solución: Verifica que envíes el header Authorization correctamente y que el token no haya expirado. Si expiró, realiza login nuevamente.

❌ 400 Bad Request - Header Faltante​

{
  "statusCode": 400,
  "message": "Missing required header: x-idempotency"
}

Solución: Incluye todos los headers requeridos en la petición.

❌ 409 Conflict - Idempotencia Duplicada​

{
  "statusCode": 409,
  "message": "Idempotency key already used",
  "existingInvoiceId": "d290f1ee-6c54-4b01-90e6-d701748f0851"
}

Solución: Genera un nuevo UUID si quieres crear una factura diferente, o consulta la factura existente con el invoiceId retornado.

Próximos Pasos​