Launch

Control horari — 2026-07-11

Factuarea ja cobreix el deure de l'empresari espanyol de portar un registre diari de jornada — RD-ley 8/2019, art. 34.9 de l'Estatut dels Treballadors — i exposa tot el sistema de personal sobre el mateix contracte v1. És el VeriFactu del control horari: un ledger de sola addició segellat per una cadena de hash SHA-256 per empresa, on res no s'edita ni s'esborra i qualsevol manipulació trenca la cadena. Tota la superfície està protegida pel nou mòdul control_horario. Comença pel resum de control horari.

• Vuit dominis nous — empleats (amb invitacions i facturació per assentament), horaris de treball, fitxatges (entrada/sortida, pauses, fitxatges retroactius i correccions), tancaments mensuals del registre, exportacions per a nòmines, absències (tipus, polítiques, sol·licituds, saldos i calendari), presència i festius.
• Scopes nous — un conjunt dedicat dins del catàleg tancat: employees:*, time_entries:*, work_schedules:*, absences:*, presence:read, holidays:read i payroll_exports:read, tots darrere el mòdul control_horario. Consulta Scopes i irreversibilitat.
• Tancament mensual segellat — congela un mes finalitzat i segella'l amb una signatura RSA-SHA256 desacoblada sobre la instantània; el segellat és irreversible (un per tancament) i verificable de manera independent. Exporta el registre diari en el format rdley_8_2019, o un fitxer d'incidències per a nòmines A3, Sage o NominaSOL. Consulta Tancament mensual del registre.
• Rol d'empleat només al portal — un empleat fitxa, segueix un horari i sol·licita absències des del portal, i mai compta contra el límit users del pla.
• Add-on per assentament — els empleats es facturen mitjançant una subscripció mensual dedicada (employee-seats) la quantitat de la qual segueix el teu cens actiu; contractar-la activa el mòdul. Un compte enterprise facturat per contracte l'obté gratis. Consulta Facturació d'assentaments d'empleat.
• Paritat MCP — cada ruta v1 reflecteix una tool MCP pública, així que un agent executa les mateixes operacions. Consulta el catàleg de tools MCP.

API i MCP inclosos en tots els plans — 2026-07-04

L'API pública i el servidor MCP deixen de vendre's com a add-on developer_api a banda — ara estan inclosos en tots els plans de Factuarea:

• Tier per pla — el teu tier de rate limit es deriva del teu pla: Emprendedor → starter (30 req/min, 5.000 req/mes), Empresario → pro (300 req/min, 50.000 req/mes), Enterprise → scale (personalitzat, sense topalls). Consulta Límits de peticions.
• Trial inclòs — durant el trial de 10 dies tens accés a l'API amb el tier free (10 req/min, 100 req/mes).
• Boost de capacitat — si necessites més capacitat sense canviar de pla, subscriu-te des del dashboard a un tier estrictament superior al que atorga el teu pla; un tier igual o inferior retorna 422 boost_not_applicable. Consulta Boost de capacitat.
• L'add-on desapareix — els add-ons de developer Starter i Pro deixen de vendre's. El codi d'error addon_not_active es manté (ara significa que l'empresa no té un pla actiu que inclogui accés a l'API), així que les integracions existents no necessiten cap canvi.
• Programa beta tancat — l'accés a l'API ja no se sol·licita: crea una key des de Dashboard → Developers → API Keys i comença a cridar /v1.

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 413 operacions en 37 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

• Clients (/v1/clients) — CRUD complet, cerca per NIF/CIF, verificació censal de l'AEAT i VIES, i importació CSV amb plantilla descarregable.
• Proveïdors (/v1/suppliers) — CRUD complet, cerca per NIF/CIF.
• 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/clients/*) — 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 391 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 391 tools), o OAuth 2.1 per a apps de tercers (un catàleg curat de 305 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.