GetbeelDocs

Commercialista (advisors)

Invitare un commercialista con accesso in sola lettura, vedere chi ha accesso, revocare un invito o rimuoverlo.

Un advisor è il commercialista dell'azienda: un membro del team con il ruolo in sola lettura auditor (nell'app Commercialista). Dopo aver accettato l'invito può leggere ed esportare fatture emesse e ricevute, movimenti bancari e la sezione Tasse, senza modificare nulla. È lo stesso invito di Invita il tuo commercialista nell'app.

Scope: advisors:read per l'elenco, advisors:write per invitare e rimuovere. Invitare o rimuovere qualcuno dà accesso a dati reali a una persona reale, quindi serve una chiave live (403 livemode_required con una chiave di test). advisors:write non è mai selezionato di default quando crei una chiave: va spuntato di proposito.

Il membro che ha creato la chiave deve poter fare lo stesso nell'app: invites.manage per invitare o revocare un invito, members.manage per rimuovere un membro (mai il proprietario principale né sé stesso). Altrimenti 403 invite_not_allowed o remove_not_allowed.

Invitare

curl https://www.getbeel.com/api/v1/advisors \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "email": "studio@commercialista.it" }'

201 con l'advisor, status: "invited". L'email di invito parte subito e scade dopo 7 giorni (expires_at). Un indirizzo che ha già un invito da commercialista in attesa riceve quell'invito con 200, senza una seconda email, quindi i tentativi ripetuti sono sicuri; revocalo per inviarne uno nuovo. Un indirizzo già nel team risponde 409 already_member; uno invitato con un altro ruolo 409 already_invited. Una policy di invito che rifiuta risponde 403 invite_not_allowed con il motivo.

{
  "id": "inv_42",
  "object": "advisor",
  "email": "studio@commercialista.it",
  "name": null,
  "role": "auditor",
  "status": "invited",
  "invited_at": "2026-11-09T10:00:00.000Z",
  "expires_at": "2026-11-16T10:00:00.000Z",
  "joined_at": null
}

Elenco

GET /v1/advisors restituisce gli advisor attivi (id mem_…, status: "active", joined_at) e gli inviti in attesa (inv_…). Gli altri membri del team non compaiono. L'elenco non è paginato (has_more è sempre false).

Rimuovere

DELETE /v1/advisors/{id}: inv_… revoca l'invito, mem_… toglie il commercialista dal team, che perde subito l'accesso. Risponde { "id", "object": "advisor", "deleted": true }.

Aziende clienti

Con l'header Getbeel-Company un account principale invita il commercialista di una delle sue aziende clienti, con le stesse regole.

Per invitare lo stesso commercialista a più aziende insieme (questo account e le sue aziende clienti), indicale in company_ids (al massimo 25):

curl https://www.getbeel.com/api/v1/advisors/invitations \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "email": "studio@commercialista.it", "company_ids": ["<id di questo account>", "<id azienda cliente>"] }'

POST /v1/advisors/invitations risponde 200 con un risultato per azienda, nell'ordine inviato: invited, already_invited (l'invito in sospeso, nessuna seconda email) o failed con il motivo (company_not_found per un id che non è questo account né un'azienda cliente che gestisci, already_member, invite_not_allowed, subscription_required, credits_exhausted, rate_limited). Ogni azienda è invitata esattamente come con POST /v1/advisors; se una non riesce, le altre proseguono. Senza company_ids invita all'azienda dell'header Getbeel-Company, altrimenti a questo account. Una chiave di test riceve 403 livemode_required. Nell'app: Aziende clienti → Invita il commercialista.

MCP e SDK

  • MCP: list_advisors, invite_advisor, invite_accountant (più aziende) e remove_advisor. L'assistente deve confermare con te l'indirizzo email prima di invitare.
  • TypeScript: getbeel.advisors.list(), getbeel.advisors.invite('studio@commercialista.it'), getbeel.advisors.remove('inv_42').
  • Python: client.advisors.list(), client.advisors.invite("studio@commercialista.it"), client.advisors.remove("inv_42").

In questa pagina