Les modèles de demande
Vous faites signer le même bail chaque semaine, à des personnes différentes : un modèle garde ce qui ne change pas — le PDF, les places de chacun, les réglages —, et chaque demande n’apporte plus que les personnes.
Ce que garde un modèle
Section intitulée « Ce que garde un modèle »| Partie | Ce que c’est |
|---|---|
| Documents | De 1 à 10 PDF, vérifiés et aplatis comme ceux d’une demande. |
| Rôles | Les places à remplir : « Bailleur », « Locataire ». Chacun a un libellé, un role (signer, approver, viewer), un rang (position), ses champs et ses documents cachés. |
| Champs | Ceux de chaque rôle, placés par coordonnées, avec les mêmes types et options que dans une demande ; et ceux des ancres des documents. |
| Réglages | ordering, expires_in_days, message, reminder_days. |
Un modèle ne connaît personne : ni nom, ni adresse, ni numéro. Il n’est jamais envoyé ; il sert à créer des demandes.
Créer un modèle
Section intitulée « Créer un modèle »POST /v1/signature-templatesIdempotency-Key: 2b7e…X-Tano-Timestamp: …X-Tano-Signature: v2=…
{ "name": "Bail d'habitation", "documents": [{"filename": "bail.pdf", "content": "JVBERi0xLjcK…"}], "roles": [ { "label": "Bailleur", "role": "signer", "position": 1, "fields": [{"document": 0, "kind": "signature", "page": 3, "x": 60, "y": 80, "width": 170, "height": 50}] }, { "label": "Locataire", "role": "signer", "position": 2, "fields": [ {"document": 0, "kind": "mention", "page": 3, "x": 300, "y": 140, "width": 220, "height": 30, "mention": "Lu et approuvé"}, {"document": 0, "kind": "signature", "page": 3, "x": 300, "y": 80, "width": 170, "height": 50} ] } ], "ordering": "sequential", "expires_in_days": 15, "reminder_days": [2, 5]}| Champ | Obligatoire | Description |
|---|---|---|
name |
oui | Le nom du modèle, 200 caractères au plus. Il devient le nom des demandes qui n’en donnent pas. |
documents |
oui | De 1 à 10 PDF : filename et content (le PDF en base 64). |
roles |
oui | De 1 à 20 rôles (voir ci-dessous). |
ordering |
non | sequential (par défaut) ou parallel. |
expires_in_days |
non | De 1 à 90 jours. 30 par défaut. |
message |
non | Le message aux signataires, 2 000 caractères au plus. |
reminder_days |
non | Deux jours de relance au plus. [2, 5] par défaut, [] pour aucune. |
Chaque rôle :
| Champ | Obligatoire | Description |
|---|---|---|
label |
oui | Son nom, de 1 à 60 caractères, différent des autres sans tenir compte de la casse. |
role |
non | signer (par défaut), approver ou viewer. |
position |
non | Son rang en ordre séquentiel, à partir de 1. |
fields |
non | Ses champs, exactement comme ceux d’un signataire. |
hidden_documents |
non | Les rangs des documents qu’il ne voit pas, à partir de 0. |
Le modèle est vérifié comme une demande : documents lisibles, champs dans leur page, options de
leur type, ancres justes, documents cachés existants. Ce qui passe ici passera à la création de la
demande. Une erreur sur un champ désigne le rôle en cause dans field
(roles[1].fields), là où une demande dirait signers[1].
Réponse 201 :
{ "id": "stpl_01JA2C4E6G8J0K2M4N6P8Q0R2S", "name": "Bail d'habitation", "created_at": "2026-11-14T09:00:00+00:00", "updated_at": "2026-11-14T09:00:00+00:00", "ordering": "sequential", "expires_in_days": 15, "message": null, "reminder_days": [2, 5], "documents": [ {"id": "stdoc_…", "position": 1, "pages": 3, "sha256": "9f2c…"} ], "roles": [ { "label": "Bailleur", "role": "signer", "position": 1, "hidden_documents": [], "fields": [{"document": 0, "kind": "signature", "page": 3, "x": 60, "y": 80, "width": 170, "height": 50, "required": true}] }, {"label": "Locataire", "role": "signer", "position": 2, "hidden_documents": [], "fields": ["…"]} ]}La définition du modèle est chiffrée, comme les données d’une demande : un texte proposé ou une mention peut nommer quelqu’un.
Les ancres dans un modèle
Section intitulée « Les ancres dans un modèle »Les ancres écrites dans les PDF du modèle marchent
comme dans une demande : s1 désigne le premier rôle, s2 le deuxième. Elles sont lues à la
création du modèle, pour le vérifier : une ancre fausse le fait refuser avec
invalid_anchor.
Le modèle ne garde pas les champs qu’elles posent : ils sont relus dans les documents à chaque
demande. La lecture d’un modèle (roles[].fields) ne rend donc que les champs donnés par
coordonnées ; la demande, elle, rend tous les champs de chaque signataire, ceux des ancres
compris.
Créer une demande depuis un modèle
Section intitulée « Créer une demande depuis un modèle »La demande donne template_id et les personnes, une par rôle, dans l’ordre des rôles : la
première prend le premier rôle, la deuxième le deuxième.
POST /v1/signature-requests
{ "template_id": "stpl_01JA2C4E6G8J0K2M4N6P8Q0R2S", "reference": "BAIL-2026-119", "signers": [ {"given_name": "Aya", "family_name": "Koné", "email": "[email protected]", "auth_method": "otp_email"}, {"given_name": "Koffi", "family_name": "Yao", "phone": "+2250701021234", "auth_method": "otp_sms"} ], "activate": true}| Ce qui vient du modèle | Ce que la demande peut changer | Ce qu’elle apporte |
|---|---|---|
Les documents, les rôles (role, position), les champs, les documents cachés. |
name (par défaut, le nom du modèle), ordering, expires_in_days, message, reminder_days : seulement s’ils sont envoyés. |
Les personnes ; reference, metadata, delivery, custom_text, redirect_urls, activate, comme d’habitude. |
Chaque personne porte ce qu’un signataire porte d’habitude : given_name, family_name, email
ou phone, auth_method, locale, delivery, custom_text, redirect_urls. Mais ni fields,
ni hidden_documents : ils viennent du rôle. position et role aussi, et ceux qu’elle
donnerait sont ignorés.
La réponse est une demande comme une autre, avec template_id. Elle vit ensuite sans le modèle :
le changer ou le supprimer ne la touche pas.
// Avec le client `tano()` de l'exemple complet.const demande = await tano("POST", "/v1/signature-requests", { template_id: "stpl_01JA2C4E6G8J0K2M4N6P8Q0R2S", reference: "BAIL-2026-119", signers: [ { given_name: "Koffi", family_name: "Yao", phone: "+2250701021234", auth_method: "otp_sms" }, ], expires_in_days: 7, // l'emporte sur les 15 jours du modèle activate: true,});console.log(demande.id, demande.template_id); // sr_… stpl_…# Avec le client `tano()` de l'exemple complet.demande = tano("POST", "/v1/signature-requests", { "template_id": "stpl_01JA2C4E6G8J0K2M4N6P8Q0R2S", "reference": "BAIL-2026-119", "signers": [ {"given_name": "Aya", "family_name": "Koné", "email": "[email protected]", "auth_method": "otp_email"}, {"given_name": "Koffi", "family_name": "Yao", "phone": "+2250701021234", "auth_method": "otp_sms"}, ], "expires_in_days": 7, # l'emporte sur les 15 jours du modèle "activate": True,})print(demande["id"], demande["template_id"]) # sr_… stpl_…Le client tano(), qui signe les requêtes, est celui de
l’exemple complet.
| Refus | Pourquoi |
|---|---|
invalid_request sur signers |
Pas autant de personnes que de rôles. Le message nomme les rôles attendus. |
invalid_request sur signers[i] |
Une personne porte des fields ou des hidden_documents. |
invalid_request sur documents |
La demande apporte des documents : ils viennent du modèle. |
signature_template_not_found |
Le modèle n’existe pas, ou il est d’une autre organisation. |
Lire et lister
Section intitulée « Lire et lister »GET /v1/signature-templatesGET /v1/signature-templates/{id}GET /v1/signature-templates/{id}/documents/{document_id}La liste rend, pour chaque modèle, son nom, son nombre de documents et de rôles, et sa dernière mise à jour :
{"data": [{"id": "stpl_…", "name": "Bail d'habitation", "documents": 1, "roles": 2, "updated_at": "2026-11-14T09:00:00+00:00"}]}La lecture d’un modèle rend le même corps qu’à sa création. Le document (stdoc_…) se télécharge
en PDF : de quoi l’afficher à l’écran pour y poser des champs.
curl https://api.tano.africa/v1/signature-templates \ -H "Authorization: Bearer $TANO_API_KEY"Supprimer un modèle
Section intitulée « Supprimer un modèle »DELETE /v1/signature-templates/{id}Réponse 204. Le modèle et ses documents sont effacés, sans retour. Les demandes déjà créées
depuis lui gardent leurs documents : elles vont à leur terme.
Étapes suivantes
Section intitulée « Étapes suivantes »© 2026 Qalebasse · Tano, plateforme de confiance numériquetano.africaDemander un accès[email protected]