Più aziende (multi-company)
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
- 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
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
Crea l'azienda (scope companies:write, chiave live). Il membro della chiave ne diventa proprietario, quindi la stessa chiave può usarla subito:
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:
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)
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
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.