Llançament de la plataforma

La plataforma pública fa servir Contactes unificats com a únic recurs de CRM.

Per primera vegada pots integrar Factuarea amb qualsevol sistema extern — per codi, per SDK, per línia de comandes o per agent d'IA — sense scraping ni macros. La superfície pública és un únic contracte a https://api.factuarea.com/v1, accessible de quatre maneres: l'API REST, els SDKs de TypeScript i PHP, el CLI factuarea i el servidor MCP. Cada superfície parla amb els mateixos recursos i aplica els mateixos scopes.

REST API v1

L'API REST pública exposa 469 operacions en 41 recursos com a JSON pla sobre HTTPS. Cada recurs s'identifica per una clau id opaca (un UUID v7).

Documents de venda

• Factures (/v1/invoices) — CRUD complet i el cicle de vida complet: enviar, marcar com a pagada, cancel·lar, anul·lar, duplicar, PDF i enllaç públic, cobraments i rebuts, recordatoris. Factures rectificatives amb els codis de motiu de rectificació R1–R5, elegibilitat i substitució de factura simplificada, emissió programada (schedule / reschedule / unschedule) i exportació trimestral (ZIP i email). Creació, enviament, canvi d'estat, esborrat i PDF en lot, a més d'exportació a Excel.
• Pressupostos (/v1/quotes) — CRUD + acceptar, rebutjar, convertir a factura, PDF, enllaç públic.
• Factures proforma (/v1/proformas) — CRUD + convertir a factura, PDF, enllaç públic.
• Albarans (/v1/delivery_notes) — CRUD + signar, marcar com a lliurat, convertir a factura.
• Factures recurrents (/v1/recurring_invoices) — CRUD + activar, pausar, reprendre, cancel·lar i previsualitzar la propera execució.

Compres

• Factures de compra (/v1/purchase_invoices) — CRUD amb adjunt PDF, marcar com a pagada, registre de pagaments i informes de pendents / vençudes.

CRM i catàleg

• Contactes (/v1/contacts) — una identitat amb rols acumulables de client, proveïdor i lead; CRUD complet, gestió de rols i perfils, cerca per NIF/CIF o external ID, verificació censal de l'AEAT, operacions massives i importació CSV.
• Productes (/v1/products) — CRUD, cerca per SKU o external id, control d'stock (fixar, ajustar i actualització en lot), informe d'stock baix, analítica de vendes, i imatges de galeria i vídeo.
• Sèries de documents (/v1/series) — sèries de numeració legal per tipus de document, amb reinici mensual / anual, selecció de predeterminada i arxivar / desarxivar.
• Impostos (/v1/taxes) — tipus impositius (IVA, retenció d'IRPF, recàrrec d'equivalència) amb predeterminats per document.

Compliment fiscal espanyol

• VeriFactu (/v1/verifactu/*, /v1/invoices/{invoice}/verifactu) — registres de facturació, la cadena d'empremtes del SIF i la seva validació, subsanació (registres de correcció), la declaració responsable i el seu històric, i la gestió de certificats FNMT.
• FacturaE / FACe (/v1/invoices/{invoice}/facturae, /v1/face-submissions) — descàrrega de l'XML FacturaE 3.2.2 i enviaments B2G a les administracions públiques mitjançant FACe (enviar, seguir, anul·lar).
• Cens de l'AEAT (/v1/account/census-verification, /v1/contacts/census-verification) — verifica un NIF/CIF contra el registre de l'AEAT.
• Informes fiscals (/v1/tax_reports/*) — genera, previsualitza, descarrega i mantén l'històric dels Models 303 (IVA), 347 (operacions anuals amb tercers) i 130 (pagament fraccionat d'IRPF).

Pagaments

• Autofacturació de Stripe (/v1/stripe-autoinvoicing/*) — connecta comptes de Stripe i emet factures automàticament a partir dels pagaments de Stripe, incloses factures rectificatives automàtiques en les devolucions.
• Payouts i conciliació (/v1/payouts, /v1/connected-accounts) — llegeix els payouts de Stripe i concilia les liquidacions, amb suport d'extractes bancaris Norma 43.

Empreses gestionades (gestories)

• Empreses (/v1/companies) — aprovisiona i opera empreses filles des d'un compte mestre: crear, activar, desactivar, seguir l'estat de creació i emetre API keys per empresa (crear, rotar, revocar). Previsualitza el cost per seat abans de confirmar amb /v1/companies/seat-charge-preview. Opera en nom d'una filla en una sola petició amb el header X-Active-Profile.

Webhooks i esdeveniments

• Webhooks (/v1/webhook_endpoints amb deliveries imbricats) — endpoints subscribibles signats amb HMAC SHA256, rotació de doble secret, ping / test, i un històric d'entregues que pots reenviar.
• Esdeveniments (/v1/events, /v1/event-catalog) — el flux històric d'esdeveniments i el catàleg de tipus d'esdeveniment subscribibles.

Compte

• Compte (/v1/account) — introspecciona la credencial autenticada (empresa, pla, scopes i tier de límit de peticions), gestiona API keys, personalitza les plantilles de document i executa la teva pròpia verificació censal.

Fonaments de l'API

Comportament que comparteixen tots els recursos, així una integració l'aprèn una sola vegada:

• 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í crees i proves 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, TTL de 24 h); una petició repetida retorna la resposta original emmagatzemada — inclosa una 4xx en memòria cau — marcada amb Idempotent-Replayed.
• Límits de peticions — quotes per tier, per minut i mensuals, amb headers X-RateLimit-*.
• Errors normalitzats — l'embolcall { error: { type, code, message, param, request_id, doc_url } }; els errors de validació assenyalen el camp problemàtic mitjançant param. Ramifica segons code, mai segons el message orientat a persones.
• Operacions en lot — els endpoints per lots informen de l'èxit parcial per element, així una fila incorrecta no fa fallar tota la petició.
• Importació i exportació — importació CSV de clients (amb plantilla descarregable) i exportació de factures a Excel.
• Webhooks signats — HMAC SHA256 amb ±5 min de tolerància i reintents exponencials fins a 8 intents.
• Scopes — un catàleg tancat resource:action; tota operació a la qual no pots accedir queda oculta, i els scopes destructius write / delete es marquen com a sensibles a la pantalla de consentiment d'OAuth i mai es pre-marquen.
• Versionat — el prefix d'URL /v1 més un header Factuarea-Version fixat. /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.

Interfície de línia de comandes

El CLI factuarea oficial (v0.1.3) opera tota la superfície v1 des del teu terminal. És agent-first — sortida JSON estable, exit codes semàntics i descobriment en una sola crida — i l'arbre de comandes es genera des de l'spec OpenAPI, així que mai es desincronitza de la superfície en viu.

• Una clau, dos entorns — el prefix de la clau selecciona l'entorn; una mutació fact_live_ requereix a més el flag explícit --live com a xarxa de seguretat.
• Devloop — listen reenvia esdeveniments a la teva màquina i trigger produeix esdeveniments reals de sandbox, així proves webhooks en local sense túnel ni ngrok.
• Instal·lació — Homebrew, npm o un instal·lador curl. Consulta el CLI.

Servidor MCP per a agents d'IA

El servidor MCP a https://mcp.factuarea.com exposa l'API pública com a 457 tools de Model Context Protocol sobre el transport Streamable HTTP, 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 457 tools), o OAuth 2.1 per a apps de tercers (un catàleg curat de 368 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 quatre 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.