Faire signer un document
Ce guide fait signer un bail par deux personnes, l’une après l’autre : le bailleur par courriel,
le locataire par SMS. Il suppose une clé qui porte la portée signature et des requêtes
signées. Faites-le d’abord avec une clé de
bac à sable : rien ne part, rien n’est facturé.
1. Créer et envoyer la demande
Section intitulée « 1. Créer et envoyer la demande »Un seul appel suffit : les documents voyagent en base 64 dans le corps, et "activate": true
envoie la demande dans la foulée.
POST /v1/signature-requestsIdempotency-Key: 6f1c…X-Tano-Timestamp: …X-Tano-Signature: v2=…
{ "name": "Bail — appartement Cocody", "reference": "BAIL-2026-118", "documents": [{"filename": "bail.pdf", "content": "JVBERi0xLjcK…"}], "signers": [ { "given_name": "Aya", "family_name": "Koné", "auth_method": "otp_email", "position": 1, "fields": [{"document": 0, "kind": "signature", "page": 1, "x": 60, "y": 80, "width": 180, "height": 50}] }, { "given_name": "Koffi", "family_name": "Yao", "phone": "+2250701021234", "auth_method": "otp_sms", "position": 2, "fields": [{"document": 0, "kind": "signature", "page": 1, "x": 300, "y": 80, "width": 180, "height": 50}] } ], "activate": true}| Champ | Obligatoire | Description |
|---|---|---|
name |
oui | Le nom de la demande, montré au signataire. 200 caractères au plus. Facultatif depuis un modèle. |
documents |
oui | De 1 à 10 PDF : filename et content (le PDF en base 64). Absent depuis un modèle. |
signers |
oui | De 1 à 20 signataires (voir ci-dessous). |
template_id |
non | Le modèle d’où partir (stpl_…) : il apporte les documents, les rôles et les champs. |
reference |
non | Votre référence, 120 caractères au plus. Reprise dans les webhooks. |
level |
non | simple, seul niveau disponible. |
ordering |
non | sequential (par défaut) ou parallel. |
message |
non | Un message au signataire, 2 000 caractères au plus. |
locale |
non | fr (par défaut) ou en. |
expires_in_days |
non | L’échéance, de 1 à 90 jours après l’activation. 30 par défaut. |
reminder_days |
non | Les jours de relance après l’invitation, deux au plus. [2, 5] par défaut, [] pour aucune. Voir Relances. |
activate |
non | true pour envoyer la demande tout de suite. false par défaut : elle reste en brouillon. |
delivery |
non | email (par défaut) : Tano invite et relance. none : vous remettez le lien vous-même. |
custom_text |
non | Les textes de l’invitation et de la relance. Voir Le parcours du signataire. |
redirect_urls |
non | Où renvoyer le signataire après sa signature, son refus ou une erreur. |
metadata |
non | Vos paires clé → texte, jointes à chaque webhook. Voir Gérer une demande. |
Chaque signataire :
| Champ | Obligatoire | Description |
|---|---|---|
given_name, family_name |
oui, sauf pour un groupe | Son nom. |
auth_method |
oui, sauf pour un groupe | otp_email ou otp_sms. |
email ou phone |
selon la méthode | L’adresse pour otp_email, le numéro au format international pour otp_sms. |
group_name |
pour un groupe | Le nom du groupe, de 1 à 60 caractères. |
members |
pour un groupe | Ses membres, deux au moins, chacun avec given_name, family_name, email ou phone, et auth_method. Le premier qui signe tient la place. |
role |
non | signer (par défaut), approver ou viewer. |
position |
non | Son rang en ordre séquentiel, à partir de 1. |
locale |
non | fr (par défaut) ou en. |
time_zone |
non | Son fuseau horaire. Africa/Abidjan par défaut. |
delivery, custom_text, redirect_urls |
non | Les siens, qui l’emportent sur ceux de la demande. |
fields |
non | Ses champs placés par coordonnées : document, kind, page, x, y, width, height, required, et les options du type. Inutile pour les champs posés par des ancres dans le PDF. |
hidden_documents |
non | Les rangs des documents qu’il ne voit pas, à partir de 0. Voir Cacher un document. |
Pour un groupe, la place ne porte ni given_name, ni family_name, ni email, ni phone, ni
auth_method : chaque membre porte les siens. Tout le reste (role, position, fields…) reste
sur la place. Voir Les groupes de signataires.
Les rôles et les méthodes sont détaillés dans Demandes et signataires, les champs dans Placer les champs.
Réponse 201 :
{ "id": "sr_01J9ZK7B2M4Q8R6T0V3W5X7Y9Z", "name": "Bail — appartement Cocody", "status": "ongoing", "level": "simple", "ordering": "sequential", "reference": "BAIL-2026-118", "environment": "sandbox", "created_at": "2026-11-13T09:00:00+00:00", "activated_at": "2026-11-13T09:00:00+00:00", "expires_at": "2026-12-13T09:00:00+00:00", "documents": [ {"id": "sd_…", "position": 1, "pages": 3, "sha256": "9f2c…"} ], "signers": [ {"id": "ss_…", "position": 1, "role": "signer", "status": "notified", "auth_method": "otp_email", "contact": "a••••@exemple.ci", "name": null, "notified_at": "…", "signed_at": null}, {"id": "ss_…", "position": 2, "role": "signer", "status": "pending", "auth_method": "otp_sms", "contact": "+225 07 •• •• 12 34", "name": null, "notified_at": null, "signed_at": null} ]}Le bailleur est invité (notified) ; le locataire attend son tour (pending).
Chaque signataire porte aussi ses champs (signers[].fields), avec leur identifiant, leur position
et leurs options — ceux posés par des ancres compris. Ils sont omis ci-dessus pour la lisibilité.
Une demande incomplète ne part pas : un signataire sans champ de signature, ou sans la coordonnée
de sa méthode, est refusé avec
signature_request_not_ready, et le message liste tout ce
qui manque, d’un coup.
En deux temps
Section intitulée « En deux temps »Sans activate, la demande reste en brouillon (draft) : rien n’est envoyé. Envoyez-la ensuite :
POST /v1/signature-requests/{id}/activateUn brouillon se supprime (DELETE /v1/signature-requests/{id}, réponse 204) ; une demande
envoyée, non : annulez-la.
2. Donner le lien au signataire
Section intitulée « 2. Donner le lien au signataire »Tano invite chaque signataire par courriel ou par SMS, selon sa méthode. Pour lui donner le lien vous-même — dans votre application, ou par votre propre canal :
POST /v1/signature-requests/{id}/signers/{signer_id}/link{"url": "https://verify.tano.africa/signer#…"}Le lien mène à la page de signature, où la personne lit le document, saisit le code reçu et signe.
Chaque appel rend un nouveau lien et invalide le précédent ; le lien n’est rendu qu’une fois,
ne le conservez pas. Un signataire qui n’est pas encore invité n’a pas de lien
(signer_not_invited), ni une demande qui n’est plus en cours
(signature_request_not_editable).
Le lien ne suffit pas à signer : la personne doit aussi saisir le code à usage unique envoyé par courriel ou par SMS.
3. Suivre la demande
Section intitulée « 3. Suivre la demande »Déclarez une adresse de webhook pour les événements de signature :
{"url": "https://votre-serveur.example/tano", "events": ["signer.signed", "signer.declined", "signature_request.completed", "signature_request.declined", "signature_request.expired"]}Chaque livraison désigne la demande dans object et porte votre reference :
{ "type": "signature_request.completed", "occurred_at": "2026-11-14T16:42:00+00:00", "object": {"type": "signature_request", "id": "sr_01J9ZK7B2M4Q8R6T0V3W5X7Y9Z"}, "data": {"reference": "BAIL-2026-118"}}Les événements d’un signataire ajoutent data.signer_id. Aucun ne porte de nom, d’adresse ni de
numéro. Liste complète : Événements.
Vous pouvez aussi lire l’état à tout moment :
GET /v1/signature-requests/{id}GET /v1/signature-requests?status=ongoing&reference=BAIL-2026-118La liste accepte status, reference et limit (de 1 à 100, 50 par défaut).
4. Télécharger le document signé et la preuve
Section intitulée « 4. Télécharger le document signé et la preuve »Une fois signature_request.completed reçu :
GET /v1/signature-requests/{id}/documents/{document_id}/downloadGET /v1/signature-requests/{id}/audit-trailLes deux rendent un PDF. Les en-têtes de la réponse disent ce que vous recevez :
| En-tête | Valeur |
|---|---|
X-Tano-Document-Sha256 |
L’empreinte SHA-256 du fichier rendu. |
X-Tano-Document-Signed |
true pour le document signé, false avant la complétion. Document seulement. |
X-Tano-Sandbox |
true si la demande est de bac à sable : le fichier est un spécimen. |
Avant la complétion, le téléchargement d’un document rend le document présenté aux
signataires, tel qu’aplati, sans signature. Le fichier de preuve, lui, n’existe qu’à la
complétion : avant, signature_request_not_completed.
Conservez les deux fichiers : le document signé, et le fichier de preuve qui dit qui a signé, quand, et comment il a été authentifié.
Annuler une demande
Section intitulée « Annuler une demande »POST /v1/signature-requests/{id}/cancel
{"reason": "Clause à corriger"}Le motif est obligatoire (de 3 à 500 caractères). Les liens de signature cessent aussitôt de
valoir, et signature_request.cancelled part. Seule une demande en cours s’annule
(signature_request_not_editable sinon).
Erreurs fréquentes
Section intitulée « Erreurs fréquentes »| Code | Cause |
|---|---|
signature_request_not_ready |
Il manque un document, un signataire, un champ de signature ou une coordonnée. |
invalid_field |
Un champ sort de sa page. |
document_not_flattenable |
Le PDF est illisible ou chiffré. |
document_too_large |
Plus de 20 Mo ou plus de 200 pages. |
invalid_base64 |
Le contenu d’un document n’est pas du base 64. |
signature_level_unavailable |
Un autre niveau que simple. |
signature_request_not_found |
Identifiant inconnu, ou demande d’un autre environnement. |
© 2026 Qalebasse · Tano, plateforme de confiance numériquetano.africaDemander un accès[email protected]