Documents KYC

Un mandat part en révision accompagné de ses pièces justificatives : l'extrait Kbis de l'entreprise mandante, la pièce d'identité du signataire et le justificatif de sa capacité à signer. Ces pièces sont les documents KYC (Know Your Customer) du mandat (Mandats de facturation électronique) : quand elles sont exigées et qu'il en manque, la soumission pour révision répond 422. L'exigence dépend du workspace - le champ kyc_required du mandat en donne la valeur, et il vaut false pour les workspaces de cabinet comptable et de représentant fiscal, dont les mandats partent en révision sans aucun document KYC. Un mandat actif conditionne les écritures sur l'annuaire national (Annuaire national). Cette page couvre le référentiel des documents, le téléversement des fichiers PDF et la réponse aux demandes de pièces complémentaires.

Ce que Scribee fait pour vous

• Crée les trois documents standard en statut requested dès la création du mandat : vous ne déclarez rien, vous téléversez un fichier sur chacun.
• Contrôle chaque fichier au téléversement - PDF uniquement, moins de 50 Mo - et refuse en 422 immédiat plutôt que de laisser la révision échouer sur une pièce illisible.
• Garantit un document par type standard et par mandat : une seconde déclaration du même type est refusée.
• Matérialise chaque demande de pièce complémentaire de la révision comme un document dans la même liste, en statut requested avec sa description : votre intégration suit une seule règle - téléverser un fichier sur tout document requested.

Types de documents

kind	Libellé	Origine
kbis_extract	Extrait Kbis	Créé par Scribee à la création du mandat
identity_paper	Pièce d'identité	Créé par Scribee à la création du mandat
signing_capacity_proof	Justificatif de capacité à signer	Créé par Scribee à la création du mandat
additional	Document complémentaire	Créé par Scribee quand la révision demande une pièce, ou par vous (étape 3) - description obligatoire

Cet enum est distinct de celui des pièces jointes de facture (Pièces jointes) : kbis_extract n'est pas kbis, identity_paper n'est pas identity_document. Ne fusionnez jamais les deux référentiels dans votre intégration.

Les trois types standard ne concernent pas tous les mandats : chaque mandat porte le champ booléen kyc_required, qui vaut false pour les espaces de travail de type cabinet comptable ou représentant fiscal. Sur ces mandats, aucun document standard n'est créé ni exigé ; seule s'applique la règle des documents demandés (aucun document laissé en requested).

Statuts

status	Libellé	Qui le pose
requested	Demandé	Scribee - le document attend son fichier
uploaded	Téléchargé	Vous, en téléversant le fichier (étapes 2 et 3)

Un document est créé en requested et passe en uploaded au téléversement. Le téléversement se rejoue : un nouvel appel remplace le fichier et laisse le document en uploaded.

Étape 1 : lister les documents attendus

Cet appel est une lecture : il ne crée rien et ne transmet rien vers l'extérieur - le scope read suffit. À la création d'un mandat dont kyc_required vaut true, les trois documents standard existent déjà en statut requested.

curl https://app.scribee.tech/api/v1/mandates/YOUR_MANDATE_ID/kyc_documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Réponse abrégée aux champs utiles ici :

{
  "data": [
    { "id": 512, "kind": "kbis_extract", "status": "requested", "description": null, "has_file": false },
    { "id": 513, "kind": "identity_paper", "status": "requested", "description": null, "has_file": false },
    { "id": 514, "kind": "signing_capacity_proof", "status": "requested", "description": null, "has_file": false }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total_pages": 1,
    "total_count": 3
  }
}

Chaque document porte aussi mandate_id, created_at et updated_at. La liste est paginée (page, per_page) et se trie par sort_by (kind, status ou created_at - par défaut created_at) et sort_order (asc ou desc - par défaut desc). include=mandate ajoute à chaque document le mandat porteur (id, mandate_number, state). Un document se lit aussi à l'unité, sans passer par le mandat : GET /api/v1/kyc_documents/{id}.

Étape 2 : téléverser le fichier d'un document demandé

Cet appel attache le fichier au document et le passe en statut uploaded. Rien ne part vers l'extérieur : le fichier est conservé par Scribee pour la révision du mandat. Le fichier est un PDF (application/pdf) de moins de 50 Mo, envoyé en multipart/form-data dans le champ file ; le scope write est requis.

Renvoyer un fichier sur un document qui en porte déjà un est sans risque. Si le nouveau fichier est refusé - format autre que PDF, taille au-delà de 50 Mo - l'appel répond 422 et le document reste exactement dans son état antérieur : le fichier déjà accepté et le statut sont conservés. Seul un fichier accepté remplace le précédent.

curl -X POST https://app.scribee.tech/api/v1/kyc_documents/512/upload \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@extrait-kbis.pdf;type=application/pdf"

Réponse abrégée :

{
  "data": {
    "id": 512,
    "kind": "kbis_extract",
    "status": "uploaded",
    "has_file": true
  }
}

Répétez l'appel sur les documents 513 et 514 avec les fichiers correspondants.

Étape 3 : ajouter un document de votre côté

