Inici ràpid

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/me introspecciona la credencial. No necessita cap scope: qualsevol key vàlida es pot consultar a si mateixa, i és la manera de conèixer l'id opac dels NIF als quals arriba la key. Aquest id és el segment {company} que porta tota ruta d'empresa.

curl https://api.factuarea.com/v1/me \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

Aquesta és la resposta d'una key live d'un proveïdor de comptes, així que tots els blocs vénen omplerts. Amb la teva key fact_test_, api_key.prefix i api_key.environment diuen test.

{
  "data": {
    "object": "me",
    "account": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00",
      "name": "Asesoría Martínez",
      "environment": "live",
      "is_provider": true,
      "privileged_scopes": [
        "accounts:read",
        "accounts:write"
      ]
    },
    "api_key": {
      "id": "019e81ef-e1d4-7208-a51d-94c2c2a54a84",
      "name": "Producción",
      "prefix": "fact_live_1OSf9KdP",
      "scopes": [
        "account:read",
        "series:read",
        "series:write"
      ],
      "tier": "scale",
      "environment": "live",
      "created_at": "2026-01-15T09:30:00Z",
      "last_used_at": "2026-05-25T18:00:00Z",
      "expires_at": null
    },
    "scope": [
      {
        "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
        "tax_id": "B12345674",
        "name": "Acme Corporation"
      },
      {
        "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02",
        "tax_id": "B87654323",
        "name": "Acme Logística S.L."
      }
    ],
    "client_accounts": [
      {
        "id": "0199a1f0-1c22-7a10-b111-5a5b5c5d5e5f",
        "name": "Construcciones Ruiz",
        "origin": "granted",
        "access_level": "view",
        "status": "active",
        "paid_by_provider": false,
        "environment": "live"
      },
      {
        "id": "0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f",
        "name": "Talleres García",
        "origin": "provisioned",
        "access_level": "operate",
        "status": "provisioned",
        "paid_by_provider": true,
        "environment": "live"
      }
    ],
    "client_accounts_visible": true,
    "client_accounts_has_more": false
  }
}

Un 200 aquí significa que la key és vàlida. Llegeix la resposta així:

Camp	Què et diu
`account`	El compte de la key. `id` és el valor del segment `{account}` de les rutes de compte, `is_provider` indica si el compte aprovisiona comptes gestionats per als seus clients i `privileged_scopes` llista els scopes privilegiats que Factuarea li va concedir.
`api_key`	La key mateixa. `scopes` són els scopes efectius: un scope que no permet el pla dels NIF als quals arriba no apareix.
`scope`	Els NIF als quals arriba la key, cadascun amb el seu `id`, el seu `tax_id` i el seu `name`. Sempre s'enumeren, també quan n'hi ha un de sol.
`client_accounts`	Els comptes dels teus clients que el teu compte assoleix per una relació. `origin` és `granted` quan et van cedir accés i `provisioned` quan els vas aprovisionar i encara els gestiones. Només s'omple quan la key porta l'scope privilegiat `accounts:read`; si no, torna buida i `client_accounts_visible` és `false`.

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. La key d'aquest exemple només porta account:read, series:read i series:write: cada pas de sota indica l'scope que necessita, així que compara'l amb els scopes de la teva pròpia key. Comptes i NIF descriu cada camp.

Tria el {company}

Els NIF als quals arriba una key poden ser de tres classes, i tots van al mateix segment {company}:

El NIF és…	On llegeixes el seu `id`
Un de propi	A `scope`.
Cedit per un altre compte	A `scope`, quan l'àmbit de la key el nomena. El compte que el va cedir apareix a `client_accounts` amb `origin: "granted"`. Consulta accés cedit.
D'un compte gestionat que vas aprovisionar	A `scope`, quan l'àmbit de la key el nomena i el teu nivell al compte no és `none`. El compte apareix a `client_accounts` amb `origin: "provisioned"`, i `companies[]` de `GET /v1/accounts/{account}` en llista els NIF, amb aquest `id` com a `{account}`. Consulta comptes gestionats.

Triïs la classe que triïs, les rutes de sota són les mateixes. Un NIF que la teva key no assoleix respon 404 profile_not_found, igual que un que no existeix. En un NIF on el teu nivell és view pots llegir, però qualsevol escriptura — el contacte i la factura de sota, per exemple — respon 403 company_read_only. Amb una key fact_test_, client_accounts només llista els comptes de l'entorn test; Provar comptes gestionats els recorre. Arribar a un NIF pel segment d'empresa explica les tres classes, els seus nivells i cada resposta.

Exporta el NIF per al qual facturaràs — tota ruta d'empresa de sota porta el seu id opac al path. Aquí, la primera entrada de scope:

