Abast i limitacions

El que l'API de Factuarea no fa a propòsit, el que encara no fa, i la manera equivalent de resoldre cada cas — més quatre capacitats que pots donar per absents i no ho estan.

Tota plataforma té fronteres. Una frontera que pots llegir abans d'integrar és una decisió de disseny; una que descobreixes en producció és un defecte. Aquesta pàgina és l'única llista canònica — cap altra guia no manté la seva.

Cada fila declara l'escenari, el seu estat i el workaround: l'alternativa disponible avui, o una declaració explícita que no n'hi ha. Hi ha exactament dos estats, perquè una tercera categoria difusa és el que converteix pàgines com aquesta en mer ornament:

Per disseny — no ho construirem. L'alternativa és aquí.
En full de ruta — ajornat, no descartat.

Verificat el 31 de juliol de 2026 contra la v1 de l'API. Una fila amb un escenari que passi a estar suportat es retira en el mateix canvi que l'implementa, en lloc de quedar-s'hi com a limitació obsoleta.

Limitacions verificades contra el codi

Escenari	Estat	Workaround
Autofactura — el destinatari expedeix la factura en nom del proveïdor	Per disseny	No està modelada. El proveïdor expedeix la seva pròpia factura. Si operes totes dues parts, emet-la des del compte del proveïdor.
Factura expedida per un tercer	Per disseny	El camp AEAT d'expedició per tercer no s'emet. Una assessoria que opera el compte d'un client emet des d'aquell compte amb `X-Active-Profile`; la factura es declara com a expedida per la mateixa empresa.
Multidivisa	Per disseny	El contracte v1 exposa l'euro, fix: `currency` és sempre `EUR` i no hi ha cap columna de divisa. Filtrar un llistat per qualsevol altra divisa retorna una pàgina buida, no un error. Factura en euros i converteix fora de Factuarea.
TicketBAI / Batuz (País Basc)	Per disseny	Cap alternativa dins de Factuarea. Els sistemes forals bascos fan servir esquemes, certificats i endpoints diferents, i requereixen el seu propi programari certificat. Les empreses amb domicili fiscal basc reben l'avís durant l'onboarding.
Inversió del subjecte passiu, i qualsevol règim d'operació de capçalera, declarats per l'API	Per disseny	L'`operation_regime` de capçalera és de només lectura a la v1 —ni la creació ni l'actualització no l'accepten—, així que tota factura creada per l'API neix en règim general i es qualifica `S1`. L'exempció i la no subjecció es declaren per línia amb `lines[].exemption_reason`, però la inversió del subjecte passiu és la qualificació `S2` i no té equivalent de línia: emet aquestes factures des del tauler. Vegeu Clients internacionals.
Suplerts fora de la factura emesa — pressupostos, proformes, albarans, factures de compra, plantilles de recurrents	Per disseny	Només la factura emesa modela els suplerts. Inclou l'import com a línia ordinària al document previ, i fixa `line_type` a la factura resultant mentre encara és un esborrany — l'operació d'actualització l'accepta.
Suplerts a l'XML de Facturae i UBL — l'import a pagar de l'XML és el total fiscal, no l'import degut	En full de ruta	La base imposable i les quotes surten correctes —el suplert queda ben exclòs—, però l'import a pagar es queda curt per aquell import i cap element de l'XML no transporta la diferència. No remetis per FACe una factura amb línies de suplert mentre no es mapegi el bloc natiu de Facturae 3.2.2: factura el suplert fora d'aquell canal.
Suplerts a les xifres agregades de cartera — el `pending_amount` de `GET /v1/invoices/stats`, l'informe d'aging i el de deutors principals	Per disseny	Aquests agregats mesuren volum facturat, la mateixa magnitud que declara la declaració anual d'operacions amb tercers, i tampoc no han restat mai els cobraments parcials. Per a l'import realment degut, llegeix el `pending_amount` de cada factura, que sí que mesura contra l'import a pagar.

Diferències deliberades respecte d'altres plataformes

Són decisions de producte conscients, no buits. Cadascuna existeix perquè l'alternativa que hem triat és millor per a qui integra que el patró que se'ns demana.

Escenari	Estat	Workaround
Paginació per desplaçament amb recompte de pàgines i salt a la pàgina N	Per disseny	Paginació per cursor a l'estil de Stripe: `limit` amb límits validats, més `starting_after` o `ending_before` (mútuament excloents). Les respostes porten `has_more` i `next_cursor`, i `next_cursor` val `null` quan `has_more` és fals. Vegeu Paginació.
Envelope d'error dual permanent — el nostre envelope i l'RFC 9457 al mateix cos, sempre	Per disseny	Negociació de contingut. `Accept: application/problem+json` retorna RFC 9457 pur; qualsevol altra cosa —`application/json`, `/`, sense capçalera `Accept`— retorna el nostre envelope. Vegeu Errors.
Atomicitat total en la creació massiva — una fila dolenta rebutja el lot sencer	Per disseny	Èxit parcial. La resposta porta `{dry_run, total, successful, failed, results, failures}`, on cada fallada identifica la seva fila per l'`index` que comença a zero amb el seu propi codi d'error. Importa'n 480 de 500 i arregla les 20. Vegeu Operacions massives.
Totals de línia obligatoris a la petició (`line_total`, `taxable_base`)	Per disseny	`line_total` és una suma de control opcional verificada: es compara amb el total calculat amb una tolerància d'un cèntim i després es descarta — mai no es persisteix ni es retorna. No has de replicar el nostre motor de càlcul. Vegeu Suplerts.
Representació o apoderament per tercers — endpoints de representació, documents d'autorització signats	Per disseny	Cada empresa puja el seu propi certificat, que ha de coincidir amb el seu propi NIF, es valida per estructura i mida, i té la contrasenya desada xifrada.
Substitució de factures simplificades en dos passos — una rectificativa més una factura completa nova	Per disseny	Un sol pas natiu: `POST /v1/invoices/substitute-simplified` emet la factura substitutiva agregant diverses simplificades. Vegeu Factures simplificades o completes.
SDK de Python	En full de ruta	Genera un client des del document OpenAPI publicat, o fes servir els SDK de TypeScript o PHP, el CLI o el servidor MCP.

