Model de comptes

30 de setembre de 2026 — a Factuarea el compte passa a ser el client. Reuneix el pla, les credencials, l'equip i els NIF que facturen. Pot donar a un altre compte accés a alguns d'aquests NIF, i una plataforma pot aprovisionar per API comptes per als seus propis clients. Aquesta pàgina recull el que afegeix aquest model i el que reanomena, tema per tema, amb la guia que explica cadascun. Les operacions que afegeix o canvia van en taules al final.

Membres i grants

L'equip ara pertany al compte, no a un NIF. Un membre porta un role de compte (owner, admin o member), la marca external_advisor, una llista de grants i un bloc permissions que diu què pot fer qui llegeix sobre aquest membre. Un grant (permís per NIF) és l'accés d'un member a un NIF, amb el nivell view (només lectura) o operate. Un owner o un admin arriba a tots els NIF sense grants.

• Operacions noves. GET /v1/accounts/{account}/members/{member} i les quatre operacions sobre un grant, sota /v1/accounts/{account}/members/{member}/grants: llistar, consultar, fixar amb PUT i revocar.
• Operacions canviades. Crear un membre rep grants en lloc de company_id. PATCH /v1/accounts/{account}/members/{member} canvia el role, la marca external_advisor o tots dos, i passar un membre a admin revoca els seus grants.
• Codis nous. grants_only_for_member, grant_company_not_in_account i external_advisor_already_assigned, tots 422.
• Scopes i pla. members:read i members:write necessiten el mòdul user_management, i members:* i invitations:* no es concedeixen mai per OAuth. Una clau fact_test_ llegeix el compte com una clau de producció, però les escriptures que canvien el compte responen 403 live_credential_required.

L'assessor extern és la persona externa a qui un compte pot donar accés, en qualsevol pla: sempre és member, n'hi ha un per compte i no ocupa plaça. Assessor extern explica com marcar-lo, i Comptes i NIF cobreix tot l'equip.

Invitacions de compte

Una invitació afegeix una persona al compte amb un rol i els grants amb què comença, en lloc de nomenar un sol NIF.

• Cos i recurs. POST /v1/accounts/{account}/invitations rep email, role (admin o member), grants i send_email (true per defecte) en lloc de company_id. La invitació porta ara grants, send_email i external_advisor.
• Operació nova. GET /v1/accounts/{account}/invitations/{invitation} llegeix una invitació.
• El secret es mostra un sol cop. Amb send_email: false la resposta porta el secret d'acceptació i l'accept_url exactament un cop. Quan el correu lliura l'enllaç, tots dos valen null, i també en una repetició idempotent.
• Reenviament. POST …/invitations/{invitation}/resend emet un secret nou i ara respon 200 amb la invitació, on abans responia 204.
• La invitació de l'assessor s'envia només des de l'aplicació web. Per API marques el membre després.

Invitacions recull els estats i els errors de cada escriptura.

Titularitat

El compte té exactament un owner. La titularitat es traspassa només amb PATCH /v1/accounts/{account}/owner: exigeix el scope account:owner, la persona que hi ha darrere de la credencial ha de ser el titular actual i és irreversible, així que demana una Idempotency-Key. El titular anterior passa a admin. Tots dos conserven tots els NIF, i no canvia cap NIF, API key ni pla.

El rol del titular no es canvia amb l'operació de membres, i el titular no es pot retirar del compte (member_is_last_owner): traspassa abans la titularitat. L'esdeveniment account.owner_transferred anuncia el canvi als teus webhooks de compte. Titularitat del compte en dona els detalls.

Traspassos de NIF

Un NIF canvia de compte amb un traspàs de NIF, que substitueix el «claim token» del contracte anterior. Sempre l'inicia el compte que entrega el NIF.

