Autenticación y llaves

Toda petición lleva la llave en la cabecera x-api-key:

curl -s https://api-test.facto.lat/v1/llaves/actual \
  -H "x-api-key: fk_test_..."

Anatomía de una llave

fk_test_rrEEd7NH...    →  pruebas
fk_live_rrEEd7NH...    →  producción

• El prefijo dice el ambiente. Una llave solo funciona contra su ambiente: usar una fk_test_ contra producción es un 403 con código FACTO-2002.
• La llave se muestra una sola vez al crearla. Del lado del servidor solo se guarda un hash — si se pierde, se emite otra. Es deliberado.
• Cada llave pertenece a una cuenta, y la cuenta tiene asignados sus RUC emisores. Emitir por un RUC ajeno es un 403 (FACTO-2020); consultar un comprobante ajeno es un 404 — para ti, lo que no es tuyo no existe.

La primera llamada de toda integración

GET /v1/llaves/actual confirma que la llave funciona, a qué cuenta pertenece y contra qué ambiente emite. Ponla al arranque de tu integración y en tu monitoreo: es barata y no consume nada.

Errores de autenticación

Situación	HTTP	Código
Falta la llave o no es válida	401	FACTO-2001
La llave es del otro ambiente	403	FACTO-2002
El RUC emisor no es de tu cuenta	403	FACTO-2020

Cuídala como una contraseña

• Nunca en un frontend. Para que un navegador mande la llave, la llave tiene que estar en el código del navegador — donde cualquiera la lee. La llave vive en tu servidor.
• Nunca en el repositorio. Variables de entorno o gestor de secretos.
• ¿Se filtró? Pide una llave nueva y revoca la vieja. La rotación no corta el servicio: pides la nueva primero, cambias tu despliegue y revocas después.