GetbeelDocs

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/stripe restituisce 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.

In questa pagina