Factuarea API

Inicio rápido

Tu primera factura en 5 minutos — verifica tu key, consigue una serie y un impuesto, crea un cliente, emite una factura y envíala. Una sola secuencia de copiar y pegar contra una key fact_test_.

Esta guía te lleva de una API key recién creada a una factura real (en sandbox) en cinco pasos. Cada llamada de abajo es ejecutable copiando y pegando contra una key fact_test_ — sin emails reales, sin envío a la AEAT, sin consumir numeración de producción. Consulta Modo de prueba & sandbox para ver qué desactiva el modo "test".

¿Prefieres un SDK? Si trabajas con TypeScript/Node o PHP, los SDKs oficiales envuelven todo este flujo con reintentos integrados, idempotencia, paginación por cursor y errores tipados — npm install @factuarea/sdk o composer require factuarea/factuarea-php. Los pasos HTTP en crudo de abajo funcionan en cualquier lenguaje y muestran exactamente lo que el SDK envía por dentro.

Ejecuta todo primero con una key fact_test_. La superficie de la API es idéntica en producción y en test — cuando tu flujo funcione de principio a fin, cambia el prefijo a fact_live_ para pasar a producción. Consigue una key de test en Settings → Developers → API Keys.

Exporta tu key una vez para que cada snippet la recoja:

export FACTUAREA_API_KEY="fact_test_3pXnR2VbY7TcA9eFmN5z8KqW"

La base URL es https://api.factuarea.com/v1. Autentícate con Authorization: Bearer (o con el header equivalente X-API-Key). Los identificadores son valores id opacos (UUID v7); los copias de una respuesta a la siguiente.

Verifica tu key

GET /v1/account introspecciona la credencial: la empresa a la que pertenece, el plan, el estado del addon de developer y los scopes y el tier de rate limit de la propia key. Necesita el scope account:read.

curl https://api.factuarea.com/v1/account \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"
{
  "data": {
    "object": "account",
    "company": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
      "name": "Acme Soluciones SL",
      "tax_id": "B12345678"
    },
    "plan": {
      "slug": "empresario",
      "name": "Empresario"
    },
    "addon": {
      "active": true,
      "in_grace": false,
      "expires_at": null
    },
    "api_key": {
      "id": "01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c",
      "name": "Sandbox integration",
      "prefix": "fact_test_3pXnR2Vb",
      "scopes": [
        "account:read",
        "series:read",
        "taxes:read",
        "clients:write",
        "invoices:write",
        "invoices:send",
        "pdfs:read"
      ],
      "tier": "starter",
      "created_at": "2026-05-01T09:30:00Z",
      "last_used_at": "2026-06-02T08:12:00Z",
      "expires_at": null
    }
  }
}

Un 200 aquí significa que la key es válida y puedes ver exactamente qué scopes lleva. Si recibes 401 invalid_api_key, revisa el valor; si un paso posterior falla con 403 insufficient_scope, el array scopes de arriba te dice qué falta.

Consigue los ids que vas a necesitar

Una factura referencia una serie (su numeración) y cada línea referencia un tipo impositivo. Ambos son recursos existentes que listas una vez y reutilizas.

Un id de serie

GET /v1/series devuelve tus series de numeración. Elige una cuyo document_type sea invoice (la marcada como is_default es una opción segura). Necesita series:read.

