Documentation API

Trois appels pour intégrer la vérification, plus les webhooks pour savoir comment elle s'est passée.

Authentification

Chaque requête porte la clé dans l'en-tête Authorization. Vous créez les clés depuis le tableau de bord, section Clés API, et vous ne les voyez en clair qu'une seule fois.

Authorization: Bearer kyc_live_xxxxxxxxxxxxxxxxxxxxx
Test et live sont séparés par la clé
Une clé kyc_test_… ne peut pas créer de données live. Ce n'est pas un paramètre que vous pouvez oublier : c'est la clé elle-même qui décide.
Ce que coûte le sandbox
Les 20 premières vérifications de test du mois sont gratuites. Au-delà, elles sont débitées de votre solde comme les vérifications live, module par module : une vérification de test exécute les mêmes contrôles qu'une vraie, et elle nous coûte autant.

Le flux

  1. 1. Ouvrez un dossier (POST /verifications). Cela ne coûte rien et n'expire pas.
  2. 2. Générez le lien (POST /verifications/{id}/attempts) et envoyez-le à la personne comme vous le souhaitez.
  3. 3. La personne ouvre le lien : consentement, document, liveness. Rien à installer.
  4. 4. Vous recevez verification.submitted : la personne a terminé. Si vous avez activé l'approbation automatique et que le dossier est au vert sur tous les contrôles, l'approbation suit immédiatement ; sinon, une personne tranche — votre équipe depuis le tableau de bord, ou l'un de nos opérateurs avec l'offre Institutionnelle.
  5. 5. Vous recevez verification.approved, .declined ou .retry_required.
Il y a toujours une personne dans la boucle
Les contrôles automatiques mesurent ; seuls, ils n'approuvent pas. Chaque dossier qui n'est pas approuvé automatiquement est tranché par une personne — votre équipe, depuis le tableau de bord, avec l'offre Standard ; l'un de nos opérateurs avec l'offre Institutionnelle — c'est pourquoi le résultat n'arrive pas dans le même appel. La seule exception, c'est vous qui la décidez : l'approbation automatique, désactivée tant que vous ne l'activez pas, approuve sans examen uniquement les dossiers au vert sur tous les contrôles — avec la puce, ou aussi à partir de la photo si vous avez accepté cette extension — et ne refuse jamais.

Endpoints

POST/api/v1/verifications

Ouvre un dossier. Ne génère aucun lien et ne coûte rien.

REQUÊTE

{ "external_ref": "cliente-4821", "declared_name": "Mario Rossi", "return_url": "https://app.esempio.it/firma/abc" }

RÉPONSE

{ "id": "…", "status": "created", "livemode": true, "created_at": "…" }
POST/api/v1/verifications/{id}/attempts

Génère le lien. À usage unique, avec expiration. Une nouvelle tentative invalide la précédente.

REQUÊTE

{ "instruction": "Fotografa il documento disteso, senza riflessi." }

RÉPONSE

{ "id": "…", "url": "https://…/v/<token>", "expires_at": "…", "livemode": true }
GET/api/v1/verifications/{id}

Statut, résultat et qui tranche le dossier, avec les données lues sur le document quand il y en a.

RÉPONSE

{ "id": "…", "status": "approved", "record": { "surname": "…", "verifiedFields": […] } }

Webhooks

Vous configurez l'endpoint depuis les Paramètres. En live, il doit être en https.

Le corps

Il ne contient jamais de données personnelles. Seulement des identifiants : les données, vous les lisez vous-même avec GET /verifications/{id}, en vous authentifiant.

{
  "id": "285a4274-a751-4a24-9479-12100bf9d313",
  "type": "verification.approved",
  "created": 1787037080,
  "livemode": true,
  "data": {
    "verification_id": "01a013b5-dc12-7ab2-a8c5-f00f0bab35bc",
    "status": "approved",
    "external_ref": "cliente-4821"
  }
}

Vérifier la signature

L'en-tête X-KYCJET-Signature vaut t=<timestamp>,v1=<hmac>. Le HMAC est un SHA-256 sur "<timestamp>.<corps brut>" avec votre secret de signature. Comparez en temps constant et rejetez les horodatages trop anciens.

import { createHmac, timingSafeEqual } from 'node:crypto'

function verifica(rawBody, header, secret) {
  const [t, v1] = header.split(',').map(p => p.split('=')[1])
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false
  const atteso = createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex')
  return timingSafeEqual(Buffer.from(atteso), Buffer.from(v1))
}

Livraison et nouvelles tentatives

Répondez 2xx dès que vous avez pris l'événement en charge. Toute autre réponse, ou un silence de plus de 10 secondes, déclenche une nouvelle tentative : backoff exponentiel de 30 secondes jusqu'à 6 heures, 12 tentatives sur une quinzaine d'heures environ, puis la livraison est abandonnée.

La livraison est au moins une fois : le même événement peut vous parvenir deux fois. Utilisez id comme clé d'idempotence — il reste identique même quand nous remettons une livraison en file à la main.

Erreurs

Chaque erreur a la même forme : { "code": …, "message": …, "details"?: … }. Faites le switch sur code, jamais sur le message. Le message arrive en italien, en anglais ou en français selon Accept-Language ; le code, lui, ne change pas.

401 UNAUTHORIZED
Clé absente, erronée ou révoquée. Les trois réponses sont identiques à dessein.
402 INSUFFICIENT_CREDITS
Solde insuffisant (le code a gardé son ancien nom par compatibilité) : si votre solde ne couvre pas le coût maximal d'une vérification, le POST qui génère le lien ne le génère pas. Cela arrive avant d'impliquer quelqu'un, pas après.
404 VERIFICATION_NOT_FOUND
Le dossier n'existe pas, ou n'appartient pas à votre organisation. Là aussi, même réponse.
409 VERIFICATION_NOT_RETRYABLE
Vous avez demandé une nouvelle tentative sur un dossier déjà tranché. Ce code EST la politique de nouvelle tentative.
422 DOCUMENT_REJECTED
La photo est inutilisable. Aucun débit, le lien reste valide : la personne reprend la photo.
503 CHECKS_UNAVAILABLE
Nos contrôles ne répondent pas. C'est de notre faute : les photos sont bonnes, le lien reste valide, aucun débit. La personne réessaie dans quelques minutes.