Assessor extern

L'assessor extern és l'única persona aliena al teu equip a qui el teu compte deixa treballar amb els seus NIF, normalment qui et porta la comptabilitat. L'assessor entra al teu compte com a member amb grants (permisos per NIF) sobre els NIF que triïs, igual que qualsevol altre membre, amb tres diferències: n'hi ha un per compte, existeix en qualsevol pla i no ocupa plaça.

Aquesta guia explica què és el rol, com donar-lo des de l'aplicació web i des de l'API, quins plans només el poden gestionar des de l'aplicació web, què perd l'assessor quan el retires i quins errors esperar. L'assessor és una persona dins del teu compte. Si el despatx treballa des del seu propi compte, fes servir en lloc seu l'accés cedit, que és una relació entre dos comptes.

Què és el rol

A l'API, un membre indica si és l'assessor al camp external_advisor. El llistat de membres no té cap filtre per a això: recorre GET /v1/accounts/{account}/members i busca el membre amb external_advisor: true, del qual n'hi ha com a màxim un. Per a un titular o un administrador que el llegeix, el seu bloc permissions diu can_change_role: false i can_transfer_ownership: false, mentre que can_remove i can_edit_grants continuen en true.

Dona accés a l'assessor

L'assessor entra mitjançant una invitació enviada des de l'aplicació web. Un titular o un administrador obre la secció Assessor extern de la pàgina de gestió d'usuaris, tria Convida l'assessor, escriu l'adreça de correu, marca els NIF amb el seu nivell (view o operate) i decideix si Factuarea envia el correu o mostra l'enllaç una sola vegada perquè el copiïs. La persona l'accepta com qualsevol altra invitació i entra com a member amb la marca.

Per portar l'assessor per l'API, convida la persona com a member i marca el membre quan s'hi hagi unit. En un compte que ha arribat al seu topall d'usuaris aquesta primera invitació respon 422 business_rule_violation, així que fes servir l'aplicació web.

• D'un en un. Una segona invitació pendent de l'assessor respon 422 external_advisor_already_assigned, i el mateix passa en convidar l'assessor quan el compte ja en té un. Una invitació ordinària pendent no destorba. El mateix codi respon quan la persona accepta i un altre assessor ha ocupat el lloc mentrestant.
• Una invitació caducada continua ocupant el lloc. Una invitació d'assessor que va caducar sense revocar-se continua comptant fins que la revoques o convides un altre assessor, cosa que la revoca per tu.
• Segueix-la des de l'API. GET /v1/accounts/{account}/invitations llista una invitació pendent de l'assessor amb external_advisor: true, i les operacions que revoquen i reenvien una invitació hi actuen com sobre qualsevol altra.

Marca un membre com a assessor

Per convertir un membre existent en l'assessor, envia external_advisor al membre:

{member} i member_id són l'id del membre, el que publica el llistat de membres, no l'identificador de la persona. Les eines MCP de l'equip necessiten una API key: el canal OAuth no hi arriba.

curl -X PATCH "https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/members/$MEMBER_ID" \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "external_advisor": true }'

{
  "data": {
    "id": "01933a50-2c41-7a8b-9c0d-1e2f3a4b5c03",
    "object": "account_member",
    "name": "Laura Vidal",
    "email": "laura@despacho.example",
    "role": "member",
    "external_advisor": true,
    "grants": [
      {
        "object": "account_member_grant",
        "company_id": "0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e",
        "level": "view"
      }
    ],
    "permissions": {
      "can_change_role": false,
      "assignable_roles": [],
      "can_remove": true,
      "can_transfer_ownership": false,
      "can_edit_grants": true
    }
  }
}

• Qui pot. La persona que va emetre la credencial ha de ser titular o administrador del compte en el moment de la crida, amb la secció user_management disponible, i l'àmbit de la credencial ha de cobrir tots els NIF del compte, perquè la marca canvia quantes places ocupa tot l'equip. Si no, la resposta és 403 forbidden_action.
• Cos. external_advisor, role o tots dos, i almenys un. Els dos canvis s'apliquen junts o cap: primer es treu la marca, després canvia el rol i la marca es posa al final. Per això passar l'assessor a admin es fa amb una sola petició, { "role": "admin", "external_advisor": false }, i necessita una plaça lliure, com explica treure la marca.
• Marcar. Només es pot marcar un member, i només quan el compte no té un altre assessor. Tornar a marcar l'assessor actual no canvia res. El membre conserva els seus grants i deixa d'ocupar plaça. Una invitació d'assessor pendent no impedeix marcar un membre, però respondrà 422 external_advisor_already_assigned quan la seva persona l'accepti.
• Sense avís. Marcar i treure la marca no envien cap correu ni publiquen cap esdeveniment.

