Mandats de facturation électronique

Le mandat est le document par lequel une entreprise autorise Scribee, en tant que Plateforme Agréée, à agir pour son compte dans la réforme de la facturation électronique : émettre ses factures, les recevoir, transmettre son e-reporting. C'est la porte de mise en service de chaque client que vous embarquez : sans mandat Actif, l'entreprise ne peut pas être inscrite dans l'annuaire national ni recevoir ses factures via Scribee. Cette page déroule le parcours entier, à rejouer pour chaque entreprise : création, signature (deux voies), documents KYC, soumission à révision, activation - puis résiliation et suppression.

Ce que Scribee fait pour vous

• Détermine le type du mandat (kind) : delegation quand votre espace de travail est un cabinet comptable ou un représentant fiscal, standard sinon. Vous ne l'envoyez jamais dans la requête.
• Attribue le numéro de mandat (mandate_number) à partir du SIREN de la fiche entreprise.
• Pour la signature électronique, génère le document de mandat réglementaire (PDF, en français) depuis la fiche entreprise et le signataire déclarés, l'envoie par email au signataire, puis attache le document signé au mandat sans action de votre part.
• À l'aboutissement de cette signature électronique, soumet le mandat à révision sans appel de votre part, dès lors qu'il remplit déjà les autres conditions de la soumission (étape 4).
• Crée dès la création du mandat les trois demandes de documents KYC d'un mandat standard : extrait Kbis, pièce d'identité, justificatif de capacité à signer (Documents KYC).
• Refuse en 422 un mandat dont un périmètre chevauche celui d'un autre mandat de la même entreprise - à la création, à la modification quand un périmètre est ajouté ou quand la fenêtre de dates s'élargit, et à la resoumission d'un mandat Rejeté (voir Les trois périmètres).
• À l'approbation d'un mandat couvrant receive_invoices, déclenche l'inscription de l'entreprise dans l'annuaire national (L'annuaire national).
• Résilie le mandat à la date planifiée, par un balayage quotidien exécuté à 00h15 UTC - soit 01h15 à Paris en heure d'hiver et 02h15 en heure d'été. Vous n'appelez rien le jour J.

Les trois périmètres

Un mandat porte 1 à 3 périmètres (scopes), chacun au plus une fois :

scope	Libellé	Ce que le mandat autorise
receive_invoices	Réception de factures	La réception de ses factures électroniques - conditionne l'inscription dans l'annuaire national
send_invoices	Émission de factures	L'émission de ses factures électroniques
e_reporting	E-reporting	L'e-reporting de ses transactions

Un même périmètre ne peut être couvert que par un seul mandat de l'entreprise à dates chevauchantes, en comptant tous ses mandats sauf les Rejetés, les Résiliés et les Supprimés. La création qui créerait un doublon répond 422. Un mandat Rejeté ne bloque donc pas le mandat de remplacement que vous créez sur le même périmètre et les mêmes dates.

Ce contrôle ne s'exécute pas à chaque enregistrement. Il s'exécute à la création, sur une modification qui ajoute un périmètre, sur une modification qui élargit la fenêtre de dates : start_date ramenée plus tôt, end_date repoussée plus tard ou effacée - l'effacer ouvre la fenêtre à l'infini - et sur POST /api/v1/mandates/{id}/submit_for_review depuis Rejeté, puisque le mandat resoumis couvre de nouveau ses périmètres. Dans les cas de modification, un PATCH qui ferait chevaucher deux mandats portant le même périmètre est refusé en 422, exactement comme à la création (les dates étant des termes signés, un tel PATCH suppose de toute façon un mandat non verrouillé - voir Le cycle de vie). Un PATCH qui ne fait que rétrécir la fenêtre - start_date repoussée plus tard, end_date ramenée plus tôt - ou qui renvoie la liste scopes inchangée n'est pas contrôlé : un rétrécissement ne peut pas créer un chevauchement que la fenêtre ne portait pas déjà, et cette exemption garde la résiliation planifiée possible sur une entreprise qui porte un chevauchement hérité.

Le cycle de vie : deux suivis indépendants

