Launch

Aquest és el llançament inicial de la plataforma pública de Factuarea. Per primera vegada pots integrar Factuarea amb qualsevol sistema extern — per codi, per SDK o per agent d'IA — sense scraping ni macros. Tot el que segueix es publica junt.

REST API v1

L'API REST pública a https://api.factuarea.com/v1 exposa tota la superfície de facturació com a JSON pla sobre HTTPS.

• Clients (/v1/clients) — CRUD complet, cerca per NIF/CIF.
• Productes (/v1/products) — catàleg de productes.
• Proveïdors (/v1/suppliers) — CRUD complet.
• Factures (/v1/invoices) — CRUD + accions (send, mark-paid, annul, create-corrective, duplicate, generate-pdf).
• Pressupostos (/v1/quotes) — CRUD + accept, reject, convert-to-invoice.
• Factures proforma (/v1/proformas) — CRUD + convert-to-invoice.
• Albarans (/v1/delivery_notes) — CRUD + sign, convert-to-invoice.
• Factures de compra (/v1/purchase_invoices) — CRUD + mark-paid.
• Factures recurrents (/v1/recurring_invoices) — CRUD + pause/resume.
• VeriFactu (/v1/verifactu/*, /v1/invoices/{invoice}/verifactu) — registres de facturació, esdeveniments SIF, validació de cadena, subsanació, certificats FNMT i ajustos.
• FacturaE / FACe (/v1/invoices/{invoice}/facturae, /v1/face-submissions) — descàrrega de l'XML FacturaE 3.2.2 i enviaments B2G a FACe (enviar, seguir, anul·lar).
• Informes fiscals (/v1/tax_reports/*) — generació, vista prèvia i històric dels Models 303/347.
• Compte (/v1/account) — el compte autenticat i la verificació censal de l'AEAT.
• Catàlegs (/v1/taxes, /v1/series) — tipus impositius i sèries de numeració.
• Webhooks (/v1/webhook_endpoints amb deliveries imbricats) — esdeveniments subscribibles amb signatura HMAC SHA256.
• Esdeveniments (/v1/events, /v1/event-catalog) — esdeveniments històrics i el catàleg de tipus subscribibles.

Característiques de la plataforma:

• Autenticació — API keys (Bearer o X-API-Key) en dos entorns, fact_live_* (producció) i fact_test_* (sandbox de prova).
• Mode de prova — les claus fact_test_* s'executen contra una empresa sandbox aïllada; els efectes externs (VeriFactu/AEAT, FACe, email, webhooks) no s'executen, així pots crear i provar sense tocar les dades de producció.
• Identificadors opacs — cada recurs exposa una clau id el valor de la qual és un UUID v7, amb foreign keys com a *_id.
• Paginació per cursor — starting_after / ending_before, sense ?page=.
• Idempotència — el header Idempotency-Key (màx. 64 caràcters) amb un TTL de 24 h.
• Límits de peticions — quotes per tier amb headers X-RateLimit-*.
• Errors normalitzats — l'embolcall { error: { type, code, message, request_id, doc_url } }.
• Webhooks signats — HMAC SHA256 amb ±5 min de tolerància i reintents exponencials fins a 8 intents.
• Portal de docs — docs.factuarea.com, autoallotjat amb Next.js + Fumadocs i OpenAPI renderitzat automàticament.

/v1 es manté estable durant almenys 24 mesos; qualsevol breaking change viu a /v2 amb una finestra de coexistència d'almenys 12 mesos.

SDKs oficials — TypeScript i PHP

Els SDKs mantinguts envolten tota l'API REST v1 amb un runtime premium, així no escrius HTTP a mà. Consulta la secció de SDKs.

• TypeScript / Node.js — @factuarea/sdk a npm. ESM + CommonJS dual, declaracions de tipus completes, Node 20+ (i Deno / Bun / Workers). Codi font: github.com/factuarea/factuarea-node.
• PHP — factuarea/factuarea-php a Packagist. PSR-4, basat en Guzzle, PHP 8.2+. Codi font: github.com/factuarea/factuarea-php.

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

Tots dos comparteixen el mateix runtime: reintents automàtics (amb backoff, respectant Retry-After), claus d'idempotència automàtiques, auto-paginació per cursor, una jerarquia d'errors tipada, verificació de webhooks en temps constant i descàrregues binàries (PDF). Cada pàgina de la referència de l'API mostra un snippet de TypeScript, PHP i cURL llest per copiar. Cada release fixa una Factuarea-Version i l'envia en cada request.

Servidor MCP per a agents d'IA

El servidor MCP a https://mcp.factuarea.com exposa l'API pública com a 218 tools de Model Context Protocol, així els agents d'IA (Claude i altres) les descobreixen i les criden sense que hagis de cablejar cada endpoint.

• Dos canals d'auth — una API key (fact_live_ / fact_test_) per al propietari del compte (fins a les 218 tools), o OAuth 2.1 per a apps de tercers (un catàleg curat de 204 tools). Consulta Connectar un client.
• OAuth 2.1 complet — Dynamic Client Registration (RFC 7591), PKCE (S256), una pantalla de consentiment amb selecció d'empresa i entorn, rotació de refresh-token amb detecció de reutilització, a més de revocació i introspecció.
• Governat per scopes — cada tool aplica un scope granular; les tools a les quals no pots accedir queden ocultes a tools/list. Consulta Scopes i permisos.
• Errors fidels a v1 — els errors JSON-RPC conserven el mateix code i http_status que l'API REST. Consulta Errors i límits de peticions.
• Claude Code — el plugin oficial factuarea-mcp plugin connecta en dues comandes.
• Mode de prova — executa-ho tot contra el sandbox aïllat. Consulta Mode de prova.

Comença en mode de prova

La regla d'or a les tres superfícies: comença en mode de prova. Crea contra una clau fact_test_ (o un consentiment OAuth amb l'entorn Test), després canvia a fact_live_ — sense canvis de codi. Benvingut a l'era de les integracions a Factuarea.