Platform launch

The public platform uses unified Contacts as its single CRM resource.

For the first time you can integrate Factuarea with any external system — by code, by SDK, by command line or by AI agent — without scraping or macros. The public surface is one contract at https://api.factuarea.com/v1, reachable four ways: the REST API, the TypeScript and PHP SDKs, the factuarea CLI, and the MCP server. Each surface talks to the same resources and enforces the same scopes.

REST API v1

The public REST API exposes 469 operations across 41 resources as plain JSON over HTTPS. Every resource is identified by an opaque id (a UUID v7 string).

Sales documents

• Invoices (/v1/invoices) — full CRUD and the complete lifecycle: send, mark paid, void, annul, duplicate, PDF and public link, payments and receipts, reminders. Corrective invoices (rectificativas) with the R1–R5 correction reason codes, simplified-invoice eligibility and substitution, scheduled issuing (schedule / reschedule / unschedule), and quarterly export (ZIP and email). Bulk create, send, status change, delete and PDF, plus Excel export.
• Quotes (/v1/quotes) — CRUD + accept, reject, convert to invoice, PDF, public link.
• Pro-forma invoices (/v1/proformas) — CRUD + convert to invoice, PDF, public link.
• Delivery notes (/v1/delivery_notes) — CRUD + sign, mark delivered, convert to invoice.
• Recurring invoices (/v1/recurring_invoices) — CRUD + activate, pause, resume, cancel and preview the next occurrence.

Purchases

• Purchase invoices (/v1/purchase_invoices) — CRUD with PDF attachment, mark paid, payment registration, and pending / overdue reporting.

CRM and catalog

• Contacts (/v1/contacts) — one identity with cumulative customer, supplier and lead roles; full CRUD, role/profile management, search by tax ID or external ID, AEAT census verification, bulk operations and CSV import.
• Products (/v1/products) — CRUD, lookup by SKU or external id, stock control (set, adjust and bulk update), low-stock report, sales analytics, and gallery images and video.
• Document series (/v1/series) — legal numbering series per document type, with monthly / annual reset, default selection and archive / unarchive.
• Taxes (/v1/taxes) — tax rates (IVA, IRPF retention, equivalence surcharge) with per-document defaults.

Spanish tax compliance