Capacitats que pots donar per absents

Quatre coses que Factuarea fa i que qui arriba d'altres plataformes espera rutinàriament no trobar-hi:

Capacitat	On
Factura substitutiva de simplificades, en una sola crida — agregar diversos tiquets en una factura completa sense una rectificativa prèvia	Factures simplificades o completes · `POST /v1/invoices/substitute-simplified`
Esmena de registres VeriFactu rebutjats, exposada a l'API pública — reparar una declaració refusada sense anul·lar la factura	Esmena de registres VeriFactu · `POST /v1/verifactu/records/{id}/subsanar`
Rectificativa per diferències amb base imposable negativa — la manera fiscalment correcta d'expressar un abonament	Factures rectificatives
Catàleg fiscal de l'AEAT consultable per l'API — règims indirectes, règims d'operació, causes d'exempció amb el seu article de la LIVA, tipus de retenció i els parells legals d'IVA i recàrrec, en tres idiomes	Claus de règim · `GET /v1/tax-catalog`

Cap d'aquestes no s'anuncia ni està en desenvolupament: totes quatre són operacions vives avui.

On viu el raonament fiscal

Aquesta pàgina llista fronteres. Les guies que expliquen les regles que hi ha darrere:

Estats d'enviament VeriFactu

El cicle de vida del registre, reintent i esmena.

Factures rectificatives

R1–R5, substitució davant diferències.

Claus de règim

Qualificació de capçalera i catàleg de règim per línia.

Impostos territorials

IVA, IGIC i IPSI.

Suplerts

Imports pagats per compte del client.

Clients internacionals

Identificació alternativa i mapa d'escenaris.

Traçabilitat

Aquesta pàgina documenta l'absència de comportament, cosa que cap regla de negoci no pot afirmar. Les seves files, per tant, s'ancoren de manera diferent de les de les altres guies fiscals: a un punt verificat del codi, a la decisió registrada per a la plataforma, o —quan sí que existeix una regla de negoci— a aquella regla.

Limitacions verificades contra el codi:

Fila	Ancoratge
Autofactura	No hi ha aquesta capacitat al domini. Les úniques ocurrències del concepte són la factura que Factuarea emet als seus propis subscriptors i la comprovació de l'empresa del sistema — cap de les dues no és una capacitat de l'API.
Factura expedida per un tercer	El camp AEAT d'expedició per tercer no s'emet mai; cap ocurrència al codi de l'aplicació.
Multidivisa	`InvoiceV1Resource` retorna el literal `'EUR'`, i el repositori de lectura de la v1 documenta que qualsevol altra divisa dona una pàgina buida.
TicketBAI / Batuz	`BR-VFC-019` — deliberadament fora de l'abast del context VeriFactu.
Inversió del subjecte passiu per l'API	Cap petició de la v1 no accepta `operation_regime`; el recurs de factura el retorna de només lectura. `BR-VFC-029` deriva la qualificació d'aquell règim de capçalera, i `BR-INV-032` acota el catàleg de línia a causes d'exempció i no subjecció, sense codis `S`.
Suplerts fora de la factura emesa	`BR-INV-037` i l'objecte de valor de tipus de línia, que declara que només la factura emesa modela els suplerts; `BR-INV-040` per a la restricció de la factura simplificada.
Suplerts a l'XML de Facturae i UBL	L'edge case d'avís de `BR-INV-042`, que deixa registrat que l'import a pagar de tots dos documents és el total fiscal i que el bloc natiu de Facturae 3.2.2 encara no està mapejat.
Suplerts a les xifres agregades de cartera	L'edge case de `BR-INV-045`, que deixa registrat que els agregats mesuren volum facturat i que es deixen mesurant això a propòsit.

Diferències deliberades: ancorades als components HTTP compartits que implementen l'alternativa —la paginació per cursor, el negociador de contingut d'error, el recurs d'èxit parcial de les operacions massives—, a BR-INV-044 per a la suma de control de línia opcional, a BR-VFC-003, BR-VFC-004, BR-VFC-022 i BR-VFC-024 per als certificats propis de l'empresa, i a BR-INV-015 i BR-INV-016 per a la substitució en un sol pas. La fila de l'SDK de Python reflecteix una decisió registrada de planificar-lo per separat quan l'especificació s'estabilitzi: és ajornat, no descartat, que és per què el seu estat és En full de ruta i no Per disseny.

Capacitats: cadascuna s'ancora a la ruta viva que la materialitza — public-api.v1.invoices.substitute_simplified, public-api.v1.verifactu.records.subsanar i public-api.v1.tax-catalog.show — més BR-VFC-033 per a la base imposable negativa i BR-TAX-028 per al catàleg fiscal.