Docs
Solicitar acceso

Inicio rápido: tu primera factura electrónica por API

FactuROA es una API entre sistemas: tu POS, ERP o tienda en línea envía los datos del documento y FactuROA genera el XML, lo firma con tu certificado, lo envía a la DIAN y te avisa del resultado. Esta guía te lleva de la API key a tu primera factura aceptada.

Antes de empezar

  • Tu cuenta y tu API key: crea la cuenta con Crear cuenta (elige si eres casa de software), confirma el correo con el código que te llega, inicia sesión y crea tu API key (fro_…) en Crear API key.
  • El certificado de firma digital de la empresa en formato .p12 y su contraseña.
  • La resolución de numeración de la DIAN (prefijo, rango, vigencia y clave técnica).
  • El logo de la empresa en PNG o JPEG (opcional): va en el PDF y en el correo al adquiriente. Sin logo se muestra el nombre.

Todas las rutas parten de https://api.facturoa.com.co/api/v1. El ambiente (habilitación o producción) lo define tu cuenta: no cambia la URL.

1. Prueba tu API key

Guarda la key en una variable de entorno y consulta tu cuenta. Si responde 200 con tu NIT, estás listo.

curl "https://api.facturoa.com.co/api/v1/account" \
  -H "Authorization: Bearer $FACTUROA_API_KEY"

Más detalles en Autenticación.

2. Configura tu cuenta emisora

Esto se hace una sola vez por cuenta, en este orden:

  1. Perfil del emisor: dirección, responsabilidades fiscales y datos del software ante la DIAN.
  2. Logo (opcional): va en el PDF y en el correo.
  3. Certificado .p12: se valida y se guarda cifrado; nunca se devuelve.
  4. Webhook: obligatorio para emitir con API key; por ahí te avisamos el resultado de cada documento.
  5. Rango de numeración: uno por cada resolución y tipo de documento. Si tienes más de un rango activo del mismo tipo, indica su id al emitir (numbering_range_id).

3. Emite la factura

Envía la factura con un external_id propio (tu número de pedido o venta). La API la valida y responde de inmediato con el documento en estado pending. El número y el CUFE se asignan al enviarla a la DIAN, así que tu numeración no queda con huecos.

En un punto de venta puedes agregar ?wait=10: la API espera hasta 10 segundos el resultado de la DIAN y, si llega, responde 200 con número, CUFE y estado final.

curl -X POST "https://api.facturoa.com.co/api/v1/documents/invoices" \
  -H "Authorization: Bearer $FACTUROA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "pedido-77",
  "numbering_range_id": "0199a3c1-5b2e-7d40-8c11-2f6a9e0b7d13",
  "customer": {
    "person_type": 2,
    "document_type": "13",
    "document_number": "1020304050",
    "name": "Ana Pérez",
    "email": "ana@example.com"
  },
  "lines": [{
    "description": "Café",
    "quantity": "2",
    "unit_code": "EA",
    "unit_price": "5000.00",
    "taxes": [{ "code": "01", "rate": "19" }]
  }]
}'
{
  "id": "0199a3d4-7c1e-7b2a-9f10-5c3e8d2a1b40",
  "external_id": "pedido-77",
  "full_number": null,
  "status": "pending"
}

4. Recibe el resultado

La firma y el envío a la DIAN ocurren en segundo plano, con reintentos. El documento pasa de pending a submitted y termina en accepted, rejected (con los motivos de la DIAN) o failed. Para enterarte tienes dos opciones:

  • Webhook (recomendado): configura una URL y recibe un aviso firmado cuando el documento llega a su estado final. Ver Webhooks.
  • Consulta: GET /documents/{id} devuelve el estado y la respuesta de la DIAN.

Con la factura aceptada puedes descargar el PDF con QR, el XML firmado y el AttachedDocument. Si el adquiriente tiene correo, FactuROA se lo envía automáticamente.

Si la DIAN la rechaza, corrige los datos y reenvíala con PUT /documents/{id}. Ver Errores.