Integrare Verìd
con il tuo server

Panoramica

Al termine di ogni lettura (e dopo la Passive Authentication on-device), Verìd effettua una richiesta HTTP POST con corpo JSON verso l'URL configurato dall'operatore nelle impostazioni. I dati non passano mai per server intermediari: l'app parla direttamente con il tuo endpoint.

Attivazione

Nell'app, in Impostazioni → Webhook (richiede Verìd PRO):

• URL del webhook — l'endpoint HTTPS che riceve il POST.
• Token (opzionale) — inviato come Authorization: Bearer.
• Segreto HMAC (opzionale) — firma il corpo della richiesta.
• Includi la foto / Includi DG grezzi — disattivati di default.

Token e segreto si generano direttamente in app e si esportano in un file JSON da configurare sul tuo server: i due lati devono avere gli stessi valori.

La richiesta

POST /webhook HTTP/1.1
Host: gestionale.tuodominio.it
Content-Type: application/json; charset=utf-8
User-Agent: Verid-CIE-Reader
Authorization: Bearer <token>
X-Verid-Timestamp: 1782740547
X-Verid-Signature: sha256=9fa2...uL

Gli header Authorization e X-Verid-* sono presenti solo se hai configurato rispettivamente token e segreto HMAC.

Payload JSON

anagrafica e documento sono sempre presenti. I campi non disponibili sulla carta (es. telephone, profession) sono inclusi come null — non omessi. Gli array (placeOfBirth, address) possono essere vuoti se il dato non è presente. sessionRef, raw e photoPng compaiono solo se le relative opzioni sono attive.

{
  "source": "verid-cie-reader",
  "sessionRef": "VRD-7H2K9-A2",
  "anagrafica": {
    "firstName": "MARIO",
    "lastName": "ROSSI",
    "gender": "M",
    "dateOfBirth": "1985-04-12T00:00:00.000",
    "placeOfBirth": ["ROMA", "RM"],
    "fiscalCode": "RSSMRA85D12H501Z",
    "address": ["VIA ROMA 1", "00100 ROMA RM"],
    "telephone": null,
    "profession": null
  },
  "documento": {
    "number": "CA00000AA",
    "issueDate": "2025-04-12T00:00:00.000",
    "expiryDate": "2035-04-11T00:00:00.000",
    "nationality": "ITA",
    "country": "ITA",
    "authority": "COMUNE DI ROMA"
  },
  // solo se "Includi DG grezzi" è attivo
  "raw": {
    "dg1": "Yn...", "dg2": "...",
    "dg11": "...", "dg12": "...", "sod": "..."
  },
  // solo se "Includi la foto" è attivo
  "photoPng": "iVBORw0KGgo..."
}

Header

Verifica della firma HMAC

Se hai configurato un segreto, ogni richiesta è firmata con HMAC-SHA256. L'algoritmo è:

• Stringa da firmare: "{X-Verid-Timestamp}.{corpo grezzo}" — timestamp (stringa) + punto + il body HTTP esatto, non ri-serializzato.
• Chiave: il segreto condiviso in UTF-8.
• Output: esadecimale minuscolo con prefisso sha256=.
• Confronto: a tempo costante — usa hash_equals (PHP) o timingSafeEqual (Node.js) per evitare timing attack.
• Freschezza: verifica che X-Verid-Timestamp sia entro ±5 minuti dall'ora corrente per mitigare i replay.

Verifica del token

Se hai configurato un token, l'header Authorization arriva come Bearer <token>. Estrai il valore dopo Bearer e confrontalo con il token atteso usando un confronto a tempo costante. Rispondi 401 se non corrisponde.

Token e firma HMAC sono indipendenti e complementari: puoi usarne uno, entrambi o nessuno. Per la massima sicurezza usa entrambi.

QR di sessione (sessionRef)