Cet appel crée un document et attache son fichier en un seul envoi multipart/form-data ; le document naît directement en statut uploaded, et rien ne part vers l'extérieur. Il sert à fournir une pièce que la révision n'a pas demandée - un additional avec sa description obligatoire - ou à recréer un document standard supprimé (un seul par type et par mandat). kind et file sont obligatoires ; un token read write est requis.

curl -X POST https://app.scribee.tech/api/v1/mandates/YOUR_MANDATE_ID/kyc_documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "kyc_document[kind]=additional" \
  -F "kyc_document[description]=Attestation de pouvoir du signataire" \
  -F "kyc_document[file]=@attestation-pouvoir.pdf;type=application/pdf"

Réponse 201, abrégée :

{
  "data": {
    "id": 515,
    "kind": "additional",
    "status": "uploaded",
    "description": "Attestation de pouvoir du signataire",
    "has_file": true
  }
}

Étape 4 : supprimer un document en attente

Cet appel supprime définitivement le document. Il ne vise que les documents en statut requested : une fois un fichier téléversé, le document ne se supprime plus - son fichier se remplace (étape 2). Un token read write est requis. Supprimer un document standard ne lève pas l'exigence : quand kyc_required vaut true, la soumission demande toujours les trois types - recréez-le via l'étape 3.

curl -X DELETE https://app.scribee.tech/api/v1/kyc_documents/512 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Réponse 204, sans corps.

Répondre à une demande de pièces complémentaires

Quand la révision a besoin d'une pièce de plus, le mandat repasse en incomplete et de nouveaux documents additional apparaissent dans la liste, en statut requested, chacun avec une description qui précise la pièce attendue. Votre travail ne change pas : relistez les documents du mandat (étape 1), téléversez un fichier sur chaque document requested (étape 2), puis soumettez de nouveau le mandat pour révision.

Ce qui se passe ensuite

• La complétude KYC conditionne la soumission du mandat pour révision : quand kyc_required vaut true, chacun des trois types standard doit être uploaded, et dans tous les cas aucun document ne doit rester en requested - sinon la soumission répond 422. Cette condition est indépendante de la signature du mandat : les deux se vérifient séparément avant la soumission (Mandats de facturation électronique).
• Une fois le mandat approuvé, les documents restent lisibles (GET) avec leur statut.

Erreurs et cas limites

Les échecs de validation répondent 422 avec error: "unprocessable_entity", le message "La validation a échoué" et la cause dans details.base. Basez vos traitements sur le statut HTTP, jamais sur le texte du message (Conventions de l'API).

422 : suppression refusée

Le DELETE ne vise que les documents requested :

{
  "error": "unprocessable_entity",
  "code": "validation_failed",
  "message": "La validation a échoué",
  "details": {
    "base": ["Seuls les documents demandés peuvent être supprimés"]
  }
}

422 : fichier ou attributs invalides

Au même format, dans details.base :

Message	Cause	Ce que vous faites
Un fichier est requis	file absent de la création ou du téléversement	joignez le fichier en multipart/form-data
File doit être un fichier PDF	un autre type MIME que application/pdf	convertissez la pièce en PDF
File doit être inférieur à 50 Mo	fichier trop lourd	compressez le PDF sous 50 Mo
Description est requise pour les documents complémentaires	kind à additional sans description	ajoutez la description de la pièce
Kind a déjà été pris	second document standard du même type sur le mandat	téléversez sur le document existant (étape 2)
Kind n'est pas inclus(e) dans la liste	kind hors des quatre valeurs du tableau des types	corrigez la valeur

403 : scope insuffisant

Les lectures de cette page exigent read. La création et le téléversement exigent write ; la suppression accepte destroy ou write. Un token qui ne porte pas le scope exigé par l'appel répond :

{
  "error": "forbidden",
  "message": "Vous n'êtes pas autorisé à effectuer cette action"
}

404 Not Found

Le mandat ou le document n'existe pas, appartient à un workspace hors du périmètre de votre application, ou appartient à un workspace dont l'allowlist IPv4 refuse l'adresse de votre requête - sur ces endpoints, une adresse refusée produit ce 404, et non le 403 décrit dans les Conventions de l'API :

{
  "error": "not_found",
  "message": "La ressource demandée est introuvable"
}

400 : objet kyc_document inexploitable

À la création (étape 3), la lecture des paramètres ne retient que kind et description dans l'objet kyc_document. Un envoi qui ne porte ni l'un ni l'autre - par exemple un multipart/form-data réduit au seul champ kyc_document[file], ou dépourvu d'objet kyc_document - n'atteint jamais la validation : la réponse est un 400 dans l'enveloppe d'erreur habituelle, avec error à bad_request et le message "Le corps de la requête est manquant ou mal formé" :

{
  "error": "bad_request",
  "message": "Le corps de la requête est manquant ou mal formé"
}

Envoyez toujours kind.

400 Bad Request : page au-delà de la dernière

La liste de l'étape 1 est paginée et répond 400 au-delà de la dernière page, comme partout ailleurs : Conventions de l'API.

Pages liées

• Mandats de facturation électronique - créer, signer et soumettre le mandat que ces documents accompagnent
• Pièces jointes - l'autre référentiel de documents, aux types distincts
• Référence API : lister les documents KYC d'un mandat
• Référence API : créer un document KYC
• Référence API : téléverser le fichier d'un document KYC