API OCR & MRZ

Endpoint per la scansione e il riconoscimento automatico dei documenti d’identità tramite OCR (Optical Character Recognition) e parsing delle zone MRZ (Machine Readable Zone).

Elaborazione OCR

Elabora un’immagine di un documento d’identità tramite il servizio OCR.Space. Estrae il testo completo e, se presente, identifica automaticamente la zona MRZ.

POST /api/ocr

Parametri Body

Parametro Tipo Obbligatorio Descrizione
image string ✅ Immagine codificata in Base64

Esempio di Richiesta

{
  "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD..."
}

Risposta

{
  "text": "REPUBBLICA ITALIANA\nCARTA DI IDENTITÀ\nCOGNOME: ROSSI\nNOME: MARIO\n...\nIDITAROSSI<<MARIO<<<<<<<<<<<<<<<\n8503155M3012315ITA<<<<<<<<<<<4\nCA12345AB<411004<<<<<<<<<<<<<<"  ,
  "mrz": [
    "IDITAROSSI<<MARIO<<<<<<<<<<<<<<<",
    "8503155M3012315ITA<<<<<<<<<<<4",
    "CA12345AB<411004<<<<<<<<<<<<<<<"
  ]
}

Campi della Risposta

Campo Tipo Descrizione
text string Testo completo estratto dall’immagine
mrz string[] | null Righe MRZ identificate, oppure null se non rilevate

[!NOTE]
La qualità del riconoscimento dipende dalla risoluzione dell’immagine e dalla nitidezza del documento. Si consiglia di inviare immagini con risoluzione minima di 300 DPI.

Parsing MRZ

Analizza le righe MRZ estratte da un documento d’identità e restituisce i campi strutturati. Supporta i formati TD1, TD2 e TD3.

POST /api/mrz/parse

Parametri Body

Parametro Tipo Obbligatorio Descrizione
lines string[] ✅ Array con le righe MRZ (2 o 3 righe a seconda del formato)

Esempio di Richiesta (TD1 — CIE, 3 righe)

{
  "lines": [
    "IDITAROSSI<<MARIO<<<<<<<<<<<<<<<",
    "8503155M3012315ITA<<<<<<<<<<<4",
    "CA12345AB<411004<<<<<<<<<<<<<<<"
  ]
}

Esempio di Richiesta (TD3 — Passaporto, 2 righe)

{
  "lines": [
    "P<ITAROSSI<<MARIO<<<<<<<<<<<<<<<<<<<<<<<<<",
    "YA1234567<8ITA8503155M3012315<<<<<<<<<<<04"
  ]
}

Risposta

{
  "parsed": {
    "format": "TD1",
    "name": "MARIO",
    "surname": "ROSSI",
    "docNumber": "CA12345AB",
    "birthDate": "1985-03-15",
    "gender": "M",
    "nationality": "ITA",
    "expiryDate": "2030-12-31",
    "issuingCountry": "ITA",
    "valid": true
  }
}

Campi della Risposta

Campo Tipo Descrizione
format string Formato rilevato: TD1, TD2 o TD3
name string Nome dell’intestatario
surname string Cognome dell’intestatario
docNumber string Numero del documento
birthDate string Data di nascita (YYYY-MM-DD)
gender string Sesso (M o F)
nationality string Codice nazionalità ISO 3166-1 alpha-3
expiryDate string Data di scadenza (YYYY-MM-DD)
issuingCountry string Paese di emissione
valid boolean true se i check digit sono corretti

Salva Risultato Scansione

Salva i dati estratti dalla scansione di un documento nel database, pronti per essere associati a un ospite.

POST /api/save-scan

Parametri Body

Parametro Tipo Obbligatorio Descrizione
name string ✅ Nome estratto dal documento
surname string ✅ Cognome estratto dal documento
docNum string ✅ Numero del documento
birthDate string ✅ Data di nascita (YYYY-MM-DD)
gender string ✅ Sesso (M o F)
nationality string ✅ Codice nazionalità
expiryDate string ❌ Data di scadenza (YYYY-MM-DD)

Esempio di Richiesta

{
  "name": "Mario",
  "surname": "Rossi",
  "docNum": "YA1234567",
  "birthDate": "1985-03-15",
  "gender": "M",
  "nationality": "ITA",
  "expiryDate": "2030-12-31"
}

Risposta

{
  "success": true,
  "message": "Scansione salvata con successo",
  "id": 45
}

Formati MRZ Supportati

Il sistema supporta tre formati MRZ standard ICAO:

TD1 — Carta d’Identità Elettronica (CIE)

Formato a 3 righe da 30 caratteri ciascuna, utilizzato dalle Carte d’Identità Elettroniche italiane e da altri documenti di identità di formato carta di credito.

Riga 1: Tipo documento + Paese + Numero documento + Check digit
Riga 2: Data nascita + Sesso + Scadenza + Nazionalità + Check digit
Riga 3: Cognome << Nome

Esempio:

IDITACA12345AB<<<<<<<<<<<<<<<
8503155M3012315ITA<<<<<<<<<<<4
ROSSI<<MARIO<<<<<<<<<<<<<<<<<<<

TD2 — Documenti di Viaggio (2 righe, 36 caratteri)

Formato a 2 righe da 36 caratteri ciascuna, utilizzato da alcuni documenti di viaggio e carte d’identità.

Riga 1: Tipo + Paese + Cognome << Nome
Riga 2: Numero doc + Nazionalità + Data nascita + Sesso + Scadenza

Esempio:

I<ITAROSSI<<MARIO<<<<<<<<<<<<<<<<<<
CA12345AB<8ITA8503155M3012315<<<<<<

TD3 — Passaporto

Formato a 2 righe da 44 caratteri ciascuna, utilizzato da tutti i passaporti conformi allo standard ICAO.

Riga 1: P< + Paese + Cognome << Nome
Riga 2: Numero doc + Nazionalità + Data nascita + Sesso + Scadenza

Esempio:

P<ITAROSSI<<MARIO<<<<<<<<<<<<<<<<<<<<<<<<<
YA1234567<8ITA8503155M3012315<<<<<<<<<<<04

[!TIP]
Il formato MRZ viene rilevato automaticamente in base al numero di righe e alla loro lunghezza. Non è necessario specificare il formato manualmente.

Flusso di Scansione Completo

Il flusso tipico per la scansione di un documento è:

flowchart LR A[Foto Documento] --> B[POST /api/ocr] B --> C{MRZ rilevata?} C -->|Sì| D[POST /api/mrz/parse] C -->|No| E[Inserimento manuale] D --> F[POST /api/save-scan] E --> F F --> G[Dati ospite salvati]
  1. Scatta/carica una foto del documento
  2. Invia l’immagine all’endpoint OCR per l’estrazione del testo
  3. Se vengono rilevate le righe MRZ, parsale con l’endpoint dedicato
  4. Salva i dati estratti nel database
Previous Lettere Benvenuto Next Admin & Utenti