Aller au contenu

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é.

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-requests
Idempotency-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é",
"email": "[email protected]",
"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.

Sans activate, la demande reste en brouillon (draft) : rien n’est envoyé. Envoyez-la ensuite :

POST /v1/signature-requests/{id}/activate

Un brouillon se supprime (DELETE /v1/signature-requests/{id}, réponse 204) ; une demande envoyée, non : annulez-la.

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.

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-118

La liste accepte status, reference et limit (de 1 à 100, 50 par défaut).

Une fois signature_request.completed reçu :

GET /v1/signature-requests/{id}/documents/{document_id}/download
GET /v1/signature-requests/{id}/audit-trail

Les 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é.

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).

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]