Accés cedit entre comptes

Un compte pot deixar que un altre compte treballi amb tots o alguns dels seus NIF, sense compartir cap contrasenya i sense moure res. El compte que ho permet és el compte cedent, i els NIF continuen sent seus. El compte que rep l'accés és el compte receptor. És el que fa servir una empresa quan vol que la seva assessoria emeti i consulti els seus documents.

És un sol accés entre dos comptes. Té un nivell, view o operate, i un abast: tots els NIF del compte cedent, o només els que ell tria. El compte receptor arriba a aquests NIF amb les seves pròpies credencials a través del segment {company} de l'eix de NIF. Aquesta guia explica com es cedeix un accés, què pot i què no pot fer-hi el compte receptor i què passa amb les seves claus quan l'accés es redueix o acaba.

No és un compte gestionat, que crea un proveïdor per al seu client, ni és un grant, que dona a un membre del teu propi compte accés a un dels teus NIF. Quan el titular d'un compte gestionat assumeix el pagament, l'accés del proveïdor passa a ser un accés cedit: preu i canvi de pagador ho explica.

L'accés en resum

Amb all, un NIF que el compte cedent afegeixi més endavant entra a l'accés per si sol, i un que arxivi o traspassi a un altre compte en surt a l'acte. Amb list, l'accés cobreix els NIF de la llista que continuen sent del compte cedent. Un NIF que només està desactivat es queda a l'abast i respon 403 company_inactive fins que es reactivi.

Cedir, canviar i revocar a l'aplicació web

Cedir, canviar i revocar un accés es fa només a l'aplicació web. No existeix cap ruta de l'API ni cap eina MCP per fer-ho, a propòsit: una credencial filtrada no ha de poder obrir els NIF d'un compte a un altre. Acceptar, rebutjar i renunciar a un accés també són operacions de l'aplicació web.

• Qui pot. Només un titular o administrador del compte de cada banda. Un membre i una persona aliena al compte reben el mateix 403 forbidden_action.
• Convidar per email o per codi de compte. Per email, Factuarea envia la invitació a aquesta adreça, i una persona que encara no té compte es pot registrar i acceptar amb el mateix enllaç. Per codi de compte, el compte cedent enganxa el codi de l'altre compte, que és el seu account.id, l'UUID que retorna GET /v1/me. El compte receptor el troba a Configuració → Accessos al meu compte, i la invitació espera llavors a les seves invitacions pendents. Cada invitació porta un nivell i un abast.
• Un sol accés obert per parella. Convidar un compte que ja té amb tu un accés pendent o vigent respon 422 relation_already_exists, i el mateix passa en acceptar una invitació per email quan els dos comptes ja en tenen un d'obert. Un codi que anomena el teu propi compte, que no existeix o que està mal format respon el mateix 422 relation_self_grant_not_allowed, perquè el camp no serveixi per sondejar comptes. Una llista de NIF que n'anomena algun que el compte cedent no té, o que arriba buida, respon 422 relation_company_not_in_grantor i no diu quin falla.
• Caducitat. Una invitació caduca als 7 dies. Reenviar-la emet un secret i una caducitat nous, i l'enllaç anterior deixa de valer. Una invitació caducada continua pendent i no es pot acceptar (422 relation_invitation_expired). Una enviada per codi de compte manté ocupada la parella fins que es reenviï o es retiri. Convidar i reenviar comparteixen un mateix límit de peticions per compte cedent.
• Acceptar. Una invitació per codi de compte s'accepta des de la llista d'invitacions pendents, i una per enllaç s'accepta triant quin compte administra la persona. Una invitació per email l'ha d'acceptar la persona amb aquesta adreça. El secret val una sola vegada: un de buit, desconegut, ja usat, retirat o adreçat a una altra persona respon el mateix 422 relation_invitation_invalid, a propòsit.
• Canviar i acabar. El compte cedent pot canviar el nivell entre view i operate, canviar els NIF i revocar l'accés en qualsevol moment, també mentre la invitació és pendent. El compte receptor pot rebutjar una invitació pendent i renunciar a un accés vigent. Un canvi que l'estat de l'accés no admet respon 422 relation_transition_not_allowed.
• Qui rep avís. Una invitació, la seva acceptació, una revocació, un rebuig i una renúncia avisen per correu l'altre compte. Canviar el nivell o els NIF no envia cap correu, i arriba al compte receptor a la seva petició següent.

Arribar a un NIF cedit

El compte receptor arriba a un NIF cedit com a un de propi: pel segment {company}, a /v1/companies/{company}/…. {company} és l'id del NIF (UUID v7), mai el seu tax_id. El segment {account} de /v1/accounts/{account}/… continua sent el teu propi compte: el compte cedent no és un compte que administris, i anomenar-lo respon el mateix 404 account_not_found que qualsevol compte que no és teu. El servidor MCP arriba als mateixos NIF: anomena el NIF amb la capçalera X-Company-Id en lloc d'un segment de ruta, amb els mateixos nivells i els mateixos límits.

