API Keys en Facturear

La API Key es el mecanismo de autenticación principal de la API de Facturear. Toda llamada a la API debe incluir una API Key válida en el header x-api-key.

¿Qué es una API Key?

Una API Key es un token secreto que identifica y autentica a tu aplicación cuando llama a la API de Facturear. Es como una contraseña para tu integración.

Tratá las API Keys como contraseñas. No las compartas en código público, repositorios de GitHub, logs, o mensajes. Si una API Key se compromete, rotatela inmediatamente.

Cómo obtener tu API Key

Cada cuenta tiene dos API Keys: una de producción y una de testing. Las generás desde el dashboard:

La key completa se muestra una sola vez, en el momento en que la generás. Facturear no la guarda (solo guarda un hash), así que no la vas a poder ver de nuevo: copiala antes de salir de la pantalla. Después, en la tarjeta queda solo el principio y el final (por ejemplo prod_sk_…1a2b) para que sepas cuál está en uso. Si la perdiste, regenerala.

Cómo usar la API Key

La URL base de la API es https://www.facture.ar/api. Incluí la API Key en el header x-api-key de todas las requests:

curl

curl https://www.facture.ar/api/invoices \
  -H "x-api-key: prod_sk_abc123..."

JavaScript (fetch)

const response = await fetch('https://www.facture.ar/api/invoices', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.FACTUREAR_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(facturaData)
});

Python

import os
import requests

headers = {
    "x-api-key": os.environ["FACTUREAR_API_KEY"],
    "Content-Type": "application/json"
}
response = requests.post(
    "https://www.facture.ar/api/invoices",
    headers=headers,
    json=factura_data
)

Ver Primera factura con Facturear para el cuerpo de facturaData.

Prefijos de API Keys

Las API Keys de Facturear usan prefijos para identificar el entorno:

Prefijo	Entorno	Descripción
`prod_sk_`	Producción	Emite facturas reales con CAE de ARCA
`test_sk_`	Testing	Opera contra la homologación de ARCA, sin validez fiscal

El entorno lo define la key que usás: no hace falta (ni se tiene en cuenta) ningún header adicional para elegirlo.

Buenas prácticas de seguridad

Usar variables de entorno

Nunca hardcodees la API Key en el código. Usá variables de entorno:

# .env (no subir al repositorio)
FACTUREAR_API_KEY=prod_sk_abc123...

// código
const apiKey = process.env.FACTUREAR_API_KEY;

Rotación periódica

Rotá las API Keys periódicamente. Como hay una sola key por entorno, al regenerarla la anterior deja de funcionar en el acto:

Ingresá a Desarrolladores → Claves API y hacé clic en “Regenerar” en la tarjeta del entorno
Copiá la nueva key en ese momento: es la única vez que se muestra completa
Actualizá tu aplicación para usar la nueva key lo antes posible
Verificá que todo funciona con la nueva key

Usar keys distintas por entorno

Usá cada key en su lugar:

Producción (prod_sk_): solo en tu sistema real
Testing (test_sk_): en desarrollo, staging y pruebas, para no emitir comprobantes con validez fiscal por error

Revocar una API Key

Si una key se comprometió, regenerala:

Ingresá al panel de Facturear → Desarrolladores → Claves API
En la tarjeta del entorno afectado (Producción o Testing), hacé clic en “Regenerar”
La key anterior queda inválida inmediatamente; todas las requests con esa key empiezan a fallar con error 401

Errores comunes de autenticación

Error HTTP	Significado	Solución
`401 Unauthorized`, con `code: "unauthorized"`	API Key inválida, regenerada o no enviada	Verificá que enviás el header `x-api-key` con la key vigente
`403 Forbidden` al emitir, con `code: "SUBSCRIPTION_LIMIT_EXCEEDED"`	Superaste el límite de facturas de tu plan	Revisá tu plan en el dashboard

Algunas funciones se manejan solo desde el dashboard y no aceptan API Key: generar y regenerar keys, ver o rotar el secreto de firma de un webhook y su historial de entregas, y cargar tributos por CUIT. Crear, editar y borrar webhooks sí se puede hacer con la API Key.

Recursos relacionados

Emití facturas electrónicas con Facturear

Conectate a ARCA en minutos y empezá a facturar sin complicaciones.

Inicio

Con IA

Configuración

Funcionalidades

Cómo facturar

Integraciones

API Keys en Facturear: cómo obtenerlas y usarlas

API Keys en Facturear

¿Qué es una API Key?

Cómo obtener tu API Key

Cómo usar la API Key

curl

JavaScript (fetch)

Python

Prefijos de API Keys

Buenas prácticas de seguridad

Usar variables de entorno

Rotación periódica

Usar keys distintas por entorno

Revocar una API Key

Errores comunes de autenticación

Recursos relacionados

Emití facturas electrónicas con Facturear

​API Keys en Facturear

​¿Qué es una API Key?

​Cómo obtener tu API Key

​Cómo usar la API Key

​curl

​JavaScript (fetch)

​Python

​Prefijos de API Keys

​Buenas prácticas de seguridad

​Usar variables de entorno

​Rotación periódica

​Usar keys distintas por entorno

​Revocar una API Key

​Errores comunes de autenticación

​Recursos relacionados

Emití facturas electrónicas con Facturear

API Keys en Facturear

¿Qué es una API Key?

Cómo obtener tu API Key

Cómo usar la API Key

curl

JavaScript (fetch)

Python

Prefijos de API Keys

Buenas prácticas de seguridad

Usar variables de entorno

Rotación periódica

Usar keys distintas por entorno

Revocar una API Key

Errores comunes de autenticación

Recursos relacionados