Un contrat clair.
Une lecture à intégrer.

Ce qui est disponible

La sandbox fournit une réponse prédéfinie à partir d’un spécimen fictif. Elle permet d’explorer le contrat JSON et ne réalise ni OCR réel ni vérification d’identité.

La lecture répond 503 tant que le moteur privé et la clé d’intégration ne sont pas configurés. L’ouverture au public, l’émission de clés clients et le paiement ne sont pas actifs.

Votre première requête

Envoyez une opération read ou verify, avec l’exemple identity-card. Ce sont les seules valeurs prises en charge par la sandbox.

# En local ; utilisez votre URL Vercel pour la preview
BASE_URL='http://localhost:4020'
curl -X POST "$BASE_URL/api/sandbox" \
  -H 'Content-Type: application/json' \
  -d '{"operation":"read","sample":"identity-card"}'

La réponse

{
  "mode": "sandbox",
  "request_id": "sandbox_…",
  "operation": "read",
  "document": {
    "type": "identity_card",
    "country": "FR",
    "sides": ["front", "back"]
  },
  "fields": {
    "last_name": "MARTIN",
    "first_names": ["Camille"],
    "birth_date": "1992-04-18",
    "document_number": "SPECIMEN-000001",
    "expiry_date": "2032-04-18"
  },
  "checks": {
    "readability": "passed",
    "document_consistency": "passed",
    "identity_assurance": "not_performed"
  },
  "billing": { "charged": false }
}

Les valeurs passed sont simulées pour illustrer le contrat. identity_assurance: "not_performed" indique qu’aucune vérification du porteur n’a été réalisée. Le montant facturé est nul.

Une opération non prise en charge ou un exemple inconnu est rejeté. Les détails du contrat et des réponses d’erreur figurent dans le fichier OpenAPI.

Lire une pièce

POST /v1/read reçoit le type de document document_type, son format et un fichier front, avec un fichier back facultatif lorsque le profil possède un verso. La réponse contient directement les résultats de lecture, par face.

# Serveur d’intégration activé ; clé secrète côté serveur
BASE_URL='http://localhost:4020'
curl -X POST "$BASE_URL/v1/read" \
  -H "Authorization: Bearer $KYCKYDE_API_KEY" \
  -F 'document_type=identity_card' \
  -F 'format=current' \
  -F 'front=@document-recto.jpg' \
  -F 'back=@document-verso.jpg'

Les types admis sont identity_card, passport, driving_licence, health_card et residence_permit. Le format current est choisi par défaut ; legacy existe pour la CNI, le permis et le titre de séjour. Le catalogue GET /v1/document-profiles décrit les profils et champs attendus, sans garantir une précision de lecture pour tous les scans.

Envoyez des fichiers JPEG, PNG, WebP ou PDF, pour un total de 4 Mio maximum, enveloppe multipart comprise. Les signatures réelles des fichiers sont contrôlées. Les profils, instructions, modèles et URL de fichiers arbitraires ne sont pas acceptés.

Recto et verso correspondent aux faces déclarées par votre appel, sans détection indépendante de leur côté. Un PDF est lu comme un fichier entier : les champs peuvent provenir de ses différentes pages.

{
  "mode": "integration",
  "request_id": "read_…",
  "document_type": "identity_card",
  "format": "current",
  "faces": [{
    "side": "front",
    "profile_id": "cni_fr_recto",
    "source_sha256": "…",
    "fields": [{
      "id": "nom",
      "status": "found",
      "value": "MARTIN",
      "source_text": "MARTIN"
    }],
    "timing": { "reading_ms": 1200, "preparation_ms": 400 },
    "reader": { "id": "…", "revision": "…" }
  }],
  "checks": { "identity_assurance": "not_performed" },
  "billing": { "charged": false }
}

Les identifiants de champs du moteur sont conservés : nom, date_naissance, numero_document… Chaque champ indique found, absent ou unreadable. La transcription imprimée figure dans source_text. Les dates lues gardent le format du profil, notamment JJ.MM.AAAA ; elles ne sont pas converties systématiquement en ISO.