Una persona del compte receptor arriba a un NIF cedit amb aquest nivell:

A l'aplicació web, els NIF cedits apareixen com a comptes de clients, a part dels NIF del teu propi compte. Una credencial rep el nivell de la persona que la va emetre, com explica el sostre de les teves claus.

Una credencial arriba a un NIF cedit només quan el seu àmbit l'anomena. Les claus que ja existien no canvien quan es cedeix un accés, i una clau que crees per l'API sense scoped_company_ids arriba als mateixos NIF que la credencial que la crea, i mai a més. Per això:

• La primera clau es crea a l'aplicació web. A Configuració → Desenvolupadors → API Keys, el camp d'àmbit de NIF llista els NIF de l'accés en un grup anomenat Comptes de clients, cadascun amb el nivell més alt que admet. Només un titular o un administrador del compte receptor pot crear-hi claus i, amb això, afegir-los: un membre no pot, ni tan sols sobre els NIF en què té un grant.
• L'API redueix i mai no amplia. POST /v1/accounts/{account}/api-keys amb scoped_company_ids i PATCH /v1/accounts/{account}/api-keys/{api_key}/nif-scope, tots dos amb el scope account:write, només accepten NIF als quals la clau que crida ja arriba. Demanar-ne un de més respon 422 business_rule_violation amb el subcodi nif_scope_exceeds_issuer, i un NIF d'un compte que no t'ha cedit res respon 422 invalid_param_value, igual que un que no existeix.

Quan una clau hi arriba, GET /v1/me els llista a scope. No apareixen a GET /v1/accounts/{account}/companies, que llista només els NIF del compte del path. El bloc client_accounts de GET /v1/me llista els comptes que et van cedir accés (origin granted) només quan la clau porta el scope privilegiat accounts:read en vigor, cosa que exigeix el privilegi de proveïdor de comptes gestionats del teu compte. Si no, va buit i client_accounts_visible és false.

Què pots fer a cada nivell

El nivell de l'accés decideix què pots fer en un NIF cedit.

Un accés operate et fa administrador del NIF, no del compte que el posseeix. Treballes amb les dades del NIF dins del que permet el pla del compte cedent, i el que crees pertany a aquest NIF. El servidor MCP aplica els mateixos nivells i respon el mateix 403 company_read_only.

Un POST /v1/companies/{company}/invoices en un NIF amb view respon:

{
  "error": {
    "type": "authorization_error",
    "code": "company_read_only",
    "message": "Tu acceso a esta empresa es de solo lectura.",
    "doc_url": "https://docs.factuarea.com/guides/errors#company_read_only",
    "request_id": "req_01J8Y3M2Q40000000000000007"
  }
}

El que es queda al compte cedent

Algunes operacions de l'eix de NIF pertanyen al compte que posseeix el NIF, no a les dades del NIF. En un NIF cedit responen 403 forbidden_action abans de llegir o canviar res, amb qualsevol dels dos nivells i també les lectures. El missatge no anomena el compte cedent.

Un POST /v1/companies/{company}/webhook-endpoints en un NIF cedit respon, amb view o amb operate:

{
  "error": {
    "type": "authorization_error",
    "code": "forbidden_action",
    "message": "Esta operación solo la puede hacer la cuenta dueña del NIF: con un acceso por relación entre cuentas no está disponible.",
    "doc_url": "https://docs.factuarea.com/guides/errors#forbidden_action",
    "request_id": "req_01J8Y3M2Q40000000000000008"
  }
}

Les seves eines MCP responen el mateix. La resta d'operacions de l'eix de NIF són dades del NIF i se serveixen amb el teu nivell. El compte que posseeix el NIF crida aquestes mateixes operacions com sempre.

Les capacitats del propi compte cedent viuen sota /v1/accounts/{account}/…: el seu equip, invitacions, titularitat, API keys, cartera i traspassos de NIF, webhooks de compte i registres de peticions. {account} ha de ser el teu propi compte, així que no t'hi pots adreçar. Les operacions que porten al path un NIF del compte també rebutgen un de cedit: activar, desactivar, editar o arxivar un NIF cedit per la ruta del teu propi compte respon 404 resource_not_found, sense canvi d'estat ni càrrec. L'aplicació web bloqueja les mateixes capacitats mentre un NIF cedit és la teva empresa activa: la facturació, l'equip, les invitacions, la titularitat, les claus, la compra, el traspàs i l'arxiu de NIF, els webhooks d'empresa i els ajustos del compte es queden amb el compte cedent.

Les teves claus: nivell i sostre

El nivell d'una clau en un NIF cedit es fixa quan el NIF entra a la clau, en emetre-la o en canviar-ne l'àmbit, i només baixa. És el menor entre el nivell de l'accés i el nivell que té en aquest NIF la persona que emet la clau, que per a un member queda a més limitat pel seu grant. En cada escriptura compta el menor entre el nivell desat a la clau i el que la persona emissora té avui.

