by Piensa ITAutenticación
Autentica cada petición a AdapterDian con una API Key de tipo Bearer y rótala antes de que venza con las cabeceras de vencimiento.
Cada petición lleva tu API Key en la cabecera Authorization:
Authorization: Bearer <tu-api-key>Piensa IT emite una llave por servicio consumidor. La llave determina tres cosas que nunca envías en el cuerpo:
- El tenant a cuyo nombre emites. Nunca se toma de la petición, así que un consumidor no puede emitir a nombre de otro.
- El ambiente del proveedor (sandbox o producción).
- Los permisos. Emitir, descartar, reenviar por correo y responder documentos recibidos exige
invoices:write; las consultas no.
Nunca envíes la llave al navegador
La llave da acceso a todo tu tenant y puede emitir documentos fiscales. Llama a AdapterDian desde tu backend, nunca desde un cliente web o móvil. La referencia de la API te pide pegarla solo para probar operaciones, y no la guarda.
Vencimiento
Las llaves vencen (como máximo un año después de emitidas). Toda respuesta autenticada lo anuncia:
| Cabecera | Cuándo | Ejemplo |
|---|---|---|
X-Api-Key-Expires-At |
Siempre | 2027-09-01T00:00:00.000Z |
Warning |
Faltan menos de 30 días | 299 - "La API Key vence en 12 dias; rote antes del 2027-09-01" |
Registra la cabecera Warning o genera una alerta con ella: es el único aviso antes de que la llave deje de funcionar.
Errores de autenticación
| Estado | code |
Significado |
|---|---|---|
| 401 | UNAUTHORIZED |
Falta la cabecera Authorization, o la llave es inválida o está revocada. |
| 401 | API_KEY_EXPIRED |
La llave venció; detail trae la fecha. Pide una nueva. |
| 403 | FORBIDDEN |
La llave no tiene el permiso que la operación exige. |
Rotar una llave
- Pide a Piensa IT una llave nueva.
- Despliega tu servicio con ella.
- Pide que se revoque la anterior.
El adaptador solo guarda un hash de cada llave: una llave perdida no se recupera, se reemplaza.