Les appels d’intégration ne sont pas facturés. Il n’existe pas encore de tâches asynchrones, de webhooks ni de clé d’idempotence. L’appel est limité à 170 secondes au total. Les erreurs HTTP sont détaillées dans le contrat OpenAPI ; un résultat absent ou illisible reste explicite.

Une lecture restitue le contenu visible. Elle n’atteste ni l’authenticité de la pièce ni l’identité de la personne qui la présente.

Comparer le titulaire à sa pièce

Le moteur Kyckyde compare le portrait de la pièce à une vidéo, analyse la présence et l’ordre des mouvements. Il provient du module importé dans ce dépôt. Kyckyde gère les sessions, les médias privés, leur purge et la revue humaine. Les modèles, leurs droits et une évaluation du pipeline doivent être configurés avant les essais.

# Serveur marchand ; références opaques et portrait issu de la pièce
curl -X POST 'https://api.kyckyde.com/v1/identity/session' \
  -H "Authorization: Bearer $KYCKYDE_API_KEY" \
  -F 'metadata=@session.json;type=application/json' \
  -F 'portrait=@portrait-extrait.png;type=image/png'

# session.json
{
  "actorReference": "actor_opaque_001",
  "subjectReference": "user_opaque_001",
  "sourceReference": "document_opaque_001",
  "documentHash": "<SHA-256 de la pièce, 64 caractères hexadécimaux>",
  "sourceSnapshotHash": "<SHA-256 des sources, 64 caractères hexadécimaux>",
  "minor": false,
  "mode": "self",
  "authorization": { "self": true, "representative": false },
  "consent": true,
  "consentVersion": "identity-verification-v1"
}

Le marchand vérifie les droits du titulaire et extrait le portrait de sa pièce. Il affiche ensuite le lien captureUrlfourni par Kyckyde, directement ou en QR code. La capacité temporaire se trouve dans le fragment du lien ; aucune clé API ne passe dans le navigateur. La capture hébergée demande le consentement, guide les mouvements et permet de revoir la vidéo.

GET /v1/identity/session retourne le résultat avec sessionId et actorReference. Avec subjectReference et actorReference, il retourne la dernière session ou null. PATCH invalide une source remplacée et DELETE annule la session. Le serveur marchand revérifie ses autorisations à chaque consultation.

L’avis humain passe par une console Kyckyde privée, ouverte avec un accès à usage unique et une clé opérateur distincte. Les notes privées et la consultation des médias sont auditées. Les médias sont chiffrés et supprimés à la révocation ou après 24 heures. Un avis humain reste séparé des contrôles automatiques.

Transport de capture personnalisé

Les routes de compatibilité suivantes permettent une capture intégrée au site marchand. Le parcours hébergé utilise les sessions ci-dessus.

# Serveur d’intégration activé ; portrait extrait par le marchand
BASE_URL='http://localhost:4020'
curl -X POST "$BASE_URL/v1/verify/challenge" \
  -H "Authorization: Bearer $KYCKYDE_VERIFY_API_KEY" \
  -F 'portrait=@portrait-extrait.png' \
  -F "document_hash=$DOCUMENT_SHA256" \
  -F 'subject_reference=user_opaque_001'

Le serveur crée un défi de dix minutes et renvoie les instructions publiques challenge ainsi qu’un challenge_token à conserver dans votre backend. Il lie le compte, la référence utilisateur, le portrait et l’empreinte de la pièce. Le marchand est responsable du lien entre le portrait extrait et la pièce déclarée.

# Le jeton reste sur votre serveur, avec le même portrait
curl -X POST "$BASE_URL/v1/verify" \
  -H "Authorization: Bearer $KYCKYDE_VERIFY_API_KEY" \
  -F "challenge_token=$SERVER_CHALLENGE_TOKEN" \
  -F 'portrait=@portrait-extrait.png' \
  -F 'video=@capture.webm'

