Saltar al contenido principal

Autenticación

Toda la superficie /v1 —menos /v1/health y /v1/docs— exige una API key.

Authorization: Bearer ctd_sk_tu_key_aqui
curl https://integration.contadito.com/v1/invoices/1042 \
  -H "Authorization: Bearer $CONTADITO_API_KEY"

El esquema Bearer no distingue mayúsculas: bearer, Bearer y BEARER funcionan igual.

La key es tu empresa​

No existe ningún parámetro de empresa en esta API. Al validar la key, el servidor determina a qué empresa corresponde. Todo lo que consultes o emitas queda referido a esa empresa.

Consecuencia práctica: una key por empresa emisora. Si facturas para varias empresas, necesitas una key por cada una y tu sistema decide cuál usar.

Anatomía de la key​

  • Prefijo fijo ctd_sk_, para que sea reconocible de un vistazo y greppeable si se filtra en un log.
  • 32 bytes de entropía detrás del prefijo.
  • Contadito solo guarda un hash SHA-256. Nadie —ni el soporte— puede leerte la key: si la perdiste, se emite otra y se revoca la vieja.

Rotación sin caídas​

  1. Emite una segunda key en la app (el límite de 2 activas existe para esto).
  2. Despliega la nueva key en tu sistema.
  3. Verifica en la lista que lastUsedAt de la nueva se está actualizando.
  4. Revoca la vieja.

Crear una key no revoca las anteriores. Revocar es siempre un acto explícito.

Errores de autenticación​

Ambos responden 401:

codeQué pasó
MISSING_API_KEYNo mandaste el header, o no viene con el esquema Bearer.
INVALID_API_KEYLa key no existe, fue revocada o expiró.
{
  "code": "INVALID_API_KEY",
  "message": "The API key is invalid, revoked, or expired."
}
aviso

Una key válida no basta para facturar. Si la integración de tu empresa no está habilitada recibirás 403 INTEGRATION_NOT_ENABLED aun con credencial correcta. Ver Primeros pasos.

Buenas prácticas​

  • Guárdala en un gestor de secretos, no en el código ni en variables del build del frontend.
  • Llama a la API desde tu backend. Una key en una app móvil o en JavaScript del navegador es una key filtrada.
  • Nunca la escribas en logs ni la pegues en un ticket de soporte. Si eso pasó, revócala: toma diez segundos.
Última actualización en