Per collegare una lettura a una pratica del tuo gestionale, genera un QR dal tuo sistema con un identificativo (es. l'ID di un ordine o di un cliente). L'operatore lo scansiona prima della lettura e il valore torna nel payload come sessionRef.

• Quando la scansione QR è attiva nell'app, il QR è obbligatorio: senza, i dati non vengono inviati.
• Il contenuto del QR è arbitrario: usa l'identificativo che ti serve per fare il match lato server.
• Se il QR non è attivo, sessionRef non compare nel payload.

Data Group grezzi & Passive Authentication

Verìd esegue la Passive Authentication on-device: verifica l'integrità dei Data Group, la firma del SOD e la catena verso la CSCA italiana. Il risultato (authentic / notAuthentic / notEvaluable) è mostrato all'utente nell'app ma non è incluso nel payload webhook nella versione attuale.

Se vuoi ri-verificare la Passive Authentication lato server, attiva Includi DG grezzi: riceverai in raw i byte DER (base64) di dg1, dg2, dg11, dg12 e sod. La verifica lato server segue lo standard ICAO 9303.

Test di connettività

Il pulsante "Invia un test" nelle impostazioni invia una richiesta di prova al tuo endpoint (con gli stessi header di produzione, inclusi token e firma se configurati) con questo payload:

{
  "source": "verid-cie-reader",
  "test": true,
  "message": "Test di connettività dal pannello Verìd."
}

Puoi riconoscerlo dal campo "test": true e ignorarlo o loggarlo separatamente. Rispondere con un 2xx conferma all'app che l'endpoint è raggiungibile e le credenziali sono corrette.

Risposte e comportamento dell'app

L'app attende la risposta per un massimo di 20 secondi (15 per il test di connettività). Allo scadere del timeout, o in caso di errore di rete, l'invio è considerato fallito. Non ci sono retry automatici: l'utente vede il messaggio di errore e può riprovare manualmente.

Il corpo della risposta non viene letto dall'app: puoi restituire un JSON vuoto o un messaggio descrittivo a tua scelta — non ha effetto sulla UI.

Note di sicurezza

• Usa sempre HTTPS. L'app accetta HTTP in chiaro solo verso localhost e hostname *.local (rete locale mDNS, per i test). Per gli IP privati (10.x, 192.168.x, …) è richiesto HTTPS oppure un hostname .local: HTTP verso un IP privato viene bloccato dall'app.
• Confronto a tempo costante. Quando verifichi token o firma, non usare == o ===: un attaccante può dedurre quanti caratteri sono corretti misurando il tempo di risposta. Usa funzioni dedicate: hash_equals() in PHP, timingSafeEqual() in Node.js, o l'equivalente nel tuo linguaggio.
• Verifica la freschezza del timestamp. L'header X-Verid-Timestamp contiene l'ora Unix in secondi del momento in cui l'app ha firmato la richiesta. Rifiuta le richieste con timestamp più vecchio di 5 minuti (o futuro di oltre 1 minuto): questo blocca i replay, cioè un attaccante che cattura una richiesta legittima e la reinvia in seguito.
• Firma sul corpo grezzo. Calcola l'HMAC sul body HTTP esattamente come arriva, prima di qualsiasi parsing JSON. Se deserializzi e ri-serializzi il JSON potresti ottenere un ordinamento dei campi o una spaziatura diversa, che produce una firma diversa e fa fallire la verifica.
• Sei il titolare del trattamento. I dati anagrafici e biometrici che ricevi sono dati personali ai sensi del GDPR. Sei responsabile di conservarli in modo sicuro, di limitarne l'accesso e di rispettare i diritti degli interessati (accesso, cancellazione, portabilità). Verìd è il tramite tecnico, non il titolare.
• Richiedi solo i dati che ti servono. Foto e DG grezzi sono disattivati di default: abilitali solo se il tuo caso d'uso lo richiede davvero. Ogni dato non necessario che raccogli è un onere GDPR in più e una superficie di attacco in più in caso di breach.