# Connessioni (https://docs.getbeel.com/it/api/connections)

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 [#elenco-delle-connessioni]

```bash
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 [#collega-una-casella]

Gmail e Outlook usano OAuth, che deve approvare una persona. L'API restituisce un link:

```bash
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.

```bash
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 [#scansiona-una-casella]

```bash
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 [#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 [#verifica-dei-documenti-raccolti]

I documenti raccolti sono le [fatture ricevute](/it/api/reference) con una `source` (`email`, `forwarded`, `manual`, `bank_transaction`). Quelli che aspettano una persona hanno `status: pending_review`:

```bash
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 [#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 [#con-un-assistente-ai]

Il [server MCP](/it/api/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.
