Autenticación

La API Key viaja en la cabecera Authorization con el esquema Bearer:

Authorization: Bearer PROD_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Es el mismo esquema que usan OpenAI, GitHub o Stripe, así que cualquier cliente HTTP ya sabe mandarlo. La palabra Bearer es opcional —Authorization: PROD_a1b2… también funciona—, pero usala igual: es la forma que entienden los interceptores y las librerías de terceros sin configuración extra.

Las claves se crean desde la app, en Administrar Empresa → API Keys, y se muestran una sola vez. Ver cómo crearlas.

Entornos: el prefijo manda

Son 37 caracteres: un prefijo más 32 hexadecimales. El prefijo es lo único que decide contra qué ARCA se opera.

Prefijo	Entorno ARCA	Certificado que usa	Validez fiscal
TEST_	Homologación	El activo de homologación	No
PROD_	Producción	El activo de producción	Sí

Esto tiene consecuencias prácticas:

• Los listados están separados. Una clave TEST_ nunca ve comprobantes de producción, ni al revés.
• Cada entorno necesita su propio certificado activo y sus los puntos de venta son los mismos para ambos, previamente habilitados en ARCA.

Podés ensayar en homologación contra la misma empresa con la que después vas a facturar de verdad, incluso reusando las mismas claves de idempotencia: los dos entornos llevan historias independientes y no se pisan.

Qué habilita una API Key

Una clave opera sólo sobre la empresa que aparece en la URL con la que se la usa, y sólo sobre los recursos de facturación:

Recurso	Ruta
Comprobantes	/:id-empresa/invoices/…	✅
Consultas a ARCA	/:id-empresa/arca/…	✅
Puntos de venta	/:id-empresa/pos/…	✅
Datos de la empresa	/:id-empresa/details	✅
Verificación de la clave	/:id-empresa/api-keys/test	✅
Bitácora de la empresa	/:id-empresa/audit-log	✅
Suscripciones, pagos, miembros, certificados	—	❌ 401

La administración de la cuenta queda deliberadamente fuera de la API: suscripciones y pagos, invitaciones y miembros, certificados, y la creación y revocación de las propias API Keys. Todo eso se hace desde la app, con tu usuario administrador. Una clave filtrada puede facturar, pero no puede cambiar quién accede a la cuenta ni tocar el certificado.

Alcance dentro de esa empresa

Todas las claves se crean con Acceso Total: no hay niveles de permiso intermedios. Cualquier clave puede usar cualquiera de los endpoints de la tabla de arriba.

Por eso la separación se hace con una clave por sistema, no con permisos: cada comprobante guarda con qué clave se emitió, y revocar una no afecta a las demás.

Buenas prácticas

• Nunca la pongas en el código. Va en una variable de entorno o en el gestor de secretos de tu plataforma. Si se filtró en un commit, revocala: rotarla es gratis e inmediato.
• Nunca la uses desde el navegador ni desde una app móvil. Cualquiera puede leerla del bundle o interceptarla. La API se llama desde tu servidor.
• Una clave por sistema. Si tenés un ERP y una tienda online, dales claves distintas: cuando algo falle vas a saber cuál fue, y podés revocar una sin frenar la otra. Cada comprobante guarda con qué clave se emitió.
• Revocá las que no uses. La revocación es inmediata.

Si perdés una clave no hay forma de recuperarla: se guardan hasheadas y sólo se muestran al crearlas. Revocala y creá otra.

Verificar que funciona

curl https://nanofactura.com/api/mi-empresa/api-keys/test \
  -H "Authorization: Bearer TEST_tu_api_key"

{ "ok": true, "environment": "homologation", "certificates": true, "pos": true }

Campo	Qué significa
environment	"production" o "homologation", derivado del prefijo.
certificates	true si hay un certificado activo para ese entorno.
pos	true si hay al menos un punto de venta que sirva para facturar por API.

Un 401 significa clave inválida, revocada, mal copiada, o usada contra un id-empresa que no le corresponde.

Es para probar, no para llamar siempre

Usalo al integrar, al pasar a producción y cuando algo falla. No lo llames antes de cada emisión: lo que verifica —certificado y puntos de venta— cambia una vez cada dos años, así que un chequeo por comprobante duplica la latencia y no evita ningún error. Si falta configuración, la emisión lo dice igual.