Abast i limitacions

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 3 d'octubre 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 arriba al NIF d'un client, per un accés cedit o com a proveïdor d'un compte gestionat, emet des d'aquella empresa anomenant-la al segment d'empresa de la ruta; 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. Escriu els documents públics en EUR; els connectors de botigues poden convertir les comandes entrants a EUR.
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, despeses, 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/companies/{company}/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.
Una capçalera de petició que canvia l'empresa activa — una credencial més un header de perfil per petició	Per disseny	L'empresa viatja a la ruta. L'empresa efectiva és el segment `{company}` de `/v1/companies/{company}/…`, i el que abasta una credencial és el conjunt de NIF dins del seu àmbit —els propis, els cedits al seu compte i els dels comptes que gestiona—, mai un perfil que s'activa: vegeu a quins NIF arriba una credencial. La capçalera `X-Active-Profile` està retirada: una petició que l'enviï es rebutja amb `400 parameter_unknown`, subcodi `retired_active_profile_header`, sigui quin sigui el seu valor. Vegeu Arribar a un NIF pel segment d'empresa.
Substitució de factures simplificades en dos passos — una rectificativa més una factura completa nova	Per disseny	Un sol pas natiu: `POST /v1/companies/{company}/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.

A quins NIF arriba una credencial

Una credencial opera sobre un NIF anomenant-lo al segment {company} de la ruta, i arriba als NIF que són dins del seu àmbit de NIF. Vénen de tres llocs:

El seu propi compte. Els NIF del compte al qual pertany la credencial.
Un accés cedit. Els NIF que un altre compte va cedir al seu compte, tots o una llista, amb el nivell view o operate.
Un compte gestionat. Els NIF dels comptes gestionats que el seu compte va aprovisionar, mentre la gestió sigui vigent i el nivell no sigui none.

Una clau mai no arriba a més del que anomena el seu àmbit, i el seu àmbit mai no excedeix el que assoleix el seu compte. Un NIF al qual la credencial no arriba, o al qual arriba amb el nivell none, respon 404 profile_not_found. Sobre un NIF assolit per una relació entre comptes s'apliquen dos límits, i cap no canvia cap dada:

Les capacitats del compte que posseeix el NIF es queden amb ell. Les operacions que pertanyen al compte propietari del NIF —la facturació, els endpoints de webhook d'empresa, els registres de peticions i els esdeveniments d'empresa, l'ús de les automatitzacions i les escriptures de les seves credencials de pagament— responen 403 forbidden_action abans de llegir o canviar res, amb qualsevol dels dos nivells. L'equip, les invitacions, la titularitat, les claus d'API, la cartera de NIF i els traspassos d'aquell compte viuen sota /v1/accounts/{account}/…, on {account} ha de ser el teu propi compte: un altre respon 404 account_not_found.
view llegeix. Amb el nivell view, tota escriptura sobre el NIF respon 403 company_read_only. Amb operate pots escriure, tret del que el primer límit deixa amb el compte propietari.

El que es queda al compte cedent enumera les operacions que es queden amb el compte propietari, i Quines rutes de {account} accepten un compte gestionat les rutes de {account} que l'accepten.

El que el model de comptes deixa fora, a propòsit

El model de comptes deixa algunes decisions en mans d'una persona i algunes superfícies fora de l'API. Cada fila d'aquí sota és deliberada, i el seu workaround és la manera de resoldre el cas.

Escenari	Estat	Workaround
Gestionar un accés cedit per l'API o el servidor MCP — cedir, acceptar, rebutjar, canviar, reenviar, revocar o renunciar a un accés entre comptes	Per disseny	L'aplicació web. Una persona de cada compte ho decideix i ho confirma allà, de manera que una clau filtrada no pot obrir els NIF del seu compte a un altre compte. El compte cedent fa servir Configuració → Accessos al meu compte i el receptor, Configuració → Accessos rebuts. El que l'API sí dona és l'abast d'un accés cedit: vegeu a quins NIF arriba una credencial i Cedir, canviar i revocar a l'aplicació web.
El costat del client d'un compte gestionat per l'API — reclamar el compte, pujar o baixar el nivell del proveïdor, acabar la gestió i assumir el pagament	Per disseny	El client ho fa a l'aplicació web. Una credencial del proveïdor no pot decidir pel titular. El teu costat, el del proveïdor, és complet per l'API i pel servidor MCP: canvia el teu nivell amb `PATCH /v1/accounts/{account}/access-level`, acaba la gestió amb `DELETE /v1/accounts/{account}/management` i reemet el val. Vegeu El costat del client és de l'app.
Importació massiva mitjançant una eina MCP	Per disseny	L'API REST o la importació de l'aplicació web. Les tres operacions són privilegiades i la importació llegeix dos fitxers pujats, que el servidor MCP no transporta. Des d'un agent, aprovisiona els comptes d'un en un amb l'eina `provision_managed_account`, que reflecteix `POST /v1/accounts`. Vegeu Dues coses que la importació no fa, per disseny.
Webhooks i registres de peticions de compte més enllà del teu propi compte, o per OAuth — administrar els d'un compte gestionat o cedent, o fer servir les seves eines MCP des d'una connexió OAuth	Per disseny	El teu propi compte, amb una clau d'API. `{account}` és sempre el compte de la credencial. Un proveïdor de comptes segueix els esdeveniments dels comptes que gestiona al seu propi endpoint amb el filtre `managed`. Les dotze eines MCP de webhooks i de registres de peticions de compte funcionen només amb una clau d'API: una connexió per OAuth no les llista ni les crida. Vegeu Quatre diferències que no són de nom.
Un endpoint de webhook d'empresa sobre un NIF assolit per una relació	Per disseny	Un endpoint de compte. Les onze operacions de `…/webhook-endpoints` i les dues de `…/request-logs` sobre un NIF d'un altre compte, cedit o gestionat, responen `403 forbidden_action` perquè pertanyen al compte que el posseeix. Per seguir els NIF dels comptes que gestiones, crea un endpoint de compte amb el filtre `managed` o `all`. Un accés cedit no es segueix amb webhooks al costat receptor: el compte cedent rep els esdeveniments dels seus propis NIF. Vegeu Endpoints i registres d'empresa sobre un NIF assolit per una relació.
L'historial de correus d'un compte sencer — `GET /v1/accounts/{account}/emails`, el seu detall i els seus indicadors	Per disseny	Llegeix-lo NIF per NIF. L'historial viu a l'eix d'empresa, amb el scope `emails:read` i dins de l'àmbit de la credencial: `GET /v1/companies/{company}/emails`, el seu detall i els seus indicadors. Les tres rutes de compte no existeixen.
Sèries de documents a la importació massiva — una columna o una opció per crear o triar la numeració de cada NIF importat	Per disseny	Crea les sèries amb l'eix d'empresa. La importació dona d'alta comptes i NIF, no la seva numeració: la seva plantilla té un conjunt tancat de columnes i cap no és una sèrie. Després, `POST /v1/companies/{company}/series/bootstrap` crea en una crida les sèries per defecte que falten amb `series:write`, i `issuing-readiness` informa de `no_default_series` mentre en falti una. Vegeu Dues coses que la importació no fa, per disseny.
L'assessor extern per l'API o el servidor MCP, en un pla sense gestió d'usuaris	Per disseny	L'aplicació web, en qualsevol pla. La gestió de l'equip per l'API i el servidor MCP pertany al mòdul `user_management`, que inclouen `empresario` i `enterprise` i no `emprendedor`: sense ell els scopes `members:` i `invitations:` no es poden assignar. L'aplicació web convida l'assessor, edita els seus grants, reenvia o cancel·la la invitació, retira l'assessor i treu la marca en qualsevol pla. Amb el mòdul, un membre existent es marca o es desmarca amb `external_advisor` a `PATCH /v1/accounts/{account}/members/{member}`. Vegeu Plans sense gestió d'usuaris.

Capacitats que pots donar per absents

Vuit 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/companies/{company}/invoices/substitute-simplified`
Esmena de registres VeriFactu acceptats o rebutjats, exposada a l'API pública — corregir un registre amb un de nou, sense anul·lar la factura i sense editar l'original	Esmena de registres VeriFactu · `POST /v1/companies/{company}/verifactu/records/{record}/subsanar`
Remissió per un tercer — Factuarea remet els registres amb el seu propi certificat a l'empara d'un apoderament (o de l'annex I signat de la col·laboració social), de manera que l'empresa no lliura el seu certificat	Alta automàtica a VeriFactu · `POST /v1/companies/{company}/verifactu/representation`
Cobrament desatès en una crida idempotent — una factura simplificada ja cobrada amb el seu QR VERI*FACTU, que es pot reenviar amb seguretat dies després per `external_id`	Facturació des de terminals desatesos · `POST /v1/companies/{company}/invoices`
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`
Catàleg de producte mesurat — unitats UNECE, presentacions fixes/variables, variants amb estoc propi opcional i ofertes de proveïdor	Catàleg de productes
Tarifes per client i document — preus a quatre decimals, precedència estable variant/presentació i repricing explícit d'esborranys	Tarifes · `POST /v1/companies/{company}/price-lists/resolve`

Cap d'aquestes no s'anuncia ni està en desenvolupament: totes vuit 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, 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. La capçalera de perfil retirada s'ancora al middleware de la v1 que la rebutja per presència, abans que s'executi cap handler, i al seu rebuig catalogat 400 · parameter_unknown · retired_active_profile_header.

Abast d'una credencial: BR-ACC-181 per al segment d'empresa com a únic mecanisme d'empresa efectiva, que també arriba als NIF de les relacions vigents dins de l'àmbit, BR-ACC-180 per a l'àmbit que mai no excedeix el que assoleix el compte, BR-ACC-191 per a l'inventari tancat d'operacions de l'eix d'empresa que responen 403 forbidden_action, BR-ACC-153 per al que signifiquen operate i view sobre un NIF assolit per una relació, i BR-ACC-043 per al 403 company_read_only de view.

Exclusions del model de comptes:

Fila	Ancoratge
Gestionar un accés cedit per l'API o el servidor MCP	`BR-ACC-199`: una llista tancada de dotze noms de ruta, amb la seva raó com a clau, i un gate que comprova que cadascuna existeix i que cap ruta v1 ni eina MCP no la reflecteix. `BR-ACC-155` per al que fa cada banda a l'aplicació web.
El costat del client d'un compte gestionat per l'API	`BR-ACC-199`: set noms de ruta del costat del titular, al mateix gate. `BR-ACC-164` i `BR-ACC-165` per al nivell i la fi de la gestió, i `BR-ACC-194` per al costat del proveïdor, que sí que té les seves rutes i eines.
Importació massiva mitjançant una eina MCP	`BR-ACC-200`, que deixa registrat que la importació no té eina, i l'exclusió declarada de les tres operacions `managed_accounts.imports.*` al test de paritat v1 ↔ MCP.
Webhooks i registres de peticions de compte més enllà del teu propi compte, o per OAuth	`BR-ACC-230` per a la capacitat del compte comprovada a cada petició, i `BR-ACC-233` per a les dotze eines que rebutgen el canal OAuth una a una.
Un endpoint de webhook d'empresa sobre un NIF assolit per una relació	`BR-ACC-234`, dins de l'inventari tancat de `BR-ACC-191`.
L'historial de correus d'un compte sencer	`BR-ACC-235`: les tres rutes es declaren com a no exposades al gate de paritat d'eixos, i un test falla si alguna apareix a l'encaminador.
Sèries de documents a la importació massiva	El conjunt tancat de columnes de la plantilla d'importació, cap de les quals és una sèrie, i la petició d'importació, que no té cap opció de sèries.
L'assessor extern per l'API o el servidor MCP, en un pla sense gestió d'usuaris	`BR-ACC-107`: l'aplicació web gestiona l'assessor en qualsevol pla, mentre que els scopes d'equip de l'API segueixen el mòdul `user_management`. `BR-ACC-199` enumera les deu rutes que existeixen només a l'aplicació web.

Capacitats: cadascuna s'ancora a la ruta viva que la materialitza — public-api.v1.invoices.substitute_simplified, public-api.v1.verifactu.records.subsanar, public-api.v1.verifactu.representation.register, public-api.v1.invoices.create i public-api.v1.tax-catalog.show — més BR-VFC-042 per a la remissió per un tercer, BR-VFC-046 per a l'esmena com a alta nova, BR-VFC-033 per a la base imposable negativa i BR-TAX-028 per al catàleg fiscal, BR-PRD-026…BR-PRD-030 per al catàleg mesurat i BR-PRI-001…BR-PRI-004 per a les tarifes.

Comandes en altres divises

Els imports dels documents públics continuen en EUR. Els connectors de comerç electrònic poden importar una comanda en una altra divisa i convertir-la a EUR; això no afegeix escriptures de documents en qualsevol moneda a v1. Es continuen aplicant les comprovacions d’identificació i fiscalitat; la manca de tipus de canvi o de dades admeses del comprador produeix un resultat observable d’integració. Consulta botigues.