# Commercialista (advisors) (https://docs.getbeel.com/it/api/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](/it/guide/report-e-commercialista#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 [#invitare]

```bash
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.

```json
{
  "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 [#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 [#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 [#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):

```bash
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-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")`.
