# Drive (https://docs.getbeel.com/it/api/drive)

Leggi il Drive dell'azienda per mese o cartella, scarica un file, carica documenti e gestisci le cartelle.

Il Drive contiene i documenti dell'azienda come li mostra l'app: i file delle fatture ricevute, gli estratti conto caricati e i documenti caricati, per mese e cartella.

Le letture richiedono `drive:read`, le scritture `drive:write` e una chiave live. Il Drive non mostra mai a una chiave più di quanto potrebbe leggere altrove: i file delle fatture ricevute richiedono anche `received_invoices:read`, gli estratti conto `bank:read`. Senza, quei file non compaiono nell'elenco e il download viene rifiutato.

## Elencare un mese o una cartella [#elencare-un-mese-o-una-cartella]

```bash
curl "https://www.getbeel.com/api/v1/drive?month=2026-10" \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

Invia `month` (`2026-10`) oppure `folder` (un percorso da `folders[].path`, come `contratti` o `2026-10/contratti`), uno dei due: un Drive intero può essere molto grande.

```json title="Risposta"
{
  "object": "drive",
  "month": "2026-10",
  "folder": null,
  "folders": [
    {
      "object": "drive_folder",
      "path": "2026-10",
      "name": "2026-10",
      "kind": "month",
      "month": "2026-10",
      "file_count": 2,
      "total_size": 418204,
      "updated_at": "2026-10-28T09:12:00.000Z",
      "writable": true
    }
  ],
  "files": [
    {
      "object": "drive_file",
      "id": "ZG9jdW1lbnQ6…",
      "name": "1761642720000_contratto.pdf",
      "kind": "document",
      "folder": "2026-10",
      "mime_type": "application/pdf",
      "size": 208102,
      "created_at": "2026-10-28T09:12:00.000Z",
      "document_date": "2026-10-28T09:12:00.000Z",
      "month": "2026-10",
      "vendor_name": null
    }
  ]
}
```

`kind` è `invoice` (il file di una fattura ricevuta), `reconciliation` (un estratto conto caricato) o `document`. Le cartelle sono `system` (fatture, riconciliazione), `month` o `custom`; si carica solo nelle cartelle con `writable: true`.

## Scaricare un file [#scaricare-un-file]

```bash
curl https://www.getbeel.com/api/v1/drive/files/$FILE_ID/download \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

La risposta ha `download_url`, un link privato valido 15 minuti, ed `expires_at`. Dai il link a chi serve il file; non salvarlo. Un file che non è di questa azienda, o che lo storage rifiuta, risponde `404`.

## Caricare un documento [#caricare-un-documento]

```bash
curl -X POST https://www.getbeel.com/api/v1/drive/files \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "folder": "2026-10", "file_url": "https://example.com/contratto.pdf" }'
```

- `folder` è un mese (la sua cartella si crea se manca), `documents` o una cartella personalizzata esistente.
- Invia `file_url` (`https` pubblico) oppure `file_base64` con `file_name`. PDF, PNG, JPEG, DOC o DOCX fino a 25 MB; il tipo si legge dal contenuto.
- Il file viene solo archiviato, l'AI non lo legge. Per registrare una fattura fornitore, [caricala come fattura ricevuta](/it/api/received-invoices#caricare-una-fattura).

| Stato | `code`                  | Quando                                              |
| ----- | ----------------------- | --------------------------------------------------- |
| 404   | `resource_missing`      | La cartella non esiste, o è una cartella di sistema |
| 413   | `payload_too_large`     | Oltre 25 MB                                         |
| 415   | `unsupported_file_type` | Non è un PDF, PNG, JPEG, DOC o DOCX                 |

## Cartelle [#cartelle]

```bash
curl -X POST https://www.getbeel.com/api/v1/drive/folders \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "name": "Contratti", "month": "2026-10" }'
```

- Una cartella va nella radice, o dentro un mese con `month`. Il percorso viene dal nome (`2026-10/contratti`). Un nome a forma di mese è rifiutato, e un nome già usato lì risponde `409 folder_exists`.
- `DELETE /drive/folders?path=2026-10/contratti` elimina definitivamente una cartella personalizzata e tutti i suoi file. Le cartelle dei mesi e di sistema non si eliminano.

## Eliminare un file [#eliminare-un-file]

```bash
curl -X DELETE https://www.getbeel.com/api/v1/drive/files/$FILE_ID \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

Elimina il file definitivamente, come Elimina nell'app. Il file di una fattura ricevuta richiede anche `received_invoices:write` (la fattura resta, senza il file); un estratto conto richiede `bank:write`.

<Callout type="warn" title="Autofatture allo SDI">
  Un estratto conto con autofatture che sono, o potrebbero essere, allo SDI è un
  documento fiscale: non si elimina (`409 statement_has_sent_autofatture`).
</Callout>

## MCP [#mcp]

`list_drive`, `get_drive_file`, `upload_drive_file`, `create_drive_folder`, `delete_drive_file`, `delete_drive_folder`.

## Correlati [#correlati]

- [Fatture ricevute](/it/api/received-invoices): i file che l'AI legge.
- [Riconciliazione bancaria](/it/api/bank-reconciliation): gli estratti conto nella cartella di riconciliazione.
- [Autenticazione](/it/api/authentication): gli scope `drive:read` e `drive:write`.
