Sviluppatore — chiavi API e API REST

Cosa fa

L'API REST di Certivant consente ai propri sistemi di creare richieste di verifica, caricare documenti e recuperare lo stato, senza passare dalla dashboard. Due casi d'uso principali:

1. Integrare la verifica nel proprio processo di onboarding. Il modulo di registrazione invia i dati al proprio backend, il backend chiama Certivant e il richiedente riceve un link al flusso ospitato di Certivant.
2. Sincronizzare lo stato delle verifiche nel proprio data warehouse o CRM. Combinare con i webhook affinché i propri sistemi si aggiornino alla variazione di stato.

L'autenticazione API avviene tramite chiavi API emesse dalla dashboard. La documentazione completa degli endpoint si trova in /app/{your-org}/kyc/developer: questa pagina tratta la gestione delle chiavi e la panoramica concettuale.

Dove si trova

KYC → Sviluppatore nella barra laterale sinistra. (Le chiavi API si trovavano nelle impostazioni KYC/B: ora hanno una sezione dedicata Sviluppatore.)

Il portale per sviluppatori è un unico punto di accesso con un menu a sinistra:

• Panoramica e avvio rapido: l'URL di base, l'autenticazione e una richiesta da copiare e incollare in 8 linguaggi (cURL, JavaScript, TypeScript, Python, PHP, Go, Java, C#). Gli esempi sono precompilati con il proprio host reale e un segnaposto per la chiave.
• Chiavi API: elencare, creare e revocare le proprie chiavi.
• Riferimento degli endpoint: ogni endpoint dell'integrazione (/v1) con metodo, percorso, ambiti e parametri, più un link al Playground API interattivo.
• Gestori dei webhook: gestori pronti all'uso che verificano la firma, in 6 linguaggi (vedi anche Webhook).
• Limite di frequenza: il limite effettivo al minuto della propria organizzazione, mostrato in sola lettura.
• FAQ: le domande più frequenti degli integratori.

Emettere una chiave API

Usare la chiave

Inviarla nell'intestazione Authorization:

Authorization: Bearer ck_live_a3f...

Le chiavi create prima del formato ck_live_ / ck_test_ (che iniziano con kyk_) continuano a funzionare senza modifiche.

Il percorso più rapido verso un'integrazione funzionante:

curl https://api.certivant.com/api/v1/kyc/requests \
  -H "Authorization: Bearer $CV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "INDIVIDUAL",
    "applicant": {
      "fullName": "Jane Doe",
      "email": "jane@example.com"
    }
  }'

Attribuzione ai partner e ai sotto-tenant

Se si eseguono verifiche per conto di molti clienti finali da un'unica organizzazione, lo schema classico di partner o rivenditore (per esempio una piattaforma di firma elettronica che verifica i firmatari per centinaia di aziende), non serve un'organizzazione per ogni cliente. Taggare ogni richiesta con due campi facoltativi al momento della creazione tramite API:

• subTenantName: il nome visualizzato del cliente finale (per esempio "Acme Corp").
• subTenantExternalId: il proprio id interno per quel cliente (per esempio cust_8842).

Una volta taggate, è possibile:

• Filtrare l'endpoint dell'elenco tramite subTenantExternalId (GET /api/v1/kyc/requests?subTenantExternalId=cust_8842).
• Instradare i webhook: entrambi i campi sono riportati in ogni envelope dell'evento, così il gestore sa a quale cliente appartiene un esito senza ricerche.
• Filtrare le dashboard: Utilizzo KYC/B, Registro di audit, Monitoraggio, Report e Analisi ottengono tutti un filtro Sotto-tenant non appena una richiesta contiene i tag, e gli elenchi KYC/KYB possono mostrare le colonne Sotto-tenant + ID esterno (nascoste per impostazione predefinita: attivarle dal menu delle colonne).

Per la forma esatta della richiesta, consultare il riferimento API: Richieste KYC → Crea una richiesta.

Limiti di frequenza

Il proprio limite di richieste API al minuto è impostato dal piano (valori predefiniti tipici: 60/min su Launch, 300/min su Pro/Scale, 600/min su Enterprise). Il valore massimo esatto della propria organizzazione è mostrato in sola lettura nella pagina Sviluppatore, e ogni risposta API lo riporta nell'intestazione X-RateLimit-Limit. Ogni chiave viene misurata in modo indipendente rispetto a questo massimale.

