# Più aziende (multi-company) (https://docs.getbeel.com/it/api/companies)

Software house, marketplace e commercialisti gestiscono le aziende dei clienti da un solo account, con una sola chiave API.

Ogni azienda su Getbeel è un account separato, con i suoi dati fiscali, fatture, banca e invio SDI. Un account **principale** (il tuo studio, la tua software house o il tuo marketplace) può avere delle **aziende clienti**: le crei tu, ci lavori dall'app passando dall'una all'altra, e la chiave API (o la connessione MCP) dell'account principale può agire su ciascuna.

## Le regole [#le-regole]

- Chi aggiunge un'azienda cliente ne diventa **proprietario**. Vede l'azienda solo chi ne è membro: i colleghi dello studio vanno invitati dalla pagina **Membri** dell'azienda, come il cliente.
- Una chiave dell'account principale agisce su un'azienda cliente solo se il membro che l'ha creata può gestire quell'azienda (proprietario o membro, non revisore). Altrimenti la risposta è `404 company_not_found`, come per un'azienda che non esiste.
- Un solo livello: un'azienda cliente non può avere aziende clienti. Un'azienda cliente non vede l'account principale né le altre aziende clienti.
- Se l'account principale viene eliminato, le aziende clienti restano, con i loro dati e i loro membri.
- Per ora ogni azienda ha il suo piano: per inviare fatture reali allo SDI da un'azienda cliente serve l'add-on SDI su quell'azienda. Con una chiave di test la sandbox funziona su tutte, ma solo una chiave live può aggiungere aziende o modificarne i dati (`403 livemode_required`).

## Nell'app [#nellapp]

In **Aziende clienti** trovi l'elenco con lo stato SDI di ogni azienda (dati fiscali completi o cosa manca, invio SDI attivo) e **Aggiungi azienda**. Bastano ragione sociale e partita IVA; il resto si completa dopo in **Dati aziendali**. Per lavorare su un'azienda usa **Apri** o il selettore in alto nella barra laterale.

La voce **Aziende clienti** compare nella barra laterale dei team che hanno scelto **Commercialista** nei primi passi o che hanno già un'azienda cliente. Per tutti gli altri la pagina è in **Impostazioni → Azienda → Gestisci aziende clienti**. Dentro un'azienda cliente la voce non c'è: un'azienda cliente non può avere a sua volta aziende clienti.

## Con l'API [#con-lapi]

Crea l'azienda (scope `companies:write`, chiave live). Il membro della chiave ne diventa proprietario, quindi la stessa chiave può usarla subito:

```bash
curl -X POST https://www.getbeel.com/api/v1/companies \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Rossi Srl",
    "vat_number": "01234567890",
    "regime_fiscale": "RF01",
    "address": "Via Roma", "street_number": "1",
    "postal_code": "20121", "city": "Milano", "province": "MI"
  }'
```

La risposta è l'azienda, con `id` e `sdi_readiness` (`ready` e i campi `missing`). Poi invia il suo `id` nell'header **`Getbeel-Company`** su qualsiasi altro endpoint:

```bash
curl https://www.getbeel.com/api/v1/invoices \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Getbeel-Company: $COMPANY_ID"
```

Senza l'header le richieste agiscono sull'account della chiave. `GET /v1/me` con l'header mostra l'azienda su cui stai agendo.

| Endpoint                   | Scope             |                                                              |
| -------------------------- | ----------------- | ------------------------------------------------------------ |
| `GET /v1/companies`        | `account:read`    | L'account della chiave e le aziende clienti su cui può agire |
| `POST /v1/companies`       | `companies:write` | Aggiunge un'azienda cliente                                  |
| `GET /v1/companies/{id}`   | `account:read`    | Un'azienda (o l'account stesso)                              |
| `PATCH /v1/companies/{id}` | `companies:write` | Modifica solo i campi inviati                                |

`/v1/companies` è sempre relativo all'account della chiave: lì l'header `Getbeel-Company` non si applica. Una chiave di un'azienda cliente non può creare aziende (`409 company_nesting_not_allowed`).

Le chiavi create prima di questa funzione non hanno lo scope `companies:write`: per creare aziende via API crea una nuova chiave. Leggere e agire sulle aziende funziona con le chiavi esistenti.

## Con un assistente AI (MCP) [#con-un-assistente-ai-mcp]

Lo strumento `list_companies` elenca le aziende, `create_company` ne aggiunge una e `update_company` ne cambia i dati (chiave live); ogni altro strumento accetta `company_id` per agire su un'azienda cliente. Chiedi ad esempio: _"Elenca le aziende clienti e dimmi quali non sono pronte per lo SDI"_, oppure _"Crea una bozza di fattura per Rossi Srl…"_. I client che permettono header personalizzati possono usare anche `Getbeel-Company`.

## Webhook [#webhook]

Gli eventi di un'azienda cliente vanno agli endpoint configurati **su quell'azienda** (Impostazioni → Chiavi API e MCP dell'azienda) e agli endpoint corrispondenti dell'account principale, finché chi ha aggiunto l'endpoint dell'account principale può ancora gestire l'azienda. La copia per l'account principale contiene `company_id` (l'id dell'azienda, il valore di `Getbeel-Company`); quella dell'azienda no.
