Controllo dell'età

Stimi se una persona ha l'età richiesta a partire da un selfie, con ripiego sulla data di nascita del documento d'identità quando la stima è troppo vicina al limite.

POST /api/v1/kyc/age-estimation stima quanti anni sembra avere il volto in un selfie e lo confronta con un'età minima. È lo stesso controllo dell'opzione Controllo dell'età nei moduli (vedi Controllo dell'età), disponibile anche in modo autonomo.

Il risultato è una stima a partire da una foto, non una prova dell'età. Ogni risposta lo indica (isEstimate, disclaimer). Vicino al limite la risposta è inconclusive per progettazione: si ricorra a un controllo del documento d'identità.

Si autentichi con una chiave API (Authorization: Bearer ck_live_…) con l'ambito kyc:write. Vedi Autenticazione. La foto viene elaborata in memoria e non viene mai memorizzata.

Richiesta

Invii multipart/form-data oppure JSON.

curl -X POST https://app.certivant.com/api/v1/kyc/age-estimation \
  -H "Authorization: Bearer $CERTIVANT_API_KEY" \
  -H "Idempotency-Key: signup-8841" \
  -F image=@selfie.jpg \
  -F minAge=18 \
  -F buffer=5

{
  "imageBase64": "/9j/4AAQSkZJRg…",
  "minAge": 18,
  "buffer": 5,
  "dateOfBirth": "1990-02-03"
}

Campo	Tipo	Note
`image` / `imageBase64`	file / stringa	Un selfie frontale con un solo volto. JPEG, PNG, WebP o HEIC, fino a 10 MB. È accettato un URL `data:`
`minAge`	intero da 1 a 120, facoltativo	Predefinito: impostazione della Sua organizzazione (Impostazioni → Prevenzione delle frodi), inizialmente 18
`buffer`	intero da 0 a 30, facoltativo	Anni in più o in meno rispetto a `minAge` entro i quali la stima non è considerata affidabile. Predefinito: impostazione della Sua organizzazione, inizialmente 5
`dateOfBirth`	`YYYY-MM-DD`, facoltativo	La data di nascita di un documento d'identità che Lei ha già verificato. Usata quando la stima non è conclusiva

Invii un header Idempotency-Key per rendere gratuito un nuovo tentativo: la stessa chiave viene addebitata una sola volta.

Risposta

{
  "data": {
    "result": "pass",
    "method": "estimate",
    "minAge": 18,
    "buffer": 5,
    "isEstimate": true,
    "estimatedAge": 31.4,
    "estimateSpread": 3.2,
    "estimateConfidence": "high",
    "disclaimer": "An estimate from a photo, not proof of age.",
    "chargedCents": 7
  }
}

Campo	Note
`result`	`pass`, `fail` oppure `inconclusive`
`method`	`estimate` — ha deciso il selfie; `id_document` — ha deciso `dateOfBirth`; `none` — nessuno dei due ha potuto decidere
`isEstimate`	`true` quando la stima del selfie fa parte della risposta
`estimatedAge`, `estimateSpread`, `estimateConfidence`	La stima in anni, il suo margine di incertezza, e `high` oppure `low`. Presenti quando è stata effettuata una stima
`idAge`	Età in anni interi calcolata da `dateOfBirth`, quando è stata usata
`fallbackReason`	Perché è servito il documento d'identità: `near_limit`, `low_confidence`, `no_estimate` oppure `estimate_mismatch`
`mismatch`	Una stima attendibile e il documento d'identità non concordano. Va trattato come un caso da sottoporre a revisione manuale
`idCheckRequired`	`true` quando il risultato è `inconclusive` e non è stata inviata alcuna `dateOfBirth`: esegua un controllo del documento d'identità e richiami con la data di nascita, oppure indirizzi la persona a una verifica
`disclaimer`	Sempre presente. Lo mostri ovunque visualizzi la stima
`chargedCents`	Costo di questa chiamata

Come si decide

Stima pari o superiore a minAge + buffer → pass.
Stima inferiore a minAge − buffer → fail.
Nel mezzo, oppure se il modello non è sicuro della propria stima → decide dateOfBirth, se ne è stata inviata una. Senza di essa il risultato è inconclusive.
Quando invia una dateOfBirth che contraddice chiaramente la stima, mismatch è true: una stima molto superiore al limite con una data di nascita da minorenne dà fail (vince la data di nascita); una stima molto inferiore al limite con una data di nascita da adulto dà inconclusive, da far esaminare a una persona.

Errori

Stato	Quando
`400`	Immagine, `minAge`, `buffer` o `dateOfBirth` mancanti o non validi
`402`	Credito insufficiente per eseguire il controllo
`403`	Il controllo dell'età non è incluso nel Suo piano
`413`	Immagine più grande di 10 MB
`415`	Tipo di immagine non supportato
`422`	Nessun volto utilizzabile trovato (e nessuna `dateOfBirth` come ripiego)
`502`	Il servizio di stima non è disponibile. Riprovi con la stessa `Idempotency-Key`

Quando non viene trovato alcun volto ma è stata inviata una dateOfBirth, la chiamata risponde comunque in base al documento d'identità (method: "id_document").

Fatturazione

Il controllo dell'età è una funzione del piano, con una quota mensile inclusa e un prezzo a consumo per ogni controllo, scalato dal saldo del credito. Una chiamata che restituisce 402 o 403 non viene addebitata. Ogni controllo viene registrato nel registro di audit (age_estimation.checked) con il risultato e il metodo, mai la foto né la data di nascita.

Su una verifica

Quando un modulo ha il controllo dell'età attivo, la verifica stessa riporta il risultato: i suoi trigger di revisione o le sue cause di squalifica possono contenere age_requirement_not_met o age_check_inconclusive, e le politiche e i workflow possono verificare age.checked, age.result, age.method, age.estimatedAge, age.minimum, age.meetsMinimum e age.mismatch.