export COMPANY_ID="01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01"

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/companies/{company}/series retorna les teves sèries de numeració. Tria'n una el document_type de la qual sigui invoice i invoice_kind sigui complete (la marcada com a is_default és una opció segura). Necessita series:read.

curl "https://api.factuarea.com/v1/companies/$COMPANY_ID/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",
      "invoice_kind": "complete",
      "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. El camp és opcional en crear una factura: sense ell, la factura va a la teva sèrie per defecte del propòsit correcte, que es crea al moment si no en tens cap.

Un id de tipus impositiu

GET /v1/companies/{company}/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/companies/$COMPANY_ID/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 contacte amb rol de client

Crea un contacte amb name, kind, roles i identitat fiscal vàlida. Per a aquesta empresa espanyola fes servir kind: "company", roles: ["customer"] i tax_id (NIF/CIF/NIE). Necessita contacts:write.

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

curl -X POST https://api.factuarea.com/v1/companies/$COMPANY_ID/contacts \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Cliente Demo SL",
    "kind": "company",
    "roles": ["customer"],
    "tax_id": "B76543214"
  }'

{
  "data": {
    "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a03",
    "object": "contact",
    "kind": "company",
    "name": "Cliente Demo SL",
    "business_name": null,
    "commercial_name": null,
    "tax_id": "B76543214",
    "vat_id": null,
    "alternative_id": null,
    "address": {
      "line1": null,
      "line2": null,
      "number": null,
      "floor": null,
      "door": null,
      "staircase": null,
      "city": null,
      "province": null,
      "postal_code": null,
      "country": "ES"
    },
    "contact_person": null,
    "email": null,
    "phone": null,
    "mobile": null,
    "fax": null,
    "website": null,
    "billing_emails": [],
    "tags": [],
    "coordinates": null,
    "notes": null,
    "metadata": {},
    "accumulate_347": true,
    "external_id": null,
    "roles": [
      {
        "role": "customer",
        "status": "active",
        "assigned_at": "2026-08-29T10:00:00+00:00",
        "deactivated_at": null
      }
    ],
    "bank_accounts": [],
    "customer_profile": null,
    "supplier_profile": null,
    "financial_summary": {
      "sales": {
        "invoiced_amount": "0.00",
        "collected_amount": "0.00",
        "receivable_amount": "0.00",
        "currency": "EUR"
      },
      "purchases": {
        "purchased_amount": "0.00",
        "paid_amount": "0.00",
        "payable_amount": "0.00",
        "currency": "EUR"
      }
    },
    "latest_activity": null,
    "is_archived": false,
    "archived_at": null,
    "created_at": "2026-08-29T10:00:00+00:00",
    "updated_at": "2026-08-29T10:00:00+00:00"
  }
}

(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-3c5d6e7f8a03) — aquest és el contacte a qui factures, i el valor que la factura pren com a client_id.

El camp del document continua sent client_id: envia l’id canònic del contacte amb rol customer actiu.

Crea la factura

Ara combina els tres ids. POST /v1/companies/{company}/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/companies/$COMPANY_ID/invoices \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "client_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a03",
    "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-3c5d6e7f8a03",
      "name": "Cliente Demo SL"
    },
    "status": "draft",
    "issued_on": "2026-06-02",
    "due_on": "2026-07-02",
    "subtotal": "1000.00",
    "taxes_total": "210.00",
    "total": "1210.00",
    "currency": "EUR",
    "notes": null,
    "lines": [
      {
        "object": "invoice_line",
        "description": "Consultoría — junio 2026",
        "product": null,
        "quantity": 10,
        "unit_price": "100.0000",
        "tax_rate": 21,
        "discount_percent": 0,
        "subtotal": "1000.00",
        "taxes": "210.00",
        "total": "1210.00"
      }
    ],
    "metadata": {},
    "operation_regime": "general",
    "verifactu_status": "not_applicable",
    "is_corrective": false,
    "corrective": null,
    "payment": null,
    "public_link": null,
    "substituted_by": null,
    "recurring": null,
    "paid_recorded_at": null,
    "paid_date": 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. Els imports tornen com a cadenes decimals — dos decimals en un total ("1000.00") i quatre al unit_price d'una línia ("100.0000") — i el unit_price que envies pot ser un nombre o aquesta mateixa cadena. 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/companies/{company}/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/companies/$COMPANY_ID/invoices/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42/pdf \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -o invoice.pdf

POST /v1/companies/{company}/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/companies/$COMPANY_ID/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 Corporation"
  }'

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 contacte, 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ó.

Inici ràpid

I ja està

SDKs oficials

Mode de prova i sandbox

En aquesta pàgina