Le mandat porte deux suivis distincts, et ils avancent indépendamment : l'état du mandat (state) trace le parcours administratif, le statut de signature (signature_status) trace la signature du document. Envoyer le mandat en signature électronique ne change pas son état - il reste À compléter - et la révision ne modifie pas le statut de signature. Un seul lien automatique les relie : quand la signature électronique aboutit sur un mandat par ailleurs complet, Scribee le soumet lui-même à révision (voir Voie A).

Cette indépendance s'arrête aux termes que porte le document : la signature les verrouille. Tant que signature_status vaut pending ou signed, un PATCH qui change l'un des neuf termes signés - scopes, start_date, end_date, previous_approved_platform_name, previous_approved_platform_siren, previous_approved_platform_matricule, signer_first_name, signer_last_name, signer_role - est refusé en 422 avec code: "operation_failed", et details nomme chaque terme fautif. Le mandat ne bouge pas : le refus est total, jamais partiel.

Deux précisions utiles à l'intégration : signer_email n'est jamais verrouillé - il ne figure pas dans le document signé - et renvoyer un terme verrouillé avec sa valeur actuelle est accepté. Seule une modification effective est refusée, ce qui permet de rejouer un PATCH complet sans le découper.

Pour modifier réellement ces termes, levez d'abord le verrou : annulez la demande de signature en attente (POST /api/v1/mandates/{id}/cancel_signature) ou retirez le document signé (DELETE /api/v1/mandates/{id}/signed_document), puis modifiez, puis obtenez une nouvelle signature (voir Revenir en arrière).

L'état du mandat :

Le statut de signature :

signature_status	Libellé	Signification
not_initiated	Non initié	Aucune demande de signature ; les deux voies de l'étape 2 restent ouvertes
pending	En attente	Demande de signature électronique en cours chez le signataire ; le téléversement manuel répond 422
signed	Signé	Le document signé est attaché au mandat (has_signed_document passe à true)
refused	Refusé	Le signataire a décliné ou la demande a expiré ; relancez une signature
cancelled	Annulé	La demande de signature en attente a été annulée par POST /api/v1/mandates/{id}/cancel_signature (ou depuis l'interface Scribee), ou par un trigger_signature qui a annulé la demande en attente sans aboutir ; le mandat est de nouveau modifiable et re-signable, exactement comme not_initiated

pending et signed sont les deux statuts qui verrouillent les termes du mandat ; not_initiated, refused et cancelled le laissent modifiable. Deux endpoints lèvent le verrou : POST /api/v1/mandates/{id}/cancel_signature annule une demande En attente et porte le statut à cancelled, DELETE /api/v1/mandates/{id}/signed_document retire un document signé et ramène le statut à not_initiated - jamais à cancelled.

Étape 1 : créer le mandat

Cet appel crée le mandat à l'état À compléter dans votre workspace ; rien n'est transmis vers l'extérieur, et le mandat reste supprimable tant qu'il n'est pas Actif. L'entreprise est une fiche de votre workspace (Entreprises et établissements). Le scope OAuth write est requis.

curl -X POST https://app.scribee.tech/api/v1/companies/YOUR_COMPANY_ID/mandates \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mandate": {
      "start_date": "2026-09-01",
      "signer_first_name": "Jean",
      "signer_last_name": "Dupont",
      "signer_role": "Dirigeant",
      "signer_email": "jean.dupont@exemple.fr",
      "scopes": ["receive_invoices", "send_invoices", "e_reporting"]
    }
  }'

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

{
  "data": {
    "id": 42,
    "company_id": 7,
    "scopes": ["e_reporting", "receive_invoices", "send_invoices"],
    "kind": "standard",
    "state": "incomplete",
    "mandate_number": "123456789_01",
    "start_date": "2026-09-01",
    "end_date": null,
    "signer_email": "jean.dupont@exemple.fr",
    "has_signed_document": false,
    "kyc_required": true,
    "signature_status": "not_initiated"
  }
}