Quando lo si supera, le richieste restituiscono HTTP 429 Too Many Requests con X-RateLimit-Reset (secondi prima che la finestra si reimposti). Rallentare e riprovare.

Serve un massimale più alto? Lo imposta il super amministratore: può aumentare il limite del proprio cliente fino al massimo del piano da Amministrazione → Clienti → (la propria organizzazione) → Modifica organizzazione (un massimale più alto richiede un piano superiore). Il limite è controllato dall'operatore: i tenant possono visualizzarlo ma non modificarlo. Per la meccanica completa, consultare il riferimento per sviluppatori: Limiti di frequenza.

Buone pratiche di sicurezza

• Conservare le chiavi in variabili d'ambiente o in un gestore di segreti. Non committarle mai in git, non condividerle in chat. Le chiavi committate in repository pubblici vengono rilevate e sfruttate in pochi minuti.
• Una chiave per ambiente. Non condividere una chiave ck_live_... tra staging e produzione: la rotazione di una non deve influire sull'altra.
• Usare chiavi con ambiti limitati. Una chiave di sola lettura per il monitoraggio e una chiave di scrittura per il servizio di onboarding sono più sicure di un'unica chiave onnipotente ovunque.
• Vincolare le chiavi ai propri server. Aggiungere la lista degli indirizzi IP consentiti per le chiavi usate solo da indirizzi fissi.
• Ruotare ogni trimestre. Usare Ruota (vedi sotto): la vecchia chiave continua a funzionare per la sovrapposizione scelta, così si può distribuire la nuova senza interruzioni. Il registro di audit registra il passaggio.
• Controllare gli utilizzi non autorizzati. L'elenco delle chiavi mostra quando e da quale indirizzo è stata usata per l'ultima volta ciascuna chiave, e il registro di audit registra creazione, modifiche, rotazione e revoca. Indagare su qualsiasi indirizzo non riconosciuto.

Ruotare una chiave

Sviluppatore → Chiavi API → Ruota crea una sostituta con la stessa etichetta, le stesse autorizzazioni, restrizioni, lista IP e scadenza, e mostra la nuova chiave una sola volta.

• Sovrapposizione (da 0 a 168 ore, predefinito 24). La vecchia chiave continua a funzionare per questo periodo, poi restituisce 401 api_key_rotated. Impostare 0 per revocare subito la vecchia chiave.
• L'elenco contrassegna la vecchia chiave come "Ruotata: la vecchia chiave funziona fino al…" e la nuova come "Sostituisce una chiave ruotata". Una chiave già ruotata non può essere ruotata di nuovo: si ruota la sua sostituta.
• È possibile anche modificare o revocare la vecchia chiave durante la sovrapposizione, se serve interromperla prima.

Revocare una chiave

Quando una chiave è compromessa, trapelata o non più necessaria:

• Sviluppatore → Chiavi API → menu a tre puntini → Revoca.
• Effetto immediato. Qualsiasi richiesta in corso con la chiave restituisce 401 alla chiamata successiva.
• Non è reversibile: non esiste un pulsante "annulla revoca". Se ci si pente, emettere una nuova chiave.

La revoca viene registrata nel registro di audit insieme all'utente che l'ha eseguita.

Produzione e test

Ogni chiave è di uno dei due tipi:

• Test (ck_test_...): pensata per lo sviluppo e per la CI.
• Produzione (ck_live_...): pensata per l'ambiente di produzione.

L'ambiente etichetta l'utilizzo: ogni risposta riporta X-Certivant-Environment: test oppure live, e la dashboard mostra il badge accanto alla chiave, così nei propri log si può distinguere il traffico di test da quello di produzione.

Risoluzione dei problemi

401 Unauthorized

Il campo error.reason del corpo della risposta indica il motivo:

403 Forbidden

error.reason:

429 Too Many Requests

Si è soggetti al limite di frequenza. Controllare l'intestazione Retry-After (secondi) e rallentare di conseguenza. Per volumi sostenuti, chiedere un limite più alto.

"Ho perso il valore della chiave"

Le chiavi vengono mostrate una sola volta. Non esiste recupero. Revocare la vecchia chiave ed emetterne una nuova: il proprio team dovrà aggiornare il nuovo valore ovunque fosse distribuito il precedente.

Correlati

• Webhook: da abbinare all'API per un'integrazione completa.
• Elenco e dettaglio KYC: la vista dalla dashboard delle richieste create tramite API.
• Registro di audit: ogni chiamata API compare qui.