> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Report Document AI: campi estratti

> Guida al report Document AI di Didit: endpoint di caricamento documenti, JSON dei campi estratti per documento, stati e voci features[].

## Panoramica

Document AI accetta fino a 3 documenti per passaggio (PDF o immagine — PDF, JPG, JPEG, PNG, TIFF, WebP). Ogni documento viene classificato in base al relativo `document_key` configurato, letto da un modello di visione e linguaggio utilizzando uno schema ricavato dalle tue definizioni dei campi e sottoposto ad analisi forense PDF/EXIF. Per ogni documento vengono memorizzati:

* I **campi estratti** — una mappa indicizzata dalla `key` del campo che hai configurato, con valori tipizzati secondo la tua dichiarazione (`text` → string, `number` → number, `date` → `YYYY-MM-DD`). I campi che non è stato possibile leggere sono `null`.
* **Codici QR e codici a barre rilevati** - payload decodificati e coordinate in pixel per ogni pagina renderizzata. Un codice QR individuabile ma non decodificabile viene comunque restituito con `parsed_payload: null`.
* Lo **stato del documento** — `Approved`, `In Review`, `Declined` o `Not Finished`.
* **Metadati del documento** — analisi forense del file, compresa qualsiasi evidenza di sovrapposizione o manipolazione.
* **Risultati del controllo incrociato** — l'esito della corrispondenza del nome con l'identità verificata e di eventuali riferimenti incrociati tra campi personalizzati.

## Caricamento dei documenti

I documenti vengono caricati uno alla volta sull'endpoint di Document AI. In una sessione ospitata o in un flusso SDK questa operazione è gestita automaticamente; il contratto è:

```text theme={null}
POST https://verification.didit.me/v3/document-ai/documents/
multipart/form-data — Session-Token: <session token>
```

| Campo | Obbligatorio | Descrizione |
| - | - | - |
| `document_key` | sì | Il documento configurato a cui corrisponde questo file |
| `document` | sì | Il file da caricare |
| `locale` | no | Locale utilizzato per risolvere titolo e descrizione a schermo |

La risposta fa avanzare il flusso:

```json theme={null}
{
  "valid": true,
  "next_step": "DOCUMENT_AI",
  "document_ai_status": "In Progress",
  "uploaded_document_keys": ["proof_of_funds"],
  "required_document_keys": ["proof_of_funds", "payslip"]
}
```

Il passaggio si completa (`next_step` supera `DOCUMENT_AI`) una volta che ogni voce presente in `required_document_keys` compare in `uploaded_document_keys` e nessun documento rimane incompleto.

## Dove compare nelle risposte API

`GET /v3/session/{sessionId}/decision/` mostra Document AI in due punti, sia per le sessioni di Verifica degli utenti (KYC) sia per quelle di Verifica aziendale (KYB) — l'array `document_ai_documents[]` e il report PDF sono identici a prescindere dal valore di `session_kind`:

* **`features[]`** — una voce di riepilogo per ciascun nodo Document AI, utilizzata per elencare quali funzionalità sono state eseguite:

  ```json theme={null}
  { "features": [ { "feature": "DOCUMENT_AI", "node_id": "feature_document_ai_1" } ] }
  ```

* **`document_ai_documents[]`** — il risultato completo, un gruppo per ciascun nodo Document AI. Ogni gruppo contiene lo `status` combinato del nodo, l'elenco degli `items` caricati e gli eventuali `warnings`. Ogni documento caricato è un elemento con i campi configurati (sotto `extracted_data`), i codici rilevati (sotto `detected_codes`), il proprio `status`, le definizioni dei campi, i metadati forensi `document_metadata` e il `cross_check_result`.

Gli stati dei singoli documenti di ciascun nodo si combinano nello stato del nodo applicando la precedenza **Declined > In Review > Approved**.

## Esempio di decisione

Per un documento di **Prova dei fondi** configurato con `account_holder` (text), `balance` (number), `currency` (text) e `statement_date` (date):

```json theme={null}
{
  "document_ai_documents": [
    {
      "node_id": "feature_document_ai_1",
      "status": "Approved",
      "items": [
        {
          "uuid": "5c1f0a2e-9b3d-4c7a-8f21-0a4e8e7d6c12",
          "document_key": "proof_of_funds",
          "status": "Approved",
          "original_filename": "statement.pdf",
          "extracted_data": {
            "account_holder": "Sophia Martinez",
            "balance": 18450.75,
            "currency": "EUR",
            "statement_date": "2026-05-31"
          },
          "detected_codes": [
            {
              "type": "QR_CODE",
              "page_number": 2,
              "position": [[124, 86], [306, 86], [306, 268], [124, 268]],
              "x": 124,
              "y": 86,
              "width": 182,
              "height": 182,
              "page_width": 1190,
              "page_height": 1684,
              "raw_payload": "SU5WLTIwMjYtMDA0Mg==",
              "parsed_payload": "INV-2026-0042"
            }
          ],
          "fields": [
            { "key": "account_holder", "name": "Account holder", "type": "text", "required": true },
            { "key": "balance", "name": "Balance", "type": "number", "required": false },
            { "key": "currency", "name": "Currency", "type": "text", "required": false },
            { "key": "statement_date", "name": "Statement date", "type": "date", "required": false }
          ],
          "document_metadata": { "is_tampered": false },
          "cross_check_result": null,
          "created_at": "2026-05-31T10:12:00Z"
        }
      ],
      "warnings": []
    }
  ]
}
```

`page_number` inizia da 1. `position` contiene il poligono rilevato, mentre `x`, `y`, `width` e `height` forniscono il relativo riquadro di delimitazione. Tutte le coordinate utilizzano lo spazio in pixel della pagina renderizzata, le cui dimensioni sono `page_width` e `page_height`. `detected_codes` è un array vuoto quando non viene trovato alcun codice supportato. Considera un elemento con `parsed_payload: null` solo come presenza e posizione, non come valore decodificato.

Dato che ogni campo è indirizzabile come `document_ai.<field_key>`, puoi gestire la diramazione e le [regole di stato personalizzate](https://docs.didit.me/it/core-technology/document-ai/warnings-document-ai.md) direttamente dai valori di `extracted_data` — inclusi i riferimenti incrociati con altri passaggi come `kyc.full_name` o le risposte ai questionari.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.