Riferimento API (OpenAPI)

Ogni endpoint che una chiave API può chiamare è descritto in un unico documento OpenAPI 3.1. È pubblico: nessun accesso, nessuna chiave, sicuro da scaricare da una CI o da un generatore di codice.

Il documento contiene solo la superficie delle chiavi API (/api/v1/...). Le route della dashboard e dell'amministrazione non ne fanno parte.

Che cosa dice il documento

• Ogni operazione ha un tag (Verifications, KYB, Documents, Forms, Deliveries, Live verification, Fraud signals, EDD, Privacy, Analytics, Audit, Reuse), un operationId stabile per i client generati, e gli schemi di richiesta e risposta.
• Ambiti. Ogni operazione elenca l'ambito di cui ha bisogno in x-required-scope e ogni ambito che la soddisfa in x-accepted-scopes — gli ambiti generali kyc:* e gli ambiti per risorsa, come verifications:read o forms:write. Un'operazione senza x-required-scope accetta qualsiasi chiave valida.
• Errori. Ogni operazione elenca le risposte di errore che può restituire (400, 401, 402, 403, 404, 409, 429, 502), e tutte usano la stessa busta di errore descritta in Errori.
• Limiti di frequenza. Le risposte di successo dichiarano le intestazioni X-RateLimit-*; vedi Limiti di frequenza.
• Webhook. La sezione webhooks elenca ogni evento che inviamo, con lo schema del suo payload e il modo di verificarne la firma. Vedi Eventi webhook e Verifica della firma.

Riferimento interattivo

Sfogli ogni endpoint, legga gli schemi e costruisca richieste direttamente qui. Usi il pannello Autenticazione per incollare una chiave API e inviare richieste reali.

Se il riquadro non si carica, apra il riferimento direttamente su /api/v1/docs.

Scarichi il documento OpenAPI

# Save the spec
curl -sS https://app.certivant.com/api/v1/openapi.json -o certivant-openapi.json

# Only download again when it changed
curl -sS -D - -o /dev/null \
  -H 'If-None-Match: "<etag from your last download>"' \
  https://app.certivant.com/api/v1/openapi.json

import { writeFile } from "node:fs/promises";

const res = await fetch("https://app.certivant.com/api/v1/openapi.json");
if (!res.ok) throw new Error(`Spec download failed: ${res.status}`);

const spec = await res.json();
console.log(spec.info.title, spec.info.version, Object.keys(spec.paths).length, "paths");

await writeFile("certivant-openapi.json", JSON.stringify(spec, null, 2));

import json
import urllib.request

with urllib.request.urlopen("https://app.certivant.com/api/v1/openapi.json") as res:
    spec = json.load(res)

print(spec["info"]["title"], spec["info"]["version"], len(spec["paths"]), "paths")

with open("certivant-openapi.json", "w") as f:
    json.dump(spec, f, indent=2)

Come usarlo

Postman, Insomnia, Bruno. Importi l'URL https://app.certivant.com/api/v1/openapi.json. Imposti una variabile d'ambiente per la Sua chiave e la usi come token bearer sulla collezione.

Generi un client. Qualsiasi generatore OpenAPI 3.1 funziona. Per esempio con la CLI di OpenAPI Generator:

npx @openapitools/openapi-generator-cli generate \
  -i https://app.certivant.com/api/v1/openapi.json \
  -g typescript-fetch \
  -o ./certivant-client

Gli ID delle operazioni come createVerification, submitVerification e getVerification diventano i nomi dei metodi. Imposti l'URL del server e un token bearer nella configurazione del client generato.

Lo chiami senza un client. Una prima richiesta richiede solo la chiave:

curl -sS https://app.certivant.com/api/v1/kyc/requests?limit=5 \
  -H "Authorization: Bearer $CERTIVANT_API_KEY"

Restare al passo con le modifiche

Il documento viene generato dall'API in esecuzione, quindi corrisponde sempre agli endpoint distribuiti. Lo riscarichi (con l'ETag) quando rigenera un client. Consideri gli oggetti di risposta come aperti: ignori i campi che non conosce, perché possono comparire nuovi campi facoltativi.