Documents

Les documents sont rattachés à une demande, et non directement à un demandeur. Chaque envoi rapproche la demande parente de l'état « prête à être soumise » : dès que pendingDocTypes est vide, vous pouvez soumettre la demande au traitement.

Envoyer un document

POST /api/v1/kyc/requests/:requestId/documents    Portée : kyc:write

Envoi en multipart. Transmettez documentType (et side le cas échéant) en paramètres de requête, et le fichier dans un champ de formulaire file.

Paramètres de requête

Corps du formulaire

Types de documents

Exemple

# Upload the front of a driver's license
curl -X POST "https://app.certivant.com/api/v1/kyc/requests/req_01J.../documents?documentType=GOVERNMENT_ID&side=front" \
  -H "Authorization: Bearer ck_live_..." \
  -F "file=@/path/to/license-front.jpg"

Réponse (201)

{
  "id": "doc_01J...",
  "documentType": "GOVERNMENT_ID",
  "side": "front",
  "status": "pending",
  "fileSize": 412938,
  "mimeType": "image/jpeg",
  "requestStatus": "PENDING_UPLOAD",
  "pendingDocTypes": ["GOVERNMENT_ID", "SELFIE"],
  "message": "Document uploaded. Front of GOVERNMENT_ID received; back of GOVERNMENT_ID still required."
}

La réponse indique toujours ce qui manque encore, via pendingDocTypes. Lorsque ce tableau est vide, votre prochain appel doit être POST /requests/:id/submit.

Valeurs de statut des documents

• pending : envoyé, pas encore traité (cela ne se produit qu'avant la soumission de la demande).
• verified : a passé tous les contrôles d'authenticité après la soumission de la demande.
• failed : a échoué à un contrôle d'authenticité. Consultez les enregistrements de contrôle associés sur GET /requests/:id pour connaître la raison précise.
• corrupted : le fichier n'a pas pu être décodé. Envoyez-le à nouveau.

Erreurs

• 400 BAD_REQUEST :
  • Le fichier dépasse 10 Mo.
  • Type MIME non pris en charge.
  • side absent pour GOVERNMENT_ID.
  • documentType non autorisé par les paramètres KYC de l'organisation.
• 404 NOT_FOUND : la demande parente n'existe pas dans cette organisation.
• 409 CONFLICT : la demande n'est pas à l'état PENDING_UPLOAD. Vous ne pouvez pas ajouter de documents à une demande déjà soumise.

Obtenir une URL de téléchargement

GET /api/v1/kyc/requests/:requestId/documents/:docId/url    Portée : kyc:read

Les documents sont conservés dans un stockage d'objets privé. Pour en afficher ou en télécharger un, récupérez une URL signée à courte durée de vie.

Réponse

{
  "url": "https://storage.certivant.com/kyc/org_.../req_.../doc_....jpg?X-Amz-Signature=...",
  "expiresIn": 900
}

expiresIn est exprimé en secondes : l'URL est valide pendant 15 minutes. Générez-en une nouvelle chaque fois que vous devez afficher un document ; ne les mettez pas en cache.

L'url renvoyée est une URL de stockage pré-signée (S3 / Azure Blob / GCS). Elle s'ouvre directement dans un onglet du navigateur et s'affiche sans en-tête Authorization :

• Images (image/jpeg, image/png, image/webp) → <img src="{url}" />
• PDF (application/pdf) → <iframe src="{url}" /> ou <object data="{url}" type="application/pdf" />

Vérifiez le mimeType de chaque document (depuis GET /requests/:id) pour choisir l'élément à afficher.

Télécharger les octets bruts

GET /api/v1/kyc/requests/:requestId/documents/:docId/download    Portée : kyc:read

Diffuse directement les octets du fichier du document, avec le Content-Type enregistré (image/jpeg, image/png, image/webp ou application/pdf) et Content-Disposition: inline. Pas d'URL signée, pas de redirection.

curl -L "https://app.certivant.com/api/v1/kyc/requests/req_01J.../documents/doc_01J.../download" \
  -H "Authorization: Bearer ck_live_..." \
  -o government_id_front.jpg

Privilégiez cette méthode plutôt que la route par URL signée lorsque vous affichez des documents dans votre propre tableau de bord :

• Elle fonctionne avec tous les backends de stockage, y compris le disque local, dont l'URL signée /uploads/… n'est accessible que depuis l'hôte de Certivant et renverrait une erreur 404 depuis une autre origine.
• Faites-la transiter par votre backend et servez-la en même origine (<img src="/your-proxy/doc"> pour les images, <iframe> pour les PDF). La clé Authorization: Bearer reste côté serveur et n'atteint jamais le navigateur.
• Aucune URL de stockage n'est jamais exposée : il n'y a donc rien à divulguer ni à laisser expirer.

Remplacer des documents

Vous ne pouvez pas modifier un document sur place. Si le demandeur a envoyé une photo floue et que vous voulez une nouvelle prise :

1. La demande doit être à l'état PENDING_UPLOAD (ou vous devez d'abord soumettre à nouveau une demande rejetée pour effacer les documents précédents).
2. Envoyez un nouveau document avec le même documentType et le même side. Le précédent est remplacé : seule la dernière version est utilisée pour le traitement.

Cette règle existe pour l'intégrité de l'audit : un historique immuable de chaque envoi est conservé dans le journal d'audit, même lorsque le document actif change.

Lister les documents d'une demande

Il n'existe pas de point de terminaison distinct pour lister les documents. La liste complète figure dans la réponse de GET /api/v1/kyc/requests/:id :

{
  "id": "req_...",
  "documents": [
    { "id": "doc_a", "documentType": "GOVERNMENT_ID", "side": "front", "status": "verified", ... },
    { "id": "doc_b", "documentType": "GOVERNMENT_ID", "side": "back", "status": "verified", ... },
    { "id": "doc_c", "documentType": "SELFIE", "status": "verified", ... }
  ]
}

Parcourez documents et appelez /download (pour faire transiter les octets) ou /url (pour un lien signé) sur chaque document que vous voulez afficher.

Voir aussi

• Demandes KYC : le point de terminaison parent auquel vos documents sont rattachés.
• Sessions hébergées : laissez Certivant recueillir directement les documents auprès du demandeur.
• Schémas : liste complète des valeurs de documentType, status et autres valeurs associées.