Plans sense gestió d'usuaris

Gestionar l'equip per l'API i el servidor MCP pertany al mòdul user_management, que inclouen els plans empresario i enterprise i no inclou emprendedor. Sense ell, els scopes members:* i invitations:* no es poden assignar a una clau i les eines de l'equip queden fora d'abast, així que l'assessor es gestiona només des de l'aplicació web. En un pla així, GET /v1/me deixa aquests scopes fora dels scopes efectius de la clau.

L'aplicació web no té aquest límit per a l'assessor. En qualsevol pla un titular o un administrador pot convidar l'assessor, veure'l amb els seus grants, canviar aquests grants, reenviar o cancel·lar la invitació, retirar l'assessor i treure-li la marca. Tota la resta de la gestió de l'equip continua bloquejada.

És una exclusió declarada, no una llacuna: permet que un compte amb un pla sense gestió d'equip doni accés a qui li porta la comptabilitat. La guia d'abast i limitacions la recull juntament amb la resta del que l'API no cobreix.

Canvia el que arriba a tocar l'assessor

Els grants de l'assessor són els de qualsevol member: a l'aplicació web, a la mateixa secció on el vas convidar, i a l'API i al servidor MCP amb les operacions de membres, que necessiten el mòdul user_management.

Revocar un grant tanca aquest NIF a l'assessor a l'aplicació web, a l'API i al servidor MCP, i baixar-lo d'operate a view el deixa en només lectura. Les dues coses baixen en conseqüència les API keys de la persona sobre aquest NIF, i una clau mai no guanya un nivell perquè el grant torni a pujar. Perquè l'assessor vegi menys sense retirar-lo, revoca o baixa el grant.

Retira l'assessor

Hi ha dues maneres d'acabar el rol, i fan coses diferents. Tria segons si la persona continua treballant al teu compte.

Treu l'assessor del compte

curl -X DELETE "https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/members/$MEMBER_ID" \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

La resposta és 204 sense cos. L'operació necessita members:write, un titular o un administrador amb la secció user_management disponible com a emissor i una credencial que cobreixi tots els NIF del compte. És irreversible, així que Idempotency-Key és obligatòria i una crida sense ella respon 422 idempotency_key_required. L'eina MCP delete_account_member també és irreversible i rep un idempotency_key. Això és el que perd l'assessor, igual als tres canals:

• Tots els NIF del compte, d'un cop. L'accés és un únic fet, la pertinença al compte, així que retirar-la tanca l'aplicació web, l'API i el servidor MCP alhora. No queda cap accés per canal que netejar.
• Les seves sessions. Es revoquen les sessions lligades a qualsevol NIF del compte o al sandbox d'algun. Les seves sessions a qualsevol altre lloc es mantenen.
• Les seves API keys. Les claus de la persona per a aquest compte perden els NIF del compte, i una clau que es queda sense cap es revoca.
• El seu usuari, només si res més el vincula. La persona s'elimina quan no té un altre compte, cap pertinença d'empleat ni cap empresa fora d'aquest compte. Si no, conserva el seu usuari i tota la resta.
• Sense marxa enrere. Els seus grants desapareixen. Per tornar-li a donar accés, convides la persona de nou des de l'aplicació web, amb els grants des de zero. El lloc de l'assessor queda lliure tan bon punt torna la crida.

Si només vols que l'assessor vegi menys, baixa els seus grants en lloc d'això.

Mantén la persona i treu la marca

Treure la marca deixa la persona al compte com a member amb els mateixos grants, i a partir d'aleshores ocupa plaça. El pla en necessita, doncs, una de lliure: sense ella la resposta és 422 business_rule_violation amb param external_advisor, i no canvia res. Allibera una plaça o retira l'assessor en lloc d'això. Treure la marca a un membre que no és l'assessor no canvia res.

Esdeveniments

Retirar l'assessor és un canvi de pertinença com qualsevol altre: publica account.member_removed als endpoints de webhook de compte que el tinguin subscrit, i acceptar la invitació publica account.member_added. Marcar i treure la marca no publiquen res, i el payload dels esdeveniments account.member_* porta el role però no la marca, així que llegeix external_advisor del membre quan el necessitis. Webhooks de compte descriu els endpoints i el sobre.

Errors

Relacionat