start_date (la date d'effet), signer_first_name, signer_last_name, signer_role et scopes sont obligatoires. signer_email est obligatoire à la création quand votre espace de travail est un cabinet comptable ou un représentant fiscal (le mandat créé est alors de type delegation) ; pour un mandat standard, il peut être fourni plus tard, mais la signature électronique l'exige. end_date est facultative et ne peut pas précéder start_date (une end_date égale à start_date est acceptée).

Si l'entreprise quitte une autre Plateforme Agréée pour Scribee, renseignez previous_approved_platform_name, accompagné de previous_approved_platform_siren (opérateur français, 9 chiffres) ou de previous_approved_platform_matricule (opérateur étranger sans SIREN).

Tant que le mandat est À compléter ou Rejeté, il se modifie par PATCH /api/v1/mandates/42 avec les mêmes champs ; un tableau scopes envoyé en modification remplace l'intégralité des périmètres du mandat. L'état du mandat dit s'il est modifiable ; le statut de signature dit ce qui l'est encore : dès qu'une signature est En attente ou aboutie, les neuf termes que porte le document signé sont verrouillés (voir Le cycle de vie).

Étape 2 : obtenir la signature - deux voies

Les deux voies mènent au statut Signé, condition de la soumission à révision. Chacune se défait depuis l'API, mais une seule voie avance à la fois :

• Tant qu'une demande électronique est En attente, le téléversement manuel répond 422 : annulez d'abord la demande (POST /api/v1/mandates/{id}/cancel_signature).
• Tant qu'un document signé est attaché, la voie B répond 422, et tant que signature_status vaut signed, trigger_signature répond 422 lui aussi. Retirer le document signé (DELETE /api/v1/mandates/{id}/signed_document) rouvre les deux voies.
• Un second trigger_signature pendant qu'une demande est En attente annule d'abord cette demande chez le prestataire, puis crée une nouvelle demande et envoie un nouvel email au signataire. Chaque appel ouvre une nouvelle demande : pour relancer une signature En attente, un nouvel appel suffit, sans annulation préalable.
• Si cette annulation échoue, Scribee lit l'état de la demande chez le prestataire. Déjà signée : l'appel répond 422 avec code: "operation_failed", sans nouvelle demande, et la signature est enregistrée à l'arrivée de l'événement de signature du prestataire, comme en voie A. Déjà terminée (annulée, expirée ou déclinée) : la nouvelle demande la remplace. Dans les autres cas - demande toujours en cours, ou état illisible -, l'appel répond 422 avec code: "validation_failed" : aucune nouvelle demande n'est créée, et la première reste enregistrée, En attente.
• Si la demande de signature du mandat change au même moment - par exemple un autre trigger_signature ou un cancel_signature en cours -, l'appel répond 422 avec code: "operation_failed" : relisez le mandat, puis réessayez. Si les termes du mandat sont modifiés pendant que trigger_signature prépare la demande - possible sur un mandat sans demande En attente, et sur un second appel dès que la demande En attente est annulée -, l'appel répond 422 avec code: "operation_failed" et Scribee demande au prestataire de retirer la nouvelle demande : relisez le mandat, puis relancez trigger_signature. Si la nouvelle demande ne peut pas être créée une fois la première annulée, l'appel échoue et signature_status vaut cancelled : trigger_signature peut être rappelé.
• trigger_signature sur un mandat À compléter déjà Signé est refusé en 422 avec code: "operation_failed" : une signature aboutie n'est jamais remplacée en silence, ni son document écrasé. Retirez le document signé, puis relancez.

Voie A : la signature électronique

Cet appel crée une demande de signature électronique et envoie un email réel au signataire, contenant le lien de signature avec vérification par code à usage unique reçu par email. Il n'existe pas d'environnement de test : l'adresse fournie reçoit cet email en production. La demande expire au bout de 14 jours ; son échéance exacte se lit dans signature_provider_expires_at. Le mandat doit être À compléter ; son état ne change pas, seul le statut de signature passe à En attente.

curl -X POST https://app.scribee.tech/api/v1/mandates/42/trigger_signature \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"signer_email": "jean.dupont@exemple.fr", "locale": "fr"}'

signer_email est facultatif : omis, l'appel utilise l'adresse déjà portée par le mandat. locale (fr ou en, fr par défaut) fixe la langue de l'interface de signature ; le document de mandat lui-même est en français, document réglementaire.

Les déclenchements sont limités par mandat, par espace de travail, par application OAuth et par adresse du signataire ; au-delà, l'appel répond 429 sans rien envoyer (voir Erreurs et cas limites).

Suivez ensuite la demande - lecture sans effet de bord, le scope read suffit :

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

{
  "data": {
    "id": 42,
    "state": "incomplete",
    "signature_status": "pending",
    "signature_provider_status": "ongoing",
    "signature_provider_expires_at": "2026-09-15T09:30:00+02:00"
  }
}

Les horodatages sont rendus dans le fuseau Europe/Paris, avec le décalage explicite (+02:00 en heure d'été, +01:00 en hiver) - jamais un Z.

signature_provider_status vaut ongoing, done, declined ou expired, et null tant qu'aucune demande n'a été créée. À la signature, Scribee télécharge le document signé et l'attache au mandat sans action de votre part : signature_status passe à signed et has_signed_document à true. Si le mandat remplit alors déjà les autres conditions de l'étape 4 - les trois documents KYC standard fournis quand kyc_required vaut true, aucun document demandé à l'état requested ou rejected - Scribee le soumet à révision dans les instants qui suivent : state passe à pending_review sans appel de submit_for_review de votre part. Entre la signature et cette soumission, le mandat peut brièvement se lire avec signature_status à signed et state encore à incomplete. Sinon le mandat reste À compléter avec signature_status à signed, et vous le soumettez vous-même à l'étape 4 une fois la pièce manquante fournie. Téléverser les documents KYC avant de déclencher la signature permet donc au mandat de partir en révision dès sa signature. Si le signataire décline ou si la demande expire, signature_status passe à refused - relancez alors trigger_signature.

Voie B : téléverser un document signé

Cet appel attache un PDF signé au mandat et fait passer le statut de signature à Signé ; rien n'est transmis vers l'extérieur. Il sert au circuit où le document est signé hors de Scribee - signature manuscrite ou votre propre outil. Le mandat doit être À compléter ou Rejeté, le fichier est un PDF de 50 Mo maximum, et aucun document signé ne doit déjà être attaché. L'API expose le retrait d'un document attaché, mais jamais son téléchargement : tant qu'un document est en place, la voie B est close pour ce mandat, et le seul signal exposé est le booléen has_signed_document. Le PDF que vous avez téléversé n'est jamais récupérable par l'API, y compris après son retrait - conservez-en une copie de votre côté. Pour le remplacer, retirez-le puis téléversez le nouveau ; pour en obtenir une copie, contactez Scribee.

curl -X POST https://app.scribee.tech/api/v1/mandates/42/upload_document \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@mandat_signe.pdf"

Réponse 200 : le mandat avec signature_status à signed et has_signed_document à true. state ne change pas : contrairement à la voie A, le téléversement ne soumet jamais le mandat à révision - soumettez-le à l'étape 4.

Revenir en arrière : annuler une demande ou retirer un document signé

Deux endpoints défont l'étape 2 et lèvent le verrou sur les termes du mandat. Ils répondent tous deux 200 avec le mandat mis à jour.

Annuler une demande En attente. Le scope write est requis. La demande de signature en cours est annulée chez le prestataire, signature_status passe à cancelled, et signature_provider_status et signature_provider_expires_at reviennent à null. Scribee n'enregistre plus aucune signature de cette demande. Le mandat redevient modifiable et les deux voies rouvrent. Un mandat dont signature_status ne vaut pas pending répond 422. Si la demande de signature du mandat change pendant l'appel - un trigger_signature ou un autre cancel_signature en cours -, l'appel répond 422 avec code: "operation_failed" : relisez le mandat, puis réessayez.

curl -X POST https://app.scribee.tech/api/v1/mandates/42/cancel_signature \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Retirer un document signé. Le scope write ou destroy suffit. Le PDF est détaché, signature_status revient à not_initiated et has_signed_document à false. Le mandat doit être À compléter ou Rejeté et porter un document signé ; sinon, 422. Le mandat n'est alors plus soumissible tant qu'une nouvelle signature n'a pas abouti, par l'une ou l'autre voie.

curl -X DELETE https://app.scribee.tech/api/v1/mandates/42/signed_document \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Étape 3 : fournir les documents KYC

Le champ kyc_required du mandat vous dit si cette étape s'applique. Il vaut false quand votre espace de travail est un cabinet comptable ou un représentant fiscal - les mêmes espaces pour lesquels le mandat créé est de type delegation - et true partout ailleurs. Quand il vaut true, Scribee a déjà créé les trois demandes à la création du mandat : il vous reste à téléverser les fichiers.

Scribee peut aussi demander un document en plus pendant la révision (kind : additional) ; il apparaît dans la même liste et bloque la soumission tant qu'il n'est pas fourni, y compris quand kyc_required vaut false.

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

Réponse abrégée :

{
  "data": [
    { "id": 103, "kind": "signing_capacity_proof", "status": "requested", "has_file": false },
    { "id": 102, "kind": "identity_paper", "status": "requested", "has_file": false },
    { "id": 101, "kind": "kbis_extract", "status": "requested", "has_file": false }
  ]
}

La liste est triée par created_at décroissant par défaut, donc les trois demandes standard ressortent dans l'ordre inverse de leur création.

Le téléversement des fichiers, les statuts de chaque document et leurs règles sont détaillés dans Documents KYC.

Étape 4 : soumettre le mandat à révision

Cet appel fait passer le mandat en En attente de révision ; la révision est effectuée par l'équipe Scribee, rien n'est transmis vers l'extérieur. Cinq conditions, vérifiées dans cet ordre : le mandat est À compléter ou Rejeté ; signature_status vaut signed (l'une ou l'autre voie de l'étape 2) ; les trois documents KYC standard sont fournis, quand kyc_required vaut true ; aucun document demandé ne reste à l'état requested ou rejected ; pour une resoumission depuis Rejeté, aucun mandat À compléter, En attente de révision ou Actif de l'entreprise ne couvre l'un de ses périmètres à dates chevauchantes. Sinon l'appel répond 422 et le mandat reste dans son état.

Après une signature par la voie A, relisez d'abord state : si le mandat remplissait déjà ces conditions à la signature, Scribee le soumet lui-même dans les instants qui suivent et il passe En attente de révision. Un mandat encore À compléter juste après la signature peut donc encore être soumis automatiquement : relisez state avant de le soumettre vous-même. submit_for_review sur un mandat déjà soumis répond 422, puisqu'il n'est plus À compléter (voir Erreurs et cas limites) : passez directement à l'étape 5. Après la voie B, l'appel reste toujours nécessaire.

curl -X POST https://app.scribee.tech/api/v1/mandates/42/submit_for_review \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Réponse abrégée :

{
  "data": {
    "id": 42,
    "state": "pending_review",
    "signature_status": "signed"
  }
}

Étape 5 : suivre la révision jusqu'à l'activation

La révision aboutit sans appel de votre part ; relisez le mandat pour en observer l'issue - le scope read suffit.

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

Trois issues possibles :

• state passe à active : le mandat est en vigueur dès lors que sa période contractuelle couvre le jour courant - l'accord formel porte la date à compter de laquelle Scribee peut agir au nom de l'entreprise. Dans l'API, c'est cette combinaison - l'état active et une période en cours - qui débloque les écritures sur l'annuaire national pour cette entreprise (L'annuaire national) ; aucun autre endpoint n'a de prérequis de mandat actif. Les deux bornes ne jouent pas de la même façon : start_date compte le jour même, donc un mandat qui commence aujourd'hui ouvre déjà ces écritures alors qu'un mandat qui commence demain ne les ouvre pas encore ; end_date, elle, ne compte pas le jour même, donc un mandat dont l'end_date tombe aujourd'hui ne les autorise déjà plus : le dernier jour de la période ne compte pas.
• state passe à rejected : le mandat redevient modifiable. Le motif du rejet est consultable dans l'interface Scribee. Le rejet ne touche que state : le statut de signature et le document signé sont conservés, donc le verrou l'est aussi - tant que le document signé est attaché, un PATCH sur l'un des neuf termes signés répond 422. Si seuls les documents KYC sont en cause, resoumettez directement, avec la signature d'origine. Si ce sont les termes, la boucle de correction est : DELETE /api/v1/mandates/{id}/signed_document, puis PATCH /api/v1/mandates/{id}, puis une nouvelle signature, puis POST /api/v1/mandates/{id}/submit_for_review. Depuis Rejeté, cette nouvelle signature passe par la voie B : trigger_signature ne s'exécute que depuis À compléter. Un mandat Rejeté ne bloque pas un mandat de remplacement sur le même périmètre ; mais une fois ce remplacement créé, resoumettre le mandat Rejeté répond 422 (voir Les trois périmètres).
• state revient à incomplete : Scribee demande des modifications ou un document en plus - relisez la liste KYC de l'étape 3, puis soumettez de nouveau.

Tous les mandats d'une entreprise se listent via GET /api/v1/companies/YOUR_COMPANY_ID/mandates (tri par state, mandate_number, start_date ou created_at, défaut created_at décroissant ; associations company et kyc_documents via include).

Résilier un mandat actif

Cet appel planifie la résiliation : le mandat reste Actif avec end_date renseignée, et le balayage quotidien de 00h15 UTC (01h15 ou 02h15 à Paris selon la saison) le passe à Résilié une fois la date atteinte. Rien n'est transmis vers l'extérieur par cet appel. end_date doit être au plus tôt demain (J+1) ; jusqu'à la date effective, la résiliation s'annule en rappelant le même endpoint sans end_date (ou avec null).

La date planifiée n'est pas la seule route vers Résilié : Scribee peut aussi résilier immédiatement un mandat Actif depuis son interface interne, sans end_date. Un mandat que vous relisez peut donc être passé à Résilié alors que son end_date vaut null.

curl -X POST https://app.scribee.tech/api/v1/mandates/42/terminate \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"end_date": "2026-12-31"}'

Réponse abrégée :

{
  "data": {
    "id": 42,
    "state": "active",
    "end_date": "2026-12-31",
    "termination_date": null
  }
}

Une fois résilié, le mandat porte termination_date et l'état Résilié est définitif : pour réautoriser Scribee, créez un nouveau mandat.

Supprimer un mandat

DELETE retire un mandat qui ne sera jamais activé - une erreur de saisie, un parcours abandonné. Autorisé depuis À compléter, En attente de révision et Rejeté ; un mandat Actif ou Résilié répond 422. Le scope write est requis.

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

Réponse 204, sans corps. La suppression est logique : le mandat passe à l'état Supprimé, reste lisible dans les listes et à l'unité, et n'est plus ni modifiable ni soumissible. Un second DELETE sur ce mandat répond 422 avec le même message que sur un mandat Actif ou Résilié - un message qui ne nomme pourtant que ces deux états.

Si la demande de signature est En attente (signature_status à pending), Scribee la retire en outre chez le prestataire, en arrière-plan et au mieux, sans garantie de résultat : une fois retirée, le lien déjà envoyé au signataire ne mène plus à rien, tandis que le mandat supprimé conserve signature_status à pending. Si le signataire avait déjà signé avant que ce retrait n'aboutisse, Scribee attache tout de même le document signé au mandat supprimé, à titre de preuve : has_signed_document passe à true, sans autre effet sur le mandat - state reste à deleted, signature_status à pending, le mandat n'est pas soumis à révision, et ce document ne peut pas être retiré (422).

Ce qui se passe ensuite

• À l'approbation d'un mandat couvrant receive_invoices, Scribee déclenche l'inscription de l'entreprise dans l'annuaire national de la réforme, tenu par le PPF (Portail Public de Facturation) - sans appel de votre part : L'annuaire national.
• Un mandat Actif dont la période contractuelle couvre le jour courant est le prérequis des écritures d'annuaire de l'entreprise : sans lui, elles répondent 403.
• Une fois le mandat Actif, déroulez l'intégration métier : Émettre une facture de vente, Recevoir les factures fournisseurs, Déclarer des transactions.

Erreurs et cas limites

Les échecs de validation répondent 422 avec error: "unprocessable_entity", code: "validation_failed" et la cause dans details.base. Plusieurs refus de cette page portent code: "operation_failed" et un format différent (voir plus bas). Basez vos traitements sur le statut HTTP et sur code, jamais sur le texte du message (Conventions de l'API).

{
  "error": "unprocessable_entity",
  "code": "validation_failed",
  "message": "La validation a échoué",
  "details": {
    "base": ["Le mandat doit être en état incomplet pour initier la signature"]
  }
}

Les causes par message, au même format. La table n'est pas exhaustive : toute autre validation du modèle ressort dans details.base, dans le même format.

details.base	Cause	Ce que vous faites
Périmètres doit comporter au moins 1 périmètre.	scopes vide ou absent à la création	fournissez 1 à 3 périmètres de la table
Périmètres n'est pas valide	une valeur de scopes ne figure pas dans la table des périmètres	n'envoyez que receive_invoices, send_invoices ou e_reporting ; le message ne nomme pas la valeur fautive
Périmètres Un mandat actif couvre déjà l'un des périmètres sélectionnés.	un autre mandat de l'entreprise, ni Rejeté, ni Résilié, ni Supprimé, couvre déjà ce périmètre à dates chevauchantes - à la création, à la modification, ou à la resoumission d'un mandat Rejeté	réutilisez le mandat existant, ou résiliez-le d'abord ; à la resoumission, poursuivez avec le mandat qui couvre déjà le périmètre
Le mandat doit être en état incomplet ou rejeté	PATCH, upload_document ou submit_for_review sur un mandat non modifiable, y compris un mandat déjà soumis automatiquement à l'aboutissement de sa signature électronique	relisez state ; seuls À compléter et Rejeté sont modifiables, et un mandat déjà pending_review n'a plus à être soumis
Le mandat doit être en état incomplet pour initier la signature	trigger_signature hors de l'état À compléter	seul un mandat À compléter part en signature électronique ; depuis Rejeté, passez par la voie B
L'adresse e-mail du signataire est requise pour initier la signature	aucun signer_email, ni dans l'appel ni sur le mandat	fournissez signer_email
Annulez la demande de signature en cours avant de télécharger un document manuel.	upload_document pendant une demande électronique En attente	annulez la demande (POST /api/v1/mandates/{id}/cancel_signature), ou attendez son issue
Un document signé est déjà associé. Retirez-le avant d'en téléverser un nouveau.	upload_document sur un mandat qui porte déjà un document signé	retirez le document en place (DELETE /api/v1/mandates/{id}/signed_document) avant de téléverser le nouveau
La demande de signature ne peut être annulée que tant qu'elle est en attente	cancel_signature sur un mandat dont signature_status ne vaut pas pending	relisez signature_status ; une signature aboutie se défait par le retrait du document signé
Erreur du fournisseur de signature : ...	trigger_signature ou cancel_signature : le fournisseur de signature électronique n'a pas pu traiter la demande (indisponible momentanément, ou refus de sa part) ; le texte après les deux-points varie	rappelez plus tard le même endpoint ; après un trigger_signature sur un mandat sans demande En attente, signature_status n'est pas passé à pending et le mandat reste À compléter ; après un trigger_signature sur une demande En attente, relisez signature_status : pending si l'annulation de la première demande a échoué, qui reste alors enregistrée, cancelled si la nouvelle demande n'a pas pu être créée ; après cancel_signature, signature_status vaut toujours pending et le mandat est inchangé
Le document signé ne peut être supprimé que sur un mandat modifiable	DELETE .../signed_document hors des états À compléter et Rejeté	relisez state ; le document d'un mandat Actif ne se retire pas
Aucun document signé n'est associé à ce mandat	DELETE .../signed_document sur un mandat sans document attaché	rien à retirer ; has_signed_document valait déjà false
Un fichier est requis	upload_document sans champ file	envoyez le PDF en multipart/form-data, champ file
Document de mandat signé doit être un fichier PDF	fichier d'un autre type	convertissez en PDF
Document de mandat signé doit être inférieur à 50 Mo	fichier trop lourd	compressez le PDF
La signature électronique du mandat est requise avant soumission.	submit_for_review alors que signature_status ne vaut pas signed	terminez l'étape 2, quelle que soit la voie
Tous les documents KYC requis doivent être téléchargés avant la soumission	un des trois documents KYC standard manque, sur un mandat dont kyc_required vaut true	terminez l'étape 3
Tous les documents demandés doivent être téléchargés avant la soumission pour révision	un document demandé par Scribee reste à fournir ou a été rejeté	relisez la liste KYC et fournissez-le
Le mandat doit être actif	terminate sur un mandat non Actif	seuls les mandats Actifs se résilient
La date de résiliation doit être au plus tôt demain	end_date à aujourd'hui ou dans le passé	fournissez une date à J+1 minimum
Date de résiliation invalide	end_date dans un format non ISO 8601	envoyez AAAA-MM-JJ
Aucune résiliation planifiée à annuler	terminate sans end_date alors qu'aucune résiliation n'est planifiée	rien à rejouer
Les mandats actifs et résiliés ne peuvent pas être supprimés	DELETE sur un mandat Actif, Résilié, ou déjà Supprimé	résiliez un mandat Actif (endpoint terminate) au lieu de le supprimer

422 : le verrou de signature

Les deux refus du verrou de signature ne passent pas par details.base. Ils portent code: "operation_failed", et leur message est la cause elle-même. Le PATCH d'un terme verrouillé nomme en plus chaque terme fautif dans details, un terme par clé :

{
  "error": "unprocessable_entity",
  "code": "operation_failed",
  "message": "Les termes du mandat sont verrouillés tant que sa signature est en attente ou aboutie. Annulez la demande de signature en attente ou retirez le document signé, puis modifiez le mandat.",
  "details": {
    "signer_first_name": ["ne peut pas être modifié tant que la signature du mandat est en attente ou aboutie"]
  }
}

trigger_signature sur un mandat déjà Signé porte le même code, sans details :

{
  "error": "unprocessable_entity",
  "code": "operation_failed",
  "message": "Le mandat est déjà signé. Retirez le document signé avant de déclencher une nouvelle signature."
}

Les refus de trigger_signature et de cancel_signature décrits à l'étape 2 - demande En attente déjà signée chez le prestataire, demande de signature changée entre-temps, termes du mandat modifiés pendant la préparation de la demande - portent eux aussi ce code, sans details, avec la cause pour message.

429 : limite de déclenchement de signature

trigger_signature est compté contre plusieurs limites : par mandat ; par espace de travail, à la minute et à l'heure ; par application OAuth, à la minute et à l'heure, tous espaces de travail confondus ; et par adresse e-mail du signataire au sein d'un espace de travail, la casse et un suffixe +tag étant ignorés. Les valeurs sont publiées dans la référence API. Les signatures déclenchées depuis l'interface Scribee entrent dans les mêmes limites par mandat, par espace de travail et par adresse du signataire. Un refus 422 pour un mandat hors de l'état À compléter, déjà Signé ou sans signer_email n'est pas compté. Au-delà d'une limite, l'appel répond 429 avec un en-tête Retry-After en secondes :

{
  "error": "too_many_requests",
  "code": "rate_limited",
  "message": "Trop de requêtes. Veuillez réessayer plus tard."
}

Rien n'a été envoyé : aucun document n'a été généré, le prestataire de signature n'a pas été sollicité, aucun email n'est parti et le mandat est inchangé. Attendez Retry-After secondes, puis réessayez. Cette valeur est un majorant : c'est la durée entière de la plus longue des fenêtres dépassées, pas le temps restant - chaque fenêtre s'ouvre au premier appel qu'elle compte et peut donc se refermer plus tôt.

403 : scope insuffisant

Les lectures de cette page exigent read. Un token sans le scope requis - read pour une lecture, write pour une écriture, destroy ou write pour les deux DELETE de cette page (suppression du mandat et retrait du document signé) - répond :

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

404 Not Found

L'entreprise ou le mandat n'existe pas, ou appartient à un workspace hors du périmètre de votre application (Votre premier appel) :

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

Sur ces routes, une requête émise depuis une adresse IP hors de la liste d'autorisation du workspace reçoit la même réponse 404, et non un 403 : l'espace de travail devient invisible plutôt qu'interdit.

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

La liste des mandats et celle des documents KYC sont paginées et répondent 400 au-delà de la dernière page, comme partout ailleurs : Conventions de l'API. Une exception : quand la collection est vide, il n'y a pas de dépassement. Une entreprise sans mandat, ou un mandat sans document KYC, répond 200 avec data: [] quel que soit le page demandé.

Pages liées

• Documents KYC - fournir les justificatifs qui conditionnent la soumission
• L'annuaire national - l'inscription déclenchée par l'approbation du mandat
• Entreprises et établissements - créer la fiche entreprise porteuse du mandat
• Référence API : créer un mandat
• Référence API : envoyer en signature électronique
• Référence API : annuler la signature en attente
• Référence API : retirer le document signé
• Référence API : soumettre un mandat à révision