Sessioni ospitate

Una sessione ospitata è il modo più semplice per raccogliere i documenti. Lei crea la richiesta lato server, poi chiede a Certivant un URL di sessione e lo consegna al richiedente. Certivant gestisce il caricamento dei documenti, l'acquisizione con la fotocamera, il controllo di vivacità, il feedback dell'OCR e i nuovi tentativi — Lei deve solo attendere il webhook.

Quando usare una sessione

La maggior parte delle integrazioni usa le sessioni. Il caricamento dei documenti tramite API è una soluzione alternativa per casi particolari.

Generare un URL di sessione

POST /api/v1/kyc/requests/:id/session-url    Ambito: kyc:write

La richiesta deve trovarsi nello stato PENDING_UPLOAD.

Corpo della richiesta

{
  "expiresInHours": 72,
  "redirectUrl": "https://yourapp.example.com/onboarding/complete"
}

Risposta

{
  "sessionUrl": "https://app.certivant.com/s/01HZ7K8Y...",
  "expiresAt": "2026-05-30T10:00:00.000Z"
}

L'URL contiene un token firmato monouso. Dopo la scadenza (oppure dopo l'invio da parte del richiedente) viene invalidato. Generi un nuovo URL se il richiedente ha bisogno di un altro tentativo.

Il flusso del richiedente

graph LR
  A[You email the session URL] --> B[Applicant clicks]
  B --> C[Welcome screen with your branding]
  C --> D[Capture front of ID]
  D --> E[Capture back of ID]
  E --> F[Capture selfie + liveness]
  F --> G[Confirm details extracted from ID]
  G --> H[Submit]
  H --> I[Thank-you page]
  I --> J{redirectUrl set?}
  J -->|yes| K[Redirect to your URL]
  J -->|no| L[Stay on Certivant page]
  H -.->|automatically| M[POST /submit fires]
  M -.->|webhook| N[kyc.request.processing]

Il richiedente non ha bisogno di un account per usare l'URL di sessione — Certivant non gli rilascia alcun accesso. Completa il flusso ed esce. Tutto lo stato risiede sulla richiesta, non su un record utente.

Personalizzazione e white-label

L'interfaccia ospitata riprende le impostazioni white-label della Sua organizzazione — logo, colore del brand, email di assistenza, dominio personalizzato se ne ha configurato uno. Le configuri una sola volta in Impostazioni → White-label nella dashboard; ogni sessione le eredita.

Domini personalizzati

Per impostazione predefinita le sessioni ospitate e i moduli vivono sull'host condiviso di Certivant (app.certivant.com/s/…). Se li vuole sul proprio dominio (verify.yourcompany.com al posto di quello), configuri un dominio personalizzato in Impostazioni → White-label → Dominio personalizzato. Questo sposta solo i link rivolti al richiedente — l'host dell'API e il percorso base /api/v1/kyc restano invariati, e la Sua organizzazione è sempre identificata dalla chiave API.

Desktop e mobile

La sessione è reattiva e funziona su telefoni, tablet e desktop. L'acquisizione dei documenti usa la fotocamera del dispositivo su mobile; su desktop, Certivant chiede al richiedente di passare al telefono tramite un codice QR, così che il controllo di vivacità e la scansione del documento usino la fotocamera migliore. Questo avviene in automatico — la Sua integrazione non deve rilevare nulla.

Cosa succede dopo l'invio

Quando il richiedente clicca su Invia nella pagina ospitata:

1. Certivant chiama internamente POST /requests/:id/submit per conto del richiedente.
2. La richiesta passa in PROCESSING.
3. Viene attivato il primo webhook: kyc.request.processing.
4. L'elaborazione termina (di norma in pochi secondi). Viene attivato un secondo webhook: kyc.request.approved, kyc.request.rejected oppure kyc.request.escalated.
5. Se ha fornito redirectUrl, il richiedente viene inviato lì. Altrimenti vede una pagina di ringraziamento.

Il Suo backend deve attendere il webhook — non interroghi l'endpoint della richiesta per rilevare il completamento. Vedi Webhook.

Riutilizzare un URL di sessione dopo un rifiuto

Se la richiesta viene rifiutata e Lei chiama POST /requests/:id/resubmit, l'URL di sessione esistente non viene riattivato. Ne generi uno nuovo:

# 1. Reset the rejected request
curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_.../resubmit \
  -H "Authorization: Bearer ck_live_..."

# 2. Generate a fresh session URL
curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_.../session-url \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{"expiresInHours": 24}'

Poi invii via email il nuovo URL al richiedente. Suggerimento: usi lo stesso externalRef così che la riga del Suo database resti correlata.

I moduli come alternativa

Se deve raccogliere dati strutturati (non solo documenti) — risposte a questionari di conformità, dettagli sull'origine dei fondi, campi KYB aggiuntivi — usi i Moduli al posto della sessione o in aggiunta a essa. I moduli si trovano nella dashboard in KYC → Moduli, e ogni modulo ha un URL pubblico di invio: https://app.certivant.com/forms/:slug.

I moduli creano automaticamente una richiesta KYC all'invio, allegano le risposte come metadati e attivano gli stessi webhook. Consulti la documentazione per i tenant su Moduli per la configurazione. Gli sviluppatori di solito non interagiscono con i moduli tramite API — l'interfaccia prevista è il generatore di moduli della dashboard.

Errori

• 400 BAD_REQUEST — la richiesta non è nello stato PENDING_UPLOAD. Gli URL di sessione si possono generare solo per richieste in attesa di documenti.
• 400 VALIDATION_ERROR — expiresInHours è al di fuori dell'intervallo 1–168, oppure redirectUrl non è un URL valido.

Note sulla sicurezza

• L'URL di sessione contiene un token firmato — chiunque lo possieda può completare la verifica. Lo tratti come un link di reimpostazione della password: lo invii direttamente al richiedente tramite un canale a cui solo lui può accedere.
• Usi scadenze brevi (expiresInHours pari a 24 o 48) per i flussi ad alto rischio. Usi una scadenza più lunga solo quando ci si aspetta che il richiedente abbia tempo per raccogliere i documenti.
• Se una sessione scade senza essere usata, la richiesta sottostante resta in PENDING_UPLOAD. Generi un nuovo URL oppure contatti il richiedente per inviarglielo di nuovo.