Portrait PNG de 300 Kio maximum, de 32 à 1024 pixels par côté. Vidéo WebM ou MP4 de 3 Mio maximum, sans audio, de 3 à 15 secondes. Les décodeurs contrôlent le contenu et les pistes. Le registre persistant de défis bloque les substitutions ; une répétition exactement identique retrouve son reçu.

Une capture à intégrer

Le composant React demande l’accord du titulaire, ouvre la caméra avant, affiche les mouvements et permet de revoir la capture avant l’envoi. Votre backend garde la clé, le jeton et le portrait. Voir le composant.

import { IdentityCapture } from '@kyckyde/react';
import '@kyckyde/react/styles.css';

// Instructions publiques seulement, jamais le jeton ni la clé API
<IdentityCapture
  challenge={publicChallenge}
  onSubmit={async ({ file, signal, onProgress }) => {
    // Votre transport authentifié vers votre propre backend :
    // il conserve le portrait et le jeton, puis appelle Kyckyde.
    return uploadToYourBackend(file, signal, onProgress);
  }}
/>

Sans configuration, les routes répondent 503 avant lecture du corps. Les appels d’intégration ne sont pas facturés. Le parcours hébergé utilise un stockage privé durable des sessions, du QR code et de l’historique de revue. Une capture ne prouve pas à elle seule qu’une vidéo est récente ; un échec ne démontre pas une fraude.

Votre suivi marchand

L’espace client présente les lectures, vérifications, références utilisateur, crédits et opérations par période. Il utilise un compte fictif. La recharge simule le parcours et ne déclenche aucun paiement.

# Données fictives publiques ; aucune clé ni paiement
curl 'http://localhost:4020/api/merchant-demo/summary?period=30d'

Choisissez 7d, 30d ou 90d. La réponse MerchantSummary distingue les appels API des opérations, les trois services et les montants en centimes entiers. Une référence utilisateur est un identifiant fourni par le marchand ; son décompte ne certifie aucune identité.

Dans votre application React

Le package privé @kyckyde/react est construit dans ce dépôt et livré en archive par la CI. Il accepte les données et actions de votre application, sans dépendance à Next.js.

import { MerchantDashboard } from '@kyckyde/react';
import '@kyckyde/react/styles.css';

// Données obtenues par votre application, via votre serveur
<MerchantDashboard
  summary={summary}
  period={period}
  onPeriodChange={loadPeriod}
  onRefresh={refresh}
  onAddCredit={openCheckout}
  isLoading={loading}
  error={error}
/>

Les comptes commerciaux et paiements sont en préparation : GET /v1/account/summary et POST /v1/billing/topups répondent 503. Votre backend conservera la clé API et transmettra au composant uniquement le résumé du compte connecté. Le portefeuille sera crédité après confirmation du paiement côté serveur.

Clés & authentification

Les essais de lecture utilisent une clé d’intégration secrète transmise dans l’en-tête Authorization: Bearer …. Elle est distincte du secret du moteur privé. Une clé absente ou invalide est refusée avant de lire le document. L’émission de clés clients est en préparation.

• Appelez l’API depuis votre serveur.
• Conservez la clé dans une variable d’environnement secrète.
• Ne placez jamais la clé dans votre code client, une application publique ou un dépôt Git.
• La gestion, la révocation et le suivi d’utilisation des clés seront disponibles avant la commercialisation.

La sandbox publique n’a pas besoin de clé et ne facture aucune requête.

Traitement des données

La sandbox utilise uniquement le spécimen intégré. La lecture d’intégration transmet les fichiers au moteur privé de Kyckyde. Les réponses ne contiennent ni URL de document, ni nom de fichier, ni diagnostic interne. Les engagements de conservation et de suppression devront être définis avant l’ouverture commerciale.

• Limiter les informations collectées à celles nécessaires à l’opération demandée.
• Encadrer l’accès aux documents et aux résultats.
• Documenter les fichiers temporaires et leurs règles de suppression.
• Définir les durées de conservation et les options disponibles avant l’ouverture.
• Publier les engagements contractuels et les conditions du traitement avant de recevoir des données réelles.

Ces points décrivent les objectifs de conception. Ils ne constituent pas une certification ni une garantie juridique de conformité.