Saltar al contenido principal
Ver toda la doc en texto plano

API Keys

La API Key es la credencial con la que tu sistema factura. Se crean y se revocan desde la app, en Administrar Empresa → API Keys.

Crear una​

En Administrar Empresa → API Keys → Nueva clave elegís dos cosas:

DescripciónPara qué es. Poné el nombre del sistema: ERP producción, Tienda online. Cuando tengas varias, es lo único que las distingue.
EntornoTEST_ (homologación, sin validez fiscal) o PROD_ (producción, fiscal).
La clave se muestra una sola vez

no hay forma de recuperarla después. Copiala en ese momento y guardala en tu gestor de secretos o en la variable de entorno. Si la perdés, revocala y creá otra.

Después de crearla, en el listado sólo vas a ver una versión enmascarada (PROD_••••••••5f9e), suficiente para identificar cuál es cuál.

Elegir el entorno​

Empezá siempre por TEST_. Los comprobantes de homologación no tienen validez fiscal y podés equivocarte todo lo que haga falta.

PrefijoEntorno ARCAValidez fiscal
TEST_HomologaciónNo
PROD_ProducciónSí

El prefijo es lo único que decide el entorno: no hay ningún parámetro que lo cambie desde el pedido. Pasar a producción es cambiar el valor de una variable de entorno, sin tocar el código.

Cada entorno necesita su propio certificado activo y sus puntos de venta habilitados en ARCA.

Alcance​

Todas las API Keys se crean con Acceso Total: pueden usar cualquiera de los endpoints habilitados para claves —emitir y consultar comprobantes, administrar puntos de venta, consultar ARCA y leer la bitácora—. No hay niveles de permiso intermedios.

Lo que ninguna clave puede hacer, por diseño: tocar el certificado, cambiar la suscripción, invitar usuarios ni crear otras claves. Eso se hace desde la app, con tu usuario. Ver alcance de las API Keys.

Como toda clave tiene acceso total, la separación se hace creando una clave por sistema y revocando la que sobre.

Buenas prácticas​

  • Una clave por sistema. Si tenés un ERP y una tienda online, dales claves distintas: cada comprobante guarda con cuál se emitió, así que cuando algo falle vas a saber de dónde vino, y podés revocar una sin frenar la otra.
  • Nunca en el código ni en el repositorio. Va en una variable de entorno o en el gestor de secretos de tu plataforma.
  • Nunca en el navegador ni en una app móvil. Cualquiera puede leerla del bundle o interceptarla. La API se llama desde tu servidor.
  • Revocá las que no uses.
.env — nunca lo subas al repositorio
NANOFACTURA_API_KEY=TEST_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
NANOFACTURA_ID_EMPRESA=mi-empresa

Si se filtró​

Revocala. Desde Administrar Empresa → API Keys, el efecto es inmediato: la próxima petición con esa clave responde 401.

Lo que la clave filtrada no pudo hacer, por diseño: tocar tu certificado, cambiar la suscripción, invitar usuarios, ni crear otras claves. Todo eso está fuera del alcance de una API Key.

Lo que sí pudo hacer es emitir comprobantes. Revisá el listado filtrando por esa clave:

GET /:id-empresa/invoices?apiKeyId=3&ordering=-created

Si hay comprobantes que no reconocés, hay que emitir las notas de crédito correspondientes (cómo). Escribinos a [email protected] si necesitás ayuda.

También queda registro en la bitácora de la empresa, con qué se hizo, cuándo y con qué clave:

GET /:id-empresa/audit-log

Verificar una clave​

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 }

Es la primera llamada que conviene hacer al integrar: valida la clave y confirma que la empresa tenga certificado y puntos de venta para ese entorno. Un 401 significa clave inválida, revocada, mal copiada o usada contra otro id-empresa.

Y ahora​

Ya tenés todo. Andá a Primeros pasos y emití tu primera factura.