Autenticación con API keys

Cada cuenta de FactuROA corresponde a un NIT emisor y se autentica con API keys. No hay usuarios ni contraseñas: es una API entre sistemas.

Cómo enviar la key

Todas las peticiones llevan la key en el encabezado Authorization con el esquema Bearer:

curl "https://api.facturoa.com.co/api/v1/documents" \
  -H "Authorization: Bearer fro_tu_api_key"

Keys de pruebas y de producción

• fro_test_…: ambiente de pruebas, de pocos recursos. Los documentos se simulan (no van a la DIAN, sin validez fiscal) y llegan por correo y webhook como en producción, con un límite de documentos cada tantas horas.
• fro_live_…: producción, documentos reales ante la DIAN. Solo funciona cuando tu cuenta está habilitada.

Cada ambiente tiene su URL y solo acepta sus keys: una key en el ambiente equivocado responde 401 error.api_key.wrong_environment con la URL correcta. Las URL, el límite de pruebas y tus keys activas están en la sección de desarrollador.

Una key por sistema

La primera key te la entregamos al crear la cuenta. Con ella puedes crear otras, por ejemplo una por sistema o por ambiente, para poder revocarlas por separado:

curl -X POST "https://api.facturoa.com.co/api/v1/account/api-keys" \
  -H "Authorization: Bearer $FACTUROA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "POS sucursal centro" }'

• El secreto (key) se muestra una sola vez, en la respuesta de creación. FactuROA guarda solo su huella SHA-256, así que no se puede recuperar.
• Vence en 1 año por defecto; puedes fijar otro vencimiento de máximo 2 años.
• Deshabilítala temporalmente o revócala de forma definitiva.

Rotar una key

1. Crea una key nueva y configúrala en tu sistema.
2. Verifica que las peticiones con la key nueva funcionan.
3. Revoca la key anterior.

Casas de software

Si integras a varios emisores (por ejemplo, un POS con muchos negocios), tu cuenta es una casa de software: creas a cada cliente con Crear cuenta hija y actúas sobre cualquiera de ellos con tu propia key, agregando el encabezado Facturoa-Account con el id de la cuenta hija.

curl -X POST "https://api.facturoa.com.co/api/v1/documents/invoices" \
  -H "Authorization: Bearer $FACTUROA_API_KEY" \
  -H "Facturoa-Account: 0199a3c1-5b2e-7d40-8c11-2f6a9e0b7d13" \
  -H "Content-Type: application/json" \
  -d @factura.json

Sin el encabezado actúas sobre tu propia cuenta. Si la cuenta no es tu cliente, la API responde 403 error.account.not_child. El consumo de todos tus clientes se consulta en Consumo por período.

Errores de autenticación

Una key inválida responde 401 con un code que dice por qué (ver Errores):