Connessioni
Collega caselle email e Stripe, cerca le fatture dei fornitori e verifica i documenti raccolti.
Getbeel raccoglie le fatture dei fornitori dalla posta (Gmail, Outlook, IMAP o un indirizzo di inoltro) e trasforma le fatture Stripe in fatture elettroniche. L'API espone le stesse connessioni di Impostazioni → Email e della pagina fatture emesse.
Scope: connections:read per leggere, connections:write per collegare, scansionare e sincronizzare; received_invoices:write per approvare i documenti raccolti. La lettura funziona con qualsiasi chiave; le modifiche richiedono una chiave live (altrimenti 403 livemode_required). Ogni documento letto con l'AI si paga dal saldo prepagato (402 insufficient_balance se non basta).
Elenco delle connessioni
curl https://www.getbeel.com/api/v1/connections \
-H "Authorization: Bearer $GETBEEL_API_KEY"Ogni connessione ha provider (gmail, outlook, imap, forwarding, stripe), active e health.status: healthy, reconnect_required (va ricollegata), error o unknown.
Collega una casella
Gmail e Outlook usano OAuth, che deve approvare una persona. L'API restituisce un link:
curl -X POST https://www.getbeel.com/api/v1/connections/email \
-H "Authorization: Bearer $GETBEEL_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "provider": "gmail" }'Apri url in un browser con l'accesso a Getbeel come membro del team (altrimenti ti chiede di accedere), approva l'accesso e torni nell'app. La casella compare poi in GET /connections.
IMAP si collega direttamente: Getbeel prova l'accesso (porta 993, TLS) e salva la password cifrata. Usa una password per le app.
curl -X POST https://www.getbeel.com/api/v1/connections/email \
-H "Authorization: Bearer $GETBEEL_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "provider": "imap", "email": "fatture@example.it", "password": "password-app", "host": "imap.example.it" }'Le nuove caselle contano nel limite del piano (402 quando è raggiunto).
Scansiona una casella
curl -X POST https://www.getbeel.com/api/v1/connections/$CONNECTION_ID/scan \
-H "Authorization: Bearer $GETBEEL_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "from": "2026-10-01", "to": "2026-10-31" }'Al massimo un anno per richiesta. La scansione prosegue in background (202); ogni fattura trovata invia received_invoice.created e compare in GET /received-invoices?source=email.
Indirizzo di inoltro
GET /forwarding-address restituisce l'indirizzo a cui inoltrare le fatture dei fornitori, oppure null finché non lo attivi nell'app (serve l'add-on di instradamento email). Le fatture inoltrate hanno source: forwarded.
Verifica dei documenti raccolti
I documenti raccolti sono le fatture ricevute con una source (email, forwarded, manual, bank_transaction). Quelli che aspettano una persona hanno status: pending_review:
curl "https://www.getbeel.com/api/v1/received-invoices?status=pending_review" \
-H "Authorization: Bearer $GETBEEL_API_KEY"
curl -X POST https://www.getbeel.com/api/v1/received-invoices/$INVOICE_ID/approve \
-H "Authorization: Bearer $GETBEEL_API_KEY"approve imposta verified, reject imposta rejected. I documenti ancora in lettura, i segnaposto di documento mancante e quelli esportati non si possono verificare (409).
Stripe
POST /connections/striperestituisce un link a Stripe Connect; dopo l'approvazione torni alla pagina fatture emesse.POST /connections/stripe/sync(facoltativo{ "from", "to" }, di default gli ultimi 30 giorni) importa le fatture Stripe come fatture emesse. Richiede l'add-on SDI e la quota; se la connessione ha l'invio automatico attivo, le fatture vanno anche allo SDI.
Con un assistente AI
Il server MCP ha list_connections, connect_mailbox (restituisce il link), scan_mailbox, list_collected_documents e approve_collected_document. Le password IMAP non passano mai dall'assistente: collega IMAP nell'app o con l'API.