• VeriFactu (/v1/verifactu/*, /v1/invoices/{invoice}/verifactu) — billing records, the SIF hash chain and its validation, subsanación (correction records), the declaración responsable and its history, and FNMT certificate management.
• FacturaE / FACe (/v1/invoices/{invoice}/facturae, /v1/face-submissions) — FacturaE 3.2.2 XML download and B2G submissions to public administrations via FACe (submit, track, cancel).
• AEAT census (/v1/account/census-verification, /v1/contacts/census-verification) — verify a NIF/CIF against the AEAT registry.
• Tax reports (/v1/tax_reports/*) — generate, preview, download and keep history of Modelo 303 (VAT), 347 (annual operations with third parties) and 130 (IRPF instalment).

Payments

• Stripe auto-invoicing (/v1/stripe-autoinvoicing/*) — connect Stripe accounts and issue invoices automatically from Stripe payments, including automatic corrective invoices on refunds.
• Payouts and reconciliation (/v1/payouts, /v1/connected-accounts) — read Stripe payouts and reconcile settlements, with Norma 43 bank-statement support.

Managed companies (gestorías)

• Companies (/v1/companies) — provision and run child companies from a master account: create, activate, deactivate, track creation status, and issue per-company API keys (create, rotate, revoke). Preview seat billing before you commit with /v1/companies/seat-charge-preview. Operate on a child's behalf on a single request with the X-Active-Profile header.

Webhooks and events

• Webhooks (/v1/webhook_endpoints with nested deliveries) — subscribable endpoints signed with HMAC SHA256, dual-secret rotation, ping / test, and a delivery history you can replay.
• Events (/v1/events, /v1/event-catalog) — the historical event stream and the catalog of subscribable event types.

Account

• Account (/v1/account) — introspect the authenticated credential (company, plan, scopes and rate-limit tier), manage API keys, personalize document templates, and run your own census verification.

API foundations

Behaviour every resource shares, so an integration learns it once:

• Test mode — fact_test_* keys run against an isolated sandbox company; external effects (VeriFactu/AEAT, FACe, email, webhooks) are not executed, so you build and test without touching production data.
• Opaque identifiers — every resource exposes an id whose value is a UUID v7, with foreign keys as *_id.
• Cursor pagination — starting_after / ending_before, no ?page=.
• Idempotency — the Idempotency-Key header (max 64 chars, 24h TTL); a replay returns the original stored response — including a cached 4xx — marked with Idempotent-Replayed.
• Rate limits — per-tier per-minute and monthly quotas with X-RateLimit-* headers.
• Normalized errors — the { error: { type, code, message, param, request_id, doc_url } } envelope; validation errors point at the offending field through param. Branch on code, never on the human-facing message.
• Bulk operations — batch endpoints report partial success per item, so one bad row doesn't fail the whole request.
• Import and export — CSV client import (with a downloadable template) and Excel invoice export.
• Signed webhooks — HMAC SHA256 with ±5min tolerance and exponential retries up to 8 attempts.
• Scopes — a closed resource:action catalog; every operation you can't reach is hidden, and destructive write / delete scopes are flagged as sensitive on the OAuth consent screen and never pre-checked.
• Versioning — the URL prefix /v1 plus a pinned Factuarea-Version header. /v1 stays stable for at least 24 months; any breaking change lives in /v2 with a coexistence window of at least 12 months.

Official SDKs — TypeScript & PHP

Maintained SDKs wrap the full v1 REST API with a premium runtime, so you don't hand-roll HTTP. See the SDKs section.

• TypeScript / Node.js — @factuarea/sdk on npm. Dual ESM + CommonJS, full type declarations, Node 20+ (and Deno / Bun / Workers). Source: github.com/factuarea/factuarea-node.
• PHP — factuarea/factuarea-php on Packagist. PSR-4, Guzzle-based, PHP 8.2+. Source: github.com/factuarea/factuarea-php.

npm install @factuarea/sdk
composer require factuarea/factuarea-php

Both share the same runtime: automatic retries (with backoff, honouring Retry-After), automatic idempotency keys, cursor auto-pagination, a typed error hierarchy, constant-time webhook verification, and binary (PDF) downloads. Every page in the API reference shows a ready-to-copy TypeScript, PHP and cURL snippet. Each release pins one Factuarea-Version and sends it on every request.

Command-line interface

The official factuarea CLI (v0.1.3) drives the full v1 surface from your terminal. It is agent-first — stable JSON output, semantic exit codes and one-call discovery — and the command tree is generated from the OpenAPI spec, so it never drifts from the live surface.

• One key, two environments — the key prefix selects the environment; a fact_live_ mutation also requires the explicit --live flag as a safety net.
• Devloop — listen forwards events to your machine and trigger produces real sandbox events, so you test webhooks locally with no tunnel or ngrok.
• Install — Homebrew, npm or a curl installer. See the CLI.

MCP server for AI agents

The MCP server at https://mcp.factuarea.com exposes the public API as 457 Model Context Protocol tools over the Streamable HTTP transport, so AI agents (Claude and others) discover and call them without you wiring each endpoint.

• Two auth channels — an API key (fact_live_ / fact_test_) for the account owner (up to all 457 tools), or OAuth 2.1 for third-party apps (a curated 368-tool catalog). See Connecting a client.
• Full OAuth 2.1 — Dynamic Client Registration (RFC 7591), PKCE (S256), a consent screen with company and environment selection, refresh-token rotation with reuse detection, plus revocation and introspection.
• Scope-governed — every tool enforces a fine-grained scope; tools you can't reach are hidden from tools/list. See Scopes & permissions.
• v1-faithful errors — JSON-RPC errors preserve the same code and http_status as the REST API. See Errors & rate limits.
• Claude Code — the official factuarea-mcp plugin connects in two commands.
• Test mode — drive everything against the isolated sandbox. See Test mode.

Start in test mode

The golden rule across all four surfaces: start in test mode. Build against a fact_test_ key (or an OAuth consent with the Test environment), then switch to fact_live_ — no code changes. Welcome to the integrations era in Factuarea.