• Emetre. POST /v1/accounts/{account}/nif-transfers anomena el NIF a company_id i retorna el secret exactament un cop. Un traspàs dura 24 hores, o l'expires_at que triïs, fins a 7 dies.
• Acceptar. El compte receptor crida POST …/nif-transfers/accept amb el secret.
• Revocar. POST …/nif-transfers/{nif_transfer}/revoke és nova: cancel·la un traspàs que ningú no ha acceptat. GET …/nif-transfers llista els que has emès.
• Contracte. Emetre, acceptar i revocar són irreversibles i exigeixen una Idempotency-Key. Els scopes són nif_transfers:read i nif_transfers:write, els codis són nif_transfer_invalid i nif_transfer_expired, i les quatre eines són create_nif_transfer, list_nif_transfers, accept_nif_transfer i revoke_nif_transfer.
• El preu de rebre. Un compte que ja té NIF titular rep el NIF com a NIF addicional. La comprovació es fa abans de moure res.

La paraula reclamació pertany ara només als comptes gestionats. Traspassos de NIF recorre el flux.

Cartera de NIF, cicle de vida i NIF addicional

Els NIF d'un compte formen la seva cartera. Cadascun dels que se sumen al NIF titular és un NIF addicional.

• Estadístiques. GET /v1/accounts/{account}/companies/stats retorna una fila per NIF amb invoices_count, total_invoiced (una cadena amb dos decimals) i last_invoice, per al període que passis a date_from i date_to, o l'any natural en curs.
• El recurs del NIF. paid_until és el nom nou del camp de cobertura pagada del NIF (mira Reanomenats), i suspension_reason i readiness són nous. include=readiness afegeix l'aptitud d'emissió al llistat, amb el mateix contracte que issuing-readiness: can_issue i una llista de blockers. verifactu_certificate_missing és un d'aquests bloquejos, no un codi d'error.
• Cicle de vida. Un NIF està active, inactive o archived. DELETE l'arxiva i no cobra mai. El compte ha de conservar sempre un NIF actiu, així que desactivar o arxivar l'últim respon 422 business_rule_violation amb el subcodi account_must_keep_one_nif.
• El NIF addicional. Cada NIF a més del titular és un NIF addicional que paga el compte. Necessita el pla empresario o enterprise, el trial inclòs, i en producció amb una subscripció de pagament es cobra a l'acte. El topall de contracte max_additional_nifs respon 422 business_rule_violation amb el subcodi additional_nif_limit_reached, i seat-charge-preview ensenya el càrrec abans de confirmar.
• Els codis de la comprovació. additional_nif_plan_required i additional_nif_charge_failed són 402. additional_nif_not_in_plan i billing_managed_by_provider són 403.
• Scopes. companies:read, companies:write i companies:delete funcionen ara en qualsevol pla. El pla es comprova dins de l'operació que afegeix un NIF.
• Facturació. GET /v1/companies/{company}/billing conserva el bloc gestoria_seats amb el seu nom, i ara descriu la subscripció de NIF addicionals. Els seus imports són euros en cadenes amb dos decimals: la descripció anterior deia cèntims enters.
• El 409 de l'alta. POST /v1/accounts/{account}/companies documenta 409 resource_already_exists amb el subcodi managed_company_tax_id_already_exists, i el seu exemple diu ara Ya existe una empresa con ese NIF/CIF/NIE en la cuenta.

Cartera de NIF i NIF addicionals cobreixen l'alta, el cobrament i la reactivació, i l'estat d'un NIF cobreix el cicle de vida.

Comptes gestionats i aprovisionament

Un proveïdor de comptes ja pot crear comptes per als seus propis clients. Un compte gestionat és un compte normal i separat, amb el seu propi NIF titular i el seu propi pla. Passa de provisioned a claimed i després a active, i el client esdevé el seu owner en reclamar-lo amb un val. El proveïdor conserva el nivell que tenia.

