Launch

Este es el lanzamiento inicial de la plataforma pública de Factuarea. Por primera vez puedes integrar Factuarea con cualquier sistema externo — por código, por SDK o por agente de IA — sin scraping ni macros. Todo lo que sigue se publica junto.

REST API v1

La API REST pública en https://api.factuarea.com/v1 expone toda la superficie de facturación como JSON plano sobre HTTPS.

• Clientes (/v1/clients) — CRUD completo, búsqueda por NIF/CIF.
• Productos (/v1/products) — catálogo de productos.
• Proveedores (/v1/suppliers) — CRUD completo.
• Facturas (/v1/invoices) — CRUD + acciones (send, mark-paid, annul, create-corrective, duplicate, generate-pdf).
• Presupuestos (/v1/quotes) — CRUD + accept, reject, convert-to-invoice.
• Facturas proforma (/v1/proformas) — CRUD + convert-to-invoice.
• Albaranes (/v1/delivery_notes) — CRUD + sign, convert-to-invoice.
• Facturas de compra (/v1/purchase_invoices) — CRUD + mark-paid.
• Facturas recurrentes (/v1/recurring_invoices) — CRUD + pause/resume.
• VeriFactu (/v1/verifactu/*, /v1/invoices/{invoice}/verifactu) — registros de facturación, eventos SIF, validación de cadena, subsanación, certificados FNMT y ajustes.
• FacturaE / FACe (/v1/invoices/{invoice}/facturae, /v1/face-submissions) — descarga del XML FacturaE 3.2.2 y envíos B2G a FACe (enviar, seguir, anular).
• Informes fiscales (/v1/tax_reports/*) — generación, vista previa e histórico de los Modelos 303/347.
• Cuenta (/v1/account) — la cuenta autenticada y la verificación censal de la AEAT.
• Catálogos (/v1/taxes, /v1/series) — tipos impositivos y series de numeración.
• Webhooks (/v1/webhook_endpoints con deliveries anidados) — eventos suscribibles con firma HMAC SHA256.
• Eventos (/v1/events, /v1/event-catalog) — eventos históricos y el catálogo de tipos suscribibles.

Características de la plataforma:

• Autenticación — API keys (Bearer o X-API-Key) en dos entornos, fact_live_* (producción) y fact_test_* (sandbox de prueba).
• Modo de prueba — las claves fact_test_* se ejecutan contra una empresa sandbox aislada; los efectos externos (VeriFactu/AEAT, FACe, email, webhooks) no se ejecutan, así puedes crear y probar sin tocar los datos de producción.
• Identificadores opacos — cada recurso expone una clave id cuyo valor es un UUID v7, con foreign keys como *_id.
• Paginación por cursor — starting_after / ending_before, sin ?page=.
• Idempotencia — el header Idempotency-Key (máx. 64 caracteres) con un TTL de 24 h.
• Límites de peticiones — cuotas por tier con headers X-RateLimit-*.
• Errores normalizados — el envoltorio { error: { type, code, message, request_id, doc_url } }.
• Webhooks firmados — HMAC SHA256 con ±5 min de tolerancia y reintentos exponenciales hasta 8 intentos.
• Portal de docs — docs.factuarea.com, autoalojado con Next.js + Fumadocs y OpenAPI renderizado automáticamente.

/v1 se mantiene estable durante al menos 24 meses; cualquier breaking change vive en /v2 con una ventana de coexistencia de al menos 12 meses.

SDKs oficiales — TypeScript y PHP

Los SDKs mantenidos envuelven toda la API REST v1 con un runtime premium, así no escribes HTTP a mano. Consulta la sección de SDKs.

• TypeScript / Node.js — @factuarea/sdk en npm. ESM + CommonJS dual, declaraciones de tipos completas, Node 20+ (y Deno / Bun / Workers). Código fuente: github.com/factuarea/factuarea-node.
• PHP — factuarea/factuarea-php en Packagist. PSR-4, basado en Guzzle, PHP 8.2+. Código fuente: github.com/factuarea/factuarea-php.

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

Ambos comparten el mismo runtime: reintentos automáticos (con backoff, respetando Retry-After), claves de idempotencia automáticas, auto-paginación por cursor, una jerarquía de errores tipada, verificación de webhooks en tiempo constante y descargas binarias (PDF). Cada página de la referencia de la API muestra un snippet de TypeScript, PHP y cURL listo para copiar. Cada release fija una Factuarea-Version y la envía en cada request.

Servidor MCP para agentes de IA

El servidor MCP en https://mcp.factuarea.com expone la API pública como 218 tools de Model Context Protocol, así los agentes de IA (Claude y otros) las descubren y las llaman sin que tengas que cablear cada endpoint.

• Dos canales de auth — una API key (fact_live_ / fact_test_) para el propietario de la cuenta (hasta las 218 tools), u OAuth 2.1 para apps de terceros (un catálogo curado de 204 tools). Consulta Conectar un cliente.
• OAuth 2.1 completo — Dynamic Client Registration (RFC 7591), PKCE (S256), una pantalla de consentimiento con selección de empresa y entorno, rotación de refresh-token con detección de reutilización, además de revocación e introspección.
• Gobernado por scopes — cada tool aplica un scope granular; las tools a las que no puedes acceder quedan ocultas en tools/list. Consulta Scopes y permisos.
• Errores fieles a v1 — los errores JSON-RPC conservan el mismo code y http_status que la API REST. Consulta Errores y límites de peticiones.
• Claude Code — el plugin oficial factuarea-mcp plugin conecta en dos comandos.
• Modo de prueba — ejecuta todo contra el sandbox aislado. Consulta Modo de prueba.

Empieza en modo de prueba

La regla de oro en las tres superficies: empieza en modo de prueba. Crea contra una clave fact_test_ (o un consentimiento OAuth con el entorno Test), luego cambia a fact_live_ — sin cambios de código. Bienvenido a la era de las integraciones en Factuarea.