Factuarea API

Inici ràpid

La teva primera factura en 5 minuts — verifica la teva key, aconsegueix una sèrie i un impost, crea un client, emet una factura i envia-la. Una sola seqüència de copiar i enganxar contra una key fact_test_.

Aquesta guia et porta d'una API key acabada de crear a una factura real (en sandbox) en cinc passos. Cada crida de sota és executable copiant i enganxant contra una key fact_test_ — sense emails reals, sense enviament a l'AEAT, sense consumir numeració de producció. Consulta Mode de prova & sandbox per veure què desactiva el mode "test".

Prefereixes un SDK? Si treballes amb TypeScript/Node o PHP, els SDKs oficials embolcallen tot aquest flux amb reintents integrats, idempotència, paginació per cursor i errors tipats — npm install @factuarea/sdk o composer require factuarea/factuarea-php. Els passos HTTP en brut de sota funcionen en qualsevol llenguatge i mostren exactament el que l'SDK envia per dins.

Executa-ho tot primer amb una key fact_test_. La superfície de l'API és idèntica en producció i en test — quan el teu flux funcioni de principi a fi, canvia el prefix a fact_live_ per passar a producció. Aconsegueix una key de test a Settings → Developers → API Keys.

Exporta la teva key un cop perquè cada snippet la reculli:

export FACTUAREA_API_KEY="fact_test_3pXnR2VbY7TcA9eFmN5z8KqW"

La base URL és https://api.factuarea.com/v1. Autentica't amb Authorization: Bearer (o amb el header equivalent X-API-Key). Els identificadors són valors id opacs (UUID v7); els copies d'una resposta a la següent.

Verifica la teva key

GET /v1/account introspecciona la credencial: l'empresa a la qual pertany, el pla, l'estat de l'addon de developer i els scopes i el tier de rate limit de la pròpia key. Necessita 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 és vàlida i pots veure exactament quins scopes porta. Si reps 401 invalid_api_key, revisa el valor; si un pas posterior falla amb 403 insufficient_scope, l'array scopes de dalt et diu què falta.

Aconsegueix els ids que necessitaràs

Una factura referencia una sèrie (la seva numeració) i cada línia referencia un tipus impositiu. Tots dos són recursos existents que llistes un cop i reutilitzes.

Un id de sèrie

GET /v1/series retorna les teves sèries de numeració. Tria'n una el document_type de la qual sigui invoice (la marcada com a is_default és una opció segura). Necessita 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 l'id (01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e) — aquest és el teu series_id.

Un id de tipus impositiu

GET /v1/taxes retorna el catàleg d'impostos (impostos globals del sistema + els teus personalitzats). Per a una línia de factura espanyola estàndard vols el tipus d'IVA al 21% — busca type: "vat" i rate: 21. Necessita 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 aquest id — en una línia de factura va a tax_rate_id.

tax_rate_id vs tax_rate. En una línia pots referenciar un tipus del catàleg per tax_rate_id, o saltar-te la cerca i passar el percentatge numèric directament com a tax_rate (p. ex. "tax_rate": 21). Fes servir l'un o l'altre per línia — tax_rate_id manté la línia vinculada al teu catàleg, tax_rate és un override inline ràpid.

Crea un client

La factura necessita algú a qui facturar. El body mínim de client és name més tax_id (l'identificador fiscal espanyol — NIF/CIF/NIE). Necessita clients:write.

Això és una escriptura — envia una Idempotency-Key perquè una petició reintentada no creï mai un client duplicat. Consulta Idempotència.

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"
  }
}

(Els camps opcionals que no has enviat tornen com a null; address sempre és un objecte les subclaus del qual s'omplen a mesura que les proporciones.) Copia l'id retornat (01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01) — aquest és el teu client_id.

Crea la factura

Ara combina els tres ids. POST /v1/invoices requereix client_id, series_id, issued_on, due_on i com a mínim una línia. Cada línia necessita description, quantity i unit_price; afegeix tax_rate_id (o tax_rate) per aplicar IVA. Opcionals per línia: discount_percent i product_id. Necessita 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
      }
    ]
  }'

L'API calcula per tu els totals de la línia i del document i retorna l'embolcall de la factura. Una factura acabada de crear comença com a esborrany: encara sense number definitiu (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"
  }
}

Fixa't en els camps monetaris calculats: el subtotal de la línia (10 × 100 = 1000), els seus taxes (21% de 1000 = 210) i el total (1210), agregats en el subtotal / taxes_total / total de la factura. Copia l'id de la factura (01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42) per al pas següent.

Obtén el PDF i envia'l

Amb l'id de la factura pots descarregar el seu PDF i enviar-lo per email al client.

GET /v1/invoices/{id}/pdf transmet el PDF binari (application/pdf). Necessita pdfs:read. Desa'l directament a un fitxer amb l'opció -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 envia la factura per email al client. Sense body fa servir l'email del client registrat a la fitxa; pots sobreescriure el destinatari i la còpia amb to, cc, bcc, subject i body. Necessita invoices:send.

Com que estàs amb una key fact_test_, l'email no s'entrega a cap destinatari real (els efectes del sandbox estan desactivats). La crida igualment té èxit i la factura transiciona com ho faria en producció — perfecte per muntar el teu flux sense fer spam a ningú.

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 resposta és l'embolcall actualitzat de la factura (amb la mateixa forma que dalt), ara amb sent_at poblat.

I ja està

Has verificat una key, has descobert els ids que necessita, has creat un client, has emès una factura amb totals calculats al servidor i l'has enviat — tot contra un sandbox aïllat. A partir d'aquí, apunta el mateix codi a una key fact_live_ per operar sobre la teva empresa real.

SDKs oficials

Executa aquest mateix flux amb @factuarea/sdk (TypeScript) o factuarea/factuarea-php — reintents, idempotència, paginació i errors tipats inclosos.

Mode de prova i sandbox

Què desactiva una key fact_test_, com s'aïlla l'empresa sandbox, i com promocionar la teva integració a producció.

Sol·licitar accés beta

Com aconseguir accés a la beta privada de l'API REST pública de Factuarea.

Autenticació

API keys amb prefixos fact_live_ / fact_test_, scopes granulars, rotació amb període de gràcia i llista d'accés per IP.

En aquesta pàgina

I ja està