Factuarea API

The Factuarea REST API to automate your multi-tenant invoicing SaaS for Spanish businesses.

The Factuarea REST API exposes invoicing resources (clients, products, invoices, quotes, pro-forma invoices, delivery notes, recurring invoices, purchase invoices) over HTTPS with API key authentication. The entire public surface lives at https://api.factuarea.com/v1 and returns JSON. Every resource is identified by an opaque id (a UUID v7 string).

Quickstart — your first invoice in 5 minutes

One copy-paste sequence against a fact_test_ key: verify your key, grab a series and a tax, create a client, issue an invoice and send it.

Quick start

Request beta access

The API is currently in private beta. Write to info@factuarea.com following the Request beta access instructions. If your company is already in the allowlist, skip to the next step.

Create your first API key

Open Dashboard → Developers → API Keys and create a key with the scopes you need (for example invoices:read,clients:read to start). Copy the secret only once — you won't be able to see it again.

Pick the Test environment to get a fact_test_ key that operates on an isolated sandbox with no real-world effects. Build against it first, then create a fact_live_ key to go to production. See Test mode & sandbox.

Verify your key

Before anything else, confirm the key works. GET /v1/account introspects the credential — it returns the company it belongs to, the plan, and the scopes and rate-limit tier of the key itself (needs account:read):

curl https://api.factuarea.com/v1/account \
  -H "Authorization: Bearer fact_test_xxxxxxxxxxxxxxxxxxxxxxxx"

✅ You should see a 200 with an account snapshot:

{
  "data": {
    "object": "account",
    "company": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
      "name": "Acme Soluciones SL",
      "tax_id": "B12345678"
    },
    "plan": { "slug": "empresario", "name": "Empresario" },
    "api_key": {
      "id": "01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c",
      "name": "Sandbox integration",
      "prefix": "fact_test_3pXnR2Vb",
      "scopes": ["account:read", "clients:read", "invoices:read"],
      "tier": "starter"
    }
  }
}

If you get 401 invalid_api_key, re-check the value. The scopes array tells you exactly what this key can do — a later call that fails with 403 insufficient_scope is missing one of them.

Make your first data request

Now list a real resource. GET /v1/clients returns a standard envelope with data (results), has_more and next_cursor (cursor pagination):

curl https://api.factuarea.com/v1/clients \
  -H "Authorization: Bearer fact_test_xxxxxxxxxxxxxxxxxxxxxxxx"

Ready to issue your first invoice end-to-end? Follow the Quickstart. If you receive an error, look it up in Errors by the returned code.

Configure webhooks (optional)

If your integration needs to react to events (invoice paid, quote accepted, etc.), configure a webhook endpoint signed with HMAC SHA256. See Webhooks.

What the API covers

Clients and suppliers

Full CRUD, search by tax ID, VIES validation.

Catalog

Products with prices, stock, SKU and tax rates.

Sales documents

Invoices, quotes, pro-forma invoices, delivery notes, recurring invoices — with lines, retentions and equivalence surcharge.

Document actions

Send by email, mark as paid/accepted, generate PDF, void, create corrective invoice, convert between types.

Purchases

Vendor bills with PDF upload, mark_paid, mark_received.

Document series

Legal numbering series per document type (read-only via API to guarantee tax continuity).

FACe invoicing (B2G)

FacturaE 3.2.2 XML download and FACe submissions — submit, track the processing status and request cancellations.

MCP server for AI agents

The whole API as 218 Model Context Protocol tools, with OAuth 2.1 and API-key auth — connect Claude and other agents in seconds.

Contract design

The API follows the patterns you would expect from a modern provider:

Opaque identifiers — the id key carries a UUID v7 string instead of an incremental integer. See Pagination for cursor semantics.
Normalized errors — every error returns an envelope with type, code, message, param, doc_url and request_id. See Errors.
Idempotency keys — supported on every POST to prevent duplicates on retries. See Idempotency.
Rate limits per tier — per-minute and monthly quotas, with X-RateLimit-* headers on every response. See Rate limits.
URL versioning — /v1/*. Breaking changes trigger /v2/* with a documented deprecation policy. See Versioning.
Webhooks with dual-secret rotation — HMAC SHA256, exponential retry with up to 8 attempts. See Webhooks.

SDKs

We ship official TypeScript and PHP SDKs (@factuarea/sdk and factuarea/factuarea-php) with retries, idempotency, cursor pagination, typed errors and webhook verification built in. If your language isn't covered, any standard HTTP client (curl, Postman, axios, requests, Guzzle) works — the API is plain REST over JSON.

The public REST API complements the Factuarea web client (app.factuarea.com) — it doesn't replace it. Operations not exposed by the API (plan management, branding, global company tax configuration) still live in the app.