curl "https://api.factuarea.com/v1/series?document_type=invoice" \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"
{
  "data": [
    {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e",
      "object": "series",
      "code": "F-2026",
      "name": "Facturas 2026",
      "document_type": "invoice",
      "prefix": "F-2026-",
      "next_number": 46,
      "year_reset": true,
      "is_default": true,
      "is_active": true,
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-20T11:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Copia el id (01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e) — ese es tu series_id.

Un id de tipo impositivo

GET /v1/taxes devuelve el catálogo de impuestos (impuestos globales del sistema + los tuyos personalizados). Para una línea de factura española estándar quieres el tipo de IVA al 21% — busca type: "vat" y rate: 21. Necesita taxes:read.

curl "https://api.factuarea.com/v1/taxes?type=vat" \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"
{
  "data": [
    {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f",
      "object": "tax",
      "name": "IVA general 21%",
      "code": "IVA21",
      "rate": 21,
      "type": "vat",
      "applies_to": "both",
      "country": "ES",
      "is_default": true,
      "is_active": true,
      "is_system": true
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Copia este id — en una línea de factura va en tax_rate_id.

tax_rate_id vs tax_rate. En una línea puedes referenciar un tipo del catálogo por tax_rate_id, o saltarte la búsqueda y pasar el porcentaje numérico directamente como tax_rate (p. ej. "tax_rate": 21). Usa uno u otro por línea — tax_rate_id mantiene la línea vinculada a tu catálogo, tax_rate es un override inline rápido.

Crea un cliente

La factura necesita alguien a quien facturar. El body mínimo de cliente es name más tax_id (el identificador fiscal español — NIF/CIF/NIE). Necesita clients:write.

Esto es una escritura — envía una Idempotency-Key para que una petición reintentada nunca cree un cliente duplicado. Consulta Idempotencia.

curl -X POST https://api.factuarea.com/v1/clients \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Cliente Demo SL",
    "tax_id": "B98765432"
  }'
{
  "data": {
    "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
    "object": "client",
    "name": "Cliente Demo SL",
    "commercial_name": null,
    "tax_id": "B98765432",
    "vat_id": null,
    "email": null,
    "phone": null,
    "contact_person": null,
    "billing_emails": [],
    "address": {
      "line1": null,
      "postal_code": null,
      "city": null,
      "province": null,
      "country": null
    },
    "coordinates": null,
    "notes": null,
    "metadata": {},
    "is_active": true,
    "created_at": "2026-06-02T10:30:00Z",
    "updated_at": "2026-06-02T10:30:00Z"
  }
}

(Los campos opcionales que no enviaste vuelven como null; address siempre es un objeto cuyas subclaves se rellenan a medida que las proporcionas.) Copia el id devuelto (01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01) — ese es tu client_id.

Crea la factura

Ahora combina los tres ids. POST /v1/invoices requiere client_id, series_id, issued_on, due_on y al menos una línea. Cada línea necesita description, quantity y unit_price; añade tax_rate_id (o tax_rate) para aplicar IVA. Opcionales por línea: discount_percent y product_id. Necesita invoices:write.

curl -X POST https://api.factuarea.com/v1/invoices \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "client_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
    "series_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e",
    "issued_on": "2026-06-02",
    "due_on": "2026-07-02",
    "lines": [
      {
        "description": "Consultoría — junio 2026",
        "quantity": 10,
        "unit_price": 100,
        "tax_rate_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f",
        "discount_percent": 0
      }
    ]
  }'

La API calcula por ti los totales de la línea y del documento y devuelve el envoltorio de la factura. Una factura recién creada empieza como borrador: todavía sin number definitivo (is_number_assigned: false).

{
  "data": {
    "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
    "object": "invoice",
    "number": null,
    "is_number_assigned": false,
    "type": "F1",
    "series": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e",
      "code": "F-2026"
    },
    "client": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
      "name": "Cliente Demo SL"
    },
    "status": "draft",
    "issued_on": "2026-06-02",
    "due_on": "2026-07-02",
    "subtotal": 1000,
    "taxes_total": 210,
    "total": 1210,
    "currency": "EUR",
    "notes": null,
    "lines": [
      {
        "object": "invoice_line",
        "description": "Consultoría — junio 2026",
        "product": null,
        "quantity": 10,
        "unit_price": 100,
        "tax_rate": 21,
        "discount_percent": 0,
        "subtotal": 1000,
        "taxes": 210,
        "total": 1210
      }
    ],
    "metadata": {},
    "operation_regime": "general",
    "verifactu_status": "not_applicable",
    "is_corrective": false,
    "corrective": null,
    "payment": null,
    "public_link": null,
    "substituted_by": null,
    "recurring": null,
    "paid_at": null,
    "paid_on": null,
    "sent_at": null,
    "voided_at": null,
    "void_reason": null,
    "created_at": "2026-06-02T10:31:00Z",
    "updated_at": "2026-06-02T10:31:00Z"
  }
}

Fíjate en los campos monetarios calculados: el subtotal de la línea (10 × 100 = 1000), sus taxes (21% de 1000 = 210) y el total (1210), agregados en el subtotal / taxes_total / total de la factura. Copia el id de la factura (01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42) para el siguiente paso.

Obtén el PDF y envíalo

Con el id de la factura puedes descargar su PDF y enviárselo por email al cliente.

GET /v1/invoices/{id}/pdf transmite el PDF binario (application/pdf). Necesita pdfs:read. Guárdalo directamente a un fichero con la opción -o de curl:

curl https://api.factuarea.com/v1/invoices/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42/pdf \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -o invoice.pdf

POST /v1/invoices/{id}/send envía la factura por email al cliente. Sin body usa el email del cliente registrado en ficha; puedes sobreescribir el destinatario y la copia con to, cc, bcc, subject y body. Necesita invoices:send.

Como estás con una key fact_test_, el email no se entrega a ningún destinatario real (los efectos del sandbox están desactivados). La llamada igualmente tiene éxito y la factura transiciona como lo haría en producción — perfecto para montar tu flujo sin hacer spam a nadie.

curl -X POST https://api.factuarea.com/v1/invoices/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42/send \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "to": "demo@example.com",
    "subject": "Tu factura de Acme Soluciones SL"
  }'

La respuesta es el envoltorio actualizado de la factura (con la misma forma que arriba), ahora con sent_at poblado.

Y ya está

Verificaste una key, descubriste los ids que necesita, creaste un cliente, emitiste una factura con totales calculados en el servidor y la enviaste — todo contra un sandbox aislado. A partir de aquí, apunta el mismo código a una key fact_live_ para operar sobre tu empresa real.

SDKs oficiales

Ejecuta este mismo flujo con @factuarea/sdk (TypeScript) o factuarea/factuarea-php — reintentos, idempotencia, paginación y errores tipados incluidos.

Modo de prueba y sandbox

Qué desactiva una key fact_test_, cómo se aísla la empresa sandbox, y cómo promocionar tu integración a producción.

Solicitar acceso beta

Cómo conseguir acceso a la beta privada de la API REST pública de Factuarea.

Autenticación

API keys con prefijos fact_live_ / fact_test_, scopes granulares, rotación con periodo de gracia y lista de acceso por IP.

En esta página

Y ya está