Aller au contenu

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.

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.

POST /v1/signature-templates
Idempotency-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 é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.

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: "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,
});
console.log(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.
GET /v1/signature-templates
GET /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.

Fenêtre de terminal
curl https://api.tano.africa/v1/signature-templates \
-H "Authorization: Bearer $TANO_API_KEY"
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.

© 2026 Qalebasse · Tano, plateforme de confiance numériquetano.africaDemander un accès[email protected]