Documentazione per sviluppatori di Certivant
Sviluppi con l'API di Certivant — KYC, KYB, caricamento dei documenti, sessioni ospitate ed eventi webhook.
Benvenuto nella documentazione per sviluppatori di Certivant. Questo è il riferimento tecnico per integrare la piattaforma KYC e KYB di Certivant nel Suo prodotto.
Se cerca come usare Certivant nel browser, consulti invece la documentazione per i tenant — questo sito presuppone che Lei stia scrivendo codice che dialoga con l'API REST.
Cosa si può costruire
- Eseguire una verifica dell'identità (KYC) dalla Sua app — inviare un richiedente, raccogliere i documenti tramite una sessione ospitata o con la Sua interfaccia, e ricevere una decisione di approvazione, rifiuto o inoltro.
- Eseguire una verifica aziendale (KYB) — inviare i dati dell'azienda, degli amministratori e dei titolari effettivi (UBO), e verificarli rispetto ai registri e alle liste delle sanzioni.
- Ricevere webhook in tempo reale quando una richiesta cambia stato, viene caricato un documento o un controllo viene completato.
- Gestire le richieste dalla dashboard tramite un'automazione propria — gli stessi endpoint alimentano l'interfaccia web di Certivant.
- Attribuire le richieste ai Suoi clienti (modalità partner) — eseguire verifiche per molti clienti finali all'interno di un'unica organizzazione, etichettare ogni richiesta con un nome di sub-tenant e un ID esterno, e filtrarla o instradarla tramite l'API e i webhook.
In sintesi
| URL di base | https://app.certivant.com/api/v1/kyc |
| Autenticazione | Authorization: Bearer ck_live_… o ck_test_… (chiave API, per organizzazione; le chiavi precedenti kyk_… continuano a funzionare) |
| Tipo di contenuto | application/json (o multipart/form-data per il caricamento dei documenti) |
| Limite di frequenza | In base al piano — vedi Limiti di frequenza |
| Firma del webhook | X-Certivant-Signature-V2: t=…,v1=… (HMAC-SHA256 su timestamp.body, tolleranza di 300 s) — vedi Verifica della firma |
| Riferimento interattivo | Riferimento API, oppure apra direttamente /api/v1/docs — pubblico, generato dallo schema OpenAPI |
| Schema OpenAPI | /api/v1/openapi.json — OpenAPI 3.1 pubblico, senza accesso |
Un solo host, non un sottodominio per ogni tenant. Nel servizio ospitato tutte le organizzazioni condividono lo stesso host, app.certivant.com — non esiste un indirizzo del tipo organizzazione.certivant.com, quindi usi app.certivant.com in questi esempi così com'è. (Le installazioni self-hosted usano il dominio configurato dal gestore; certivant.com è il sito di marketing, non l'app.) Per l'API, la Sua organizzazione è identificata dalla chiave API, mai dall'URL: il percorso base è /api/v1/kyc senza alcuno slug dell'organizzazione. Lo slug compare solo dove una persona naviga — la dashboard in /app/{org-slug} e i link ai moduli e alle sessioni ospitate come /forms/{slug}. Un dominio personalizzato white-label può far sì che questi link rivolti alle persone usino il Suo dominio, ma l'host dell'API non cambia.
La documentazione interattiva e lo schema OpenAPI grezzo sono pubblici:
non serve né l'accesso né una chiave API, e descrivono solo gli endpoint
dell'integrazione (/api/v1). Vedi Riferimento API.
Per iniziare
Riferimento
- Moduli — elencare i moduli KYC e KYB del tenant per scegliere con quale eseguire una verifica.
- Richieste KYC — creare, elencare, recuperare, inviare, decidere e reinviare.
- Richieste KYB — verifica aziendale con amministratori e UBO.
- Documenti — caricare documenti d'identità e recuperare gli URL di download firmati.
- Sessioni ospitate — generare un URL a breve scadenza in cui il richiedente completa il flusso.
- Lista di blocco — aggiungere e rimuovere indirizzi email, numeri di telefono, numeri di documento e indirizzi IP bloccati, oppure bloccare il volto, il dispositivo e l'IP dietro una verifica.
- Controllo dell'età — stimare da un selfie se una persona ha l'età richiesta, con ripiego sulla data di nascita indicata nel documento.
- Verifiche riutilizzate — consentire a un richiedente che ha già superato una verifica Certivant altrove di riutilizzarla con Lei (persone fisiche e aziende).
- Integrazione nel Suo sito o nella Sua app — mostrare una verifica nella Sua pagina con un solo tag script, oppure in una WebView React Native o Flutter.
- Riferimento API (OpenAPI) — il documento pubblico OpenAPI 3.1 e il riferimento interattivo.
- Verifica dal vivo — pianificare, monitorare, riprogrammare o annullare una sessione di verifica dell'identità dal vivo condotta da un operatore, e ricevere l'esito tramite webhook.
- Live ID Validation — accesso biometrico: confrontare il selfie dal vivo di un utente di ritorno con il volto della sua verifica KYC.
- Server MCP — collegare un assistente IA alla coda delle verifiche tramite il Model Context Protocol.
- Webhook — registrare un URL, verificare le firme, gestire i nuovi tentativi.
- Errori — codici di errore, corrispondenza con gli stati HTTP, forma dei campi di validazione.
- Limiti di frequenza — quote, intestazioni, strategia di nuovo tentativo.
- Schemi — enumerazioni, valori di stato, forme di richieste e risposte che incontrerà spesso.