GetbeelDocs

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.

EndpointScope
GET /v1/companiesaccount:readL'account della chiave e le aziende clienti su cui può agire
POST /v1/companiescompanies:writeAggiunge un'azienda cliente
GET /v1/companies/{id}account:readUn'azienda (o l'account stesso)
PATCH /v1/companies/{id}companies:writeModifica 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.

In questa pagina