• Escriure exigeix operate. Una clau amb qualsevol scope que no sigui de lectura (:read), inclòs el scope *, necessita operate en cada NIF que anomena. Anomenar un NIF que només té view juntament amb un d'aquests scopes respon 422 business_rule_violation amb el subcodi nif_access_level_exceeds_emitter i no crea res. Si no declares scoped_company_ids, es deixen fora els NIF per sota del nivell que demanen els scopes, i quan no en queda cap la resposta és el mateix 422. A l'aplicació web, un NIF amb view només admet scopes de lectura.
• Un NIF al qual qui emet no arriba. Un NIF cedit en què un membre no té grant, o un d'un compte que no t'ha donat accés, respon 422 invalid_param_value amb param scoped_company_ids, igual que un NIF que no existeix.
• El pla és el pla del NIF. Un NIF cedit aporta el pla del seu propi compte. Una clau rep un scope només si el pla de tots els NIF del seu àmbit el permet, i l'excés mai no es retalla en silenci: respon 422 scope_not_allowed_by_plan.
• Les claus de proves no hi arriben. Una clau fact_test_ arriba només a l'empresa sandbox del seu compte, així que mai no arriba a un NIF cedit i respon 404 profile_not_found. Fes servir una clau fact_live_.

Quan l'accés es redueix o acaba

Un accés es redueix quan el compte cedent el revoca, en baixa el nivell o n'hi treu NIF, quan el compte receptor hi renuncia, i quan un NIF surt del compte cedent. Cadascuna d'aquestes coses fa efecte a la petició següent:

• Es retiren els grants que els membres del compte receptor tenien sobre els NIF perduts.
• Cada clau del compte receptor es recalcula a la baixa. Un NIF sense nivell surt de l'àmbit de la clau, un nivell baixat a view converteix les escriptures d'aquesta clau en 403 company_read_only, i una clau que es queda amb l'àmbit buit es revoca. La resta de la clau continua funcionant sobre els seus NIF propis.
• Un NIF al qual el compte receptor ja no arriba respon 404 profile_not_found, igual que un que no existeix, així que la resposta no revela que existeix.

Res no puja per si sol. Pujar el nivell, ampliar els NIF o acceptar un accés nou no toca les claus que ja existeixen: emet una clau nova per a aquest NIF per obtenir el nivell nou.

Repartir l'accés amb el teu equip

Un titular o administrador del compte receptor decideix quins membres del seu equip treballen amb els NIF cedits. Un membre rep un grant amb view o operate sobre un NIF de l'abast d'un accés vigent, i hi arriba amb el menor entre el grant i el nivell de l'accés. L'aplicació web ho fa des del compte de client, a Accessos rebuts. L'API ho replica amb les operacions dels grants de membre, on {company} és el NIF cedit:

• Qui i què. La persona que va emetre la credencial ha de ser titular o administrador del compte, i l'àmbit de la credencial ha d'incloure ja aquest NIF. Els scopes members:* necessiten el mòdul user_management.
• Guanya el nivell menor. Donar operate sobre un accés que és view no es rebutja: el nivell es desa tal qual i el membre arriba al NIF amb el menor dels dos.
• Fora de l'accés. Un NIF fora d'un accés vigent, o un l'accés del qual va acabar, respon 422 grant_company_not_in_account en escriure i 404 member_not_found en llegir, sense dir que algun cop hi va haver un accés. Un owner o un admin respon 422 grants_only_for_member, perquè ja arriba a tots els NIF de l'accés.
• Sense correu. Donar, canviar o retirar un grant no envia cap correu.

Seguir l'accés com a compte cedent

El compte cedent pot seguir els seus accessos amb tres esdeveniments account.* als seus webhooks de compte:

El seu data és un objecte account_relation amb id, origin (granted), level, previous_level, grantor_account_id, grantee_account_id i status. Només els endpoints del compte cedent els reben: al compte receptor no se li envia res d'un accés cedit. Un canvi dels NIF de l'accés tampoc no es publica.

El compte receptor no es pot subscriure al que passa en un NIF cedit. Els webhook endpoints de l'eix de NIF hi responen 403 forbidden_action, com diu la taula anterior, i els seus webhooks de compte cobreixen només els seus propis NIF i els comptes que aprovisiona.

Tingues en compte

• Identitat d'enviament. Un NIF cedit no hereta res del compte receptor: el seu estat de confiança i la seva comprovació d'identitat d'enviament continuen sent els del seu propi compte. Enviament de documents descriu la comprovació.
• Automatitzacions. Les automatitzacions de cartera de l'empresa titular del compte receptor cobreixen, a més dels seus altres NIF, els NIF cedits en què l'accés és operate, i cap amb view. Automatitzacions les explica.

Relacionat