• Operacions. POST /v1/accounts aprovisiona, GET /v1/accounts i GET /v1/accounts/{account} llegeixen, PATCH …/access-level canvia el nivell del proveïdor, DELETE …/management acaba la gestió, POST …/claim-tokens reemet el val, PATCH …/plan i GET …/plan/preview canvien i previsualitzen el pla, i GET …/provisioning-usage llegeix el consum.
• Scopes privilegiats. accounts:read i accounts:write són privilegiats: el scope * no els cobreix, OAuth no els concedeix mai, i el compte necessita el privilegi de proveïdor que GET /v1/me mostra a is_provider i privileged_scopes. Sense ell la resposta és 403 privileged_scope_required.
• Idempotència i val. Aprovisionar és irreversible i exigeix una Idempotency-Key. external_ref és la teva referència: fa la crida idempotent i és única als dos entorns. El claim_token i el claim_url tornen exactament un cop, o només per correu amb send_email: true.
• Nivells. El proveïdor conserva none, view o operate. Pot pujar el nivell només abans que el client reclami el compte (422 access_level_raise_forbidden), i el pot baixar en qualsevol moment.
• Preu. El pla és emprendedor o empresario, mensual, cobrat a la subscripció managed-accounts del proveïdor. enterprise és per contracte (422 managed_account_plan_not_self_serve), un proveïdor en trial només pot crear comptes de proves (422 managed_account_provider_in_trial), i max_managed_accounts (25 per defecte) respon 422 managed_accounts_limit_reached.
• Mentre pagues tu. El titular d'un compte gestionat que pagues tu no pot comprar pla, places d'empleat ni NIF addicionals, i rep 403 billing_managed_by_provider.
• Quan el client assumeix el pagament. El proveïdor conserva el seu nivell com a accés cedit i el client conserva el mateix pla i preu. Amb el nivell none no queda res per cedir, així que la relació acaba. No es publica cap esdeveniment account.* per això. Ho notes perquè GET /v1/accounts/{account} respon 404 i el compte apareix a client_accounts de GET /v1/me amb origin: "granted".
• Acabar la gestió no dona al proveïdor un accés cedit. La relació acaba i el proveïdor perd tot l'accés al compte des de la petició següent.
• Comptes de proves. Amb una clau fact_test_, POST /v1/accounts crea un compte de proves: sense cobrament, sense val i sense reclamació (managed_account_not_claimable).
• El certificat VeriFactu del client. Un proveïdor amb operate el puja amb POST /v1/companies/{company}/verifactu/certificates, i verifactu_certificate_missing apareix com a bloqueig a l'aptitud d'emissió del NIF. El certificat del client n'explica els passos.
• MCP. Hi ha nou eines que reflecteixen aquestes operacions, i la importació massiva no en té cap. Només apareixen per a una clau que llisti el scope privilegiat, i el recompte d'eines del catàleg MCP no les inclou.

Els codis nous són managed_account_external_ref_in_other_environment, provisioning_account_claimed i enterprise_contract_transition_required, a més dels anteriors. Comença per Comptes gestionats, continua amb preu i canvi de pagador i les proves amb fact_test_. Les eines són al catàleg MCP.

Importació massiva

Un proveïdor pot carregar els seus clients des d'un CSV d'una vegada. Les tres operacions són només d'API, sense eina MCP per disseny.

• Operacions. GET /v1/accounts/imports/template descarrega la plantilla (accounts:read). POST /v1/accounts/imports/preview revisa els fitxers i calcula el cost de cada fila sense escriure res. POST /v1/accounts/imports els aplica. Els dos POST exigeixen accounts:write i reben multipart/form-data amb accounts_file, un customers_file opcional i options.
• Modalitats. Cada fila tria el seu mode, sense valor per defecte: own_nif afegeix un NIF al teu propi compte com a NIF addicional, i managed_account aprovisiona un compte separat per al teu client.
• Límits. 5 MB per fitxer, 100 files a accounts_file i 1.000 a customers_file: import_file_too_large és 413, i import_row_limit_exceeded i import_file_invalid són 422.
• Aplicar. És irreversible i exigeix una Idempotency-Key. Les importacions del mateix proveïdor s'apliquen una a una (409 import_in_progress), i tornar a importar el mateix fitxer reconcilia per external_ref: no duplica mai un compte ni cobra dues vegades.
• Claus de proves. Les files managed_account creen comptes de proves. Les files own_nif surten ERROR amb live_credential_required.

L'esdeveniment account.import_completed avisa els teus webhooks de compte que ha acabat. Importació massiva descriu les columnes, els estats per fila i el que la importació no fa.

Abast per relació sobre {company}

Un compte pot deixar que un altre treballi amb alguns o tots els seus NIF. El compte receptor hi arriba amb la seva pròpia credencial per /v1/companies/{company}/…, com si fossin seus.

• Nivells. view llegeix i operate també escriu. Una escriptura amb view respon 403 company_read_only i no crea ni canvia res.
• El que es queda al compte cedent. Un NIF al qual s'arriba per relació no obre mai les capacitats del compte al qual pertany. A l'eix d'empresa, les operacions que són del compte propietari (facturació, webhooks i registres de peticions d'empresa, consum d'automatitzacions i credencials de Stripe) responen 403 forbidden_action, i les de nivell de compte responen 404 account_not_found.
• El segment de compte. {account} a /v1/accounts/{account}/… és sempre el compte de la teva credencial. Anomenar-ne un altre respon el mateix 404 account_not_found, així que als NIF d'un compte cedent s'hi arriba per {company}, mai per {account}.
• Claus. El nivell d'un NIF en una clau es fixa en emetre-la i només pot baixar. Quan l'accés es redueix o acaba, les claus del compte receptor es tornen a calcular a la petició següent.
• On es gestiona. Cedir, canviar i revocar un accés es fa només a l'aplicació web. No hi ha ruta ni eina MCP per fer-ho, a propòsit. No exigeix pla ni mòdul i no ocupa places d'usuari.
• Veure-ho. GET /v1/me ja no exigeix cap scope. Retorna account amb is_provider i privileged_scopes, i client_accounts amb els comptes als quals arribes per relació (origin val granted o provisioned), que només s'omple si la clau té el scope privilegiat accounts:read, a més de client_accounts_visible i client_accounts_has_more.
• Acotar claus. PATCH /v1/accounts/{account}/api-keys/{api_key}/nif-scope substitueix la llista de NIF d'una clau amb scoped_company_ids, i el nou abast mai no pot superar el teu.

Accés cedit recull el flux, i arribar a un NIF i claus acotades cobreixen el costat de la credencial.

Webhooks de compte i registres de peticions

Un compte té els seus propis endpoints de webhook i els seus propis registres de peticions, sota /v1/accounts/{account}/…. Deu operacions gestionen els endpoints i dues llegeixen els registres, amb els mateixos scopes que les seves bessones d'empresa (webhooks:read, webhooks:write, webhooks:delete i developers:read). Hi ha una eina MCP per operació, i cap no està disponible per OAuth.

• Operacions. POST /v1/accounts/{account}/webhooks crea un endpoint. Les altres el llisten, consulten, actualitzen i esborren, llisten i consulten les seves entregues, en reintenten una, roten el secret i envien una prova. GET …/request-logs i GET …/request-logs/{request_id} llegeixen les peticions de totes les claus del compte, a l'entorn de la clau que pregunta.
• Equivalència. retry correspon a replay, secret a rotate-secret i test a test-event. No hi ha cap ping de compte. El reintent d'un compte rearma la mateixa entrega, mentre que el replay d'una empresa en crea una de nova.
• Filtre i entorn. account_relationship val own, managed o all (per defecte). Un endpoint pertany a un entorn, live o test, i no el canvia mai.
• Qui pot. Només el teu propi compte, amb qui va emetre la clau com a titular o administrador i una clau que arribi a tots els NIF del compte. Crear, editar, rotar, provar, reintentar i esborrar exigeixen una clau de producció.
• Límits. El nombre d'endpoints depèn del tram de qui paga: 402 addon_required quan no n'admet cap i 422 account_webhook_endpoint_limit_reached en arribar al topall.
• Endpoints d'empresa sobre un NIF relacionat. Els webhooks i els registres de peticions d'una empresa responen 403 forbidden_action quan al NIF s'hi arriba per relació. Conserven el seu contracte sobre els teus NIF propis.

Webhooks de compte porta la taula d'equivalències i el sobre, i Deduplicar lliuraments de webhooks explica per què el mateix esdeveniment conserva el mateix id als dos tipus d'endpoint.

Esdeveniments account.*

Quinze esdeveniments t'expliquen què li passa al compte mateix. Només hi poden subscriure's els endpoints de compte.

No són a GET /v1/event-catalog i no activen mai una automatització. El sobre d'una entrega de compte és el sobre d'empresa més account, account_relationship i company_id, i les capçaleres hi afegeixen Factuarea-Account-Relationship. L'esdeveniment d'un NIF conserva el mateix id que té en un endpoint d'empresa, mentre que un esdeveniment account.* no té bessó d'empresa. El catàleg account.* llista cada nom amb la seva càrrega, i Esdeveniments explica per a què serveixen.

Correccions del contracte publicat

Cinc punts del contracte publicat canvien sense que canviï cap operació, cap estat ni cap codi que retorna l'API.

• Scopes de l'esquema OAuth2. L'esquema OAuth2 del document OpenAPI publica ara els 66 scopes que ofereix la pantalla de consentiment, amb el vocabulari de punt que accepta el servidor d'autorització (invoices.read, factuarea.full). Abans llistava els noms fins que fan servir les API keys, com invoices:read, i una petició que en nomeni un es rebutja amb invalid_scope. Scopes i permisos recull el catàleg.
• URLs d'OAuth. Les URLs d'autorització i de token d'aquest esquema són ara les de producció: https://mcp.factuarea.com/api/oauth/authorize i https://mcp.factuarea.com/api/oauth/token.
• Rotació de secret massa aviat. webhook_secret_recently_rotated és ara un 422 al catàleg d'errors, i ja no un 429. L'API ja responia 422, així que un client fet contra el catàleg l'hauria reintentat com un rate limit. rotate_secret d'empresa el documenta ara.
• seat-charge-preview. La descripció de seat-charge-preview diu que amount, tax_amount i total són euros en cadenes amb dos decimals, i que només recurring_base_cents i recurring_total_cents van en cèntims. Abans deia unitats menors. Els valors no canvien.
• Missatges del 409 i del 404. El 409 de l'alta diu ara Ya existe una empresa con ese NIF/CIF/NIE en la cuenta. i el 404 d'un NIF, NIF no encontrado en la cuenta. Abans deien «empresa gestionada», que anomena un compte gestionat i no un NIF del teu propi compte. portfolio_max_api_keys_exceeded, portfolio_rate_limit_exceeded i portfolio_monthly_quota_exceeded parlen també de la cartera del teu compte i ja no d'una gestoria. El code, el subcodi i el param no canvien.

Reanomenats

Aquests noms canvien al contracte. Cada fila mostra el nom que feia servir el contracte anterior i el que el substitueix.

Dues files necessiten una nota. El role d'un membre és ara el rol de compte, i l'accés a cada NIF viu als seus grants, així que els camps del membre se substitueixen en lloc de reanomenar-se. I POST /v1/accounts/{account}/claim-tokens reemet ara el val de reclamació d'un compte gestionat, que és una operació diferent del traspàs que anomenava abans. El camp de facturació gestoria_seats conserva el seu nom.

Operacions

Totes les operacions que el model de comptes afegeix o canvia, amb la seva pàgina de referència: