# Fatture ricevute (https://docs.getbeel.com/it/api/received-invoices)

Elenca e controlla le fatture dei fornitori, caricane una da far leggere all'AI e gestisci le categorie e le regole AI che le archiviano.

Le fatture ricevute sono le fatture e le ricevute dei fornitori della tua azienda: dallo SDI (`source: "sdi"`), raccolte dalle email (`email`) o dall'indirizzo di inoltro (`forwarded`), caricate (`manual`) o lette da un movimento bancario (`bank_transaction`). È lo stesso elenco di **Fatture ricevute** nell'app.

Le letture richiedono `received_invoices:read` e vanno con entrambe le modalità di chiave. Le scritture richiedono `received_invoices:write` e una chiave live: la contabilità è reale, non ne esiste una copia nella sandbox (`403 livemode_required` con una chiave di test).

## Elencare [#elencare]

```bash
curl "https://www.getbeel.com/api/v1/received-invoices?status=pending_review" \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

Dalla data fattura più recente, [con paginazione](/it/api/pagination). Filtra per `status` (`processing`, `pending_review`, `verified`, `rejected`, `exported`, `missing_document`), `source`, `search` e `date_from` / `date_to`. Con una chiave di test l'elenco contiene solo le fatture ricevute nella [sandbox](/it/api/sdi-receiving).

MCP: `list_received_invoices`, e `list_collected_documents` per quelle ancora da controllare.

## Approvare o rifiutare [#approvare-o-rifiutare]

```bash
curl -X POST https://www.getbeel.com/api/v1/received-invoices/$INVOICE_ID/approve \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

- `POST /received-invoices/{id}/approve` porta una fattura da `pending_review` (o `rejected`) a `verified`, come quando la controlli nell'app. Già verificata: non cambia nulla.
- `POST /received-invoices/{id}/reject` la porta da `pending_review` (o `verified`) a `rejected`: usalo per i documenti che non sono fatture.

MCP: `approve_collected_document`, con `decision: "reject"` per rifiutare.

## Reverse charge sulle fatture estere [#reverse-charge-sulle-fatture-estere]

Una fattura di un fornitore estero raccolta via email, dall'indirizzo di inoltro o da un caricamento porta `reverse_charge`: l'autofattura che getbeel ha proposto (`null` se non serve, per esempio fornitore italiano o fattura ricevuta dallo SDI).

```json title="reverse_charge"
{
  "tipo_documento": "TD17",
  "status": "proposed",
  "reason": "non_eu_services",
  "deadline_basis": "effettuazione",
  "deadline": "2026-12-15"
}
```

- `tipo_documento`: `TD17` servizi dall'estero, `TD18` beni da un altro stato UE, `TD19` beni già in Italia; `null` se nessun TD si applica o manca il paese del fornitore. Lo decide la regola, non l'AI.
- `status`, lo stato attuale della proposta: `proposed` (la bozza XML è generata da sola), `needs_review` (verificala prima nella pagina Autofatture), `needs_country` (inserisci il paese del fornitore), `not_required` (beni importati da fuori UE: vale il documento doganale, nessun TD), `generated` (la bozza XML esiste, non inviata), `sent` (consegnata allo SDI), `dismissed` (eliminata dal team).
- `reason` e `deadline` sono quelli fissati dalla regola quando la proposta è stata creata (o quando il team ne ha impostato paese e tipo).
- `deadline`: il 15 del mese successivo alla ricezione della fattura (fornitori UE, `receipt`) o all'acquisto (fornitori extra UE, `effettuazione`), art. 1, c. 3-bis, lett. b, d.lgs. 127/2015.

L'invio dell'autofattura allo SDI lo fa sempre una persona nell'app. Regole e fonti: [Autofatture](/it/guide/autofatture).

## Caricare una fattura [#caricare-una-fattura]

Invia un PDF, JPEG, PNG o WEBP (fino a 50 MB) da far leggere all'AI, come un caricamento nell'app.

```bash
curl -X POST https://www.getbeel.com/api/v1/received-invoices/uploads \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "file_url": "https://example.com/fattura-rossi.pdf" }'
```

```json title="Risposta"
{
  "object": "received_invoice_upload",
  "id": "scan_1794408453000_k3j9x2a",
  "status": "pending",
  "files": 1,
  "processed": 0,
  "skipped": 0,
  "error": null
}
```

- Invia `file_url` (un URL `https` pubblico, senza redirect) oppure `file_base64` con `file_name`. Il tipo si legge dal file, non dal nome.
- Ogni file usa un credito fattura ([Prezzi](/it/api/pricing)).
- `GET /received-invoices/uploads/{id}` lo segue: `pending` e `processing` mentre l'AI lo legge, `completed` quando la fattura è nell'elenco con `status: "pending_review"`, `failed` con il motivo in `error`. `skipped` conta i file che non erano fatture o erano duplicati.

| Stato | `code`                  | Quando                                                                                                   |
| ----- | ----------------------- | -------------------------------------------------------------------------------------------------------- |
| 413   | `payload_too_large`     | Il file supera i 50 MB                                                                                   |
| 415   | `unsupported_file_type` | Non è un PDF, JPEG, PNG o WEBP (gli XML FatturaPA arrivano dalla [ricezione SDI](/it/api/sdi-receiving)) |
| 402   | `credits_exhausted`     | Crediti fattura esauriti                                                                                 |

MCP: `upload_received_invoice`, `get_received_invoice_upload`.

## Categorie [#categorie]

Le categorie archiviano le fatture ricevute per tipo di costo. Una fattura ricevuta porta lo `slug` della categoria in `category`.

```bash
curl -X POST https://www.getbeel.com/api/v1/categories \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "label": "Software" }'
```

- `GET /categories` le elenca nell'ordine dell'app. `POST /categories` ne aggiunge una: lo slug viene dal nome, il colore dal prossimo predefinito, se non invii `color` (`#rrggbb` o `hsl()`).
- `PATCH /categories/{id}` rinomina o ricolora una categoria; lo slug resta. `DELETE /categories/{id}` la elimina e sposta le sue fatture in `other`. Le categorie predefinite non si eliminano (`409 default_category`).
- `POST /received-invoices/{id}/category` con `{ "category": "software" }` imposta la categoria di una fattura (`422 unknown_category` per uno slug che il team non ha).

MCP: `list_categories`, `create_category`, `update_category`, `delete_category`, `set_received_invoice_category`.

## Regole AI [#regole-ai]

Istruzioni in linguaggio naturale che l'AI segue, in ordine, quando legge le tue fatture. Le stesse regole di **Impostazioni → Regole AI**.

```bash
curl -X POST https://www.getbeel.com/api/v1/ai-rules \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "text": "Le fatture di Amazon Web Services vanno nella categoria software" }'
```

- `type` è `invoice_scan` (il predefinito: la lettura delle fatture ricevute) o `fattura_emessa` (le bozze delle fatture emesse dai pagamenti Stripe). Lo scope segue il tipo: le regole `invoice_scan` richiedono gli scope `received_invoices`, quelle `fattura_emessa` gli scope `invoices`.
- Una regola nuova va in fondo al suo tipo e vale per le prossime fatture che l'AI legge; quelle già lette restano come sono.
- `GET /ai-rules` le elenca (filtra con `type`). `PATCH /ai-rules/{id}` cambia il testo o mette in pausa la regola (`"active": false`). `DELETE /ai-rules/{id}` la elimina.

MCP: `list_ai_rules`, `create_ai_rule`, `update_ai_rule`, `delete_ai_rule`.

## Correlati [#correlati]

- [Connessioni](/it/api/connections): collega una casella e cercaci le fatture.
- [Ricezione SDI](/it/api/sdi-receiving): ricevi le fatture dei fornitori direttamente dallo SDI.
- [Webhook](/it/api/webhooks): `received_invoice.created` per ogni nuova fattura.
