Placer les champs
Un champ est une zone d’une page, affectée à un signataire : c’est là qu’il signe, paraphe,
date, écrit ou coche. Chaque champ appartient à un signataire (il est déclaré dans ses
fields) et à un document de la demande (document). À la complétion, chaque champ rempli
s’inscrit sur la page, à sa place.
Deux façons de placer un champ
Section intitulée « Deux façons de placer un champ »- Par ancre, dans le PDF : vous écrivez
{{s1|signature}}là où le champ doit aller, et Tano le pose à la création. Rien à mesurer, et le champ suit le texte si le document change. C’est la façon recommandée quand vous produisez vos documents. - Par coordonnées, dans l’API :
page,x,y,width,heighten points. Utile pour un document que vous ne produisez pas.
Les deux se combinent : les champs d’un signataire sont les siens, plus ceux de ses ancres.
Les ancres
Section intitulée « Les ancres »Écrivez l’ancre dans le texte du PDF, en blanc pour qu’elle ne se voie pas, sur sa propre ligne ou dans sa propre couleur :
{{s1|signature}}{{s1|signature|170|50|reason=Bon pour accord}}{{s2|text|160|20|label=Ville|max_length=40|optional}}{{s2|date|80|20|date_format=dd MMMM yyyy}}{{s2|mention|220|30|mention=Lu et approuvé le %date%}}{{s1|radio|14|14|group=duree|value=12 mois|label=12 mois}}{{s1|radio|14|14|group=duree|value=24 mois|label=24 mois}}{{s1|signer_name|160|20|name_format=family}}{{s1|read_only_text|200|20|text=Loyer : 350 000 FCFA}}Une ancre se lit de gauche à droite, morceaux séparés par | :
| Morceau | Obligatoire | Ce qu’il dit |
|---|---|---|
s1, s2… |
oui | Le signataire, par son rang dans la liste signers de la demande (s1 est le premier). |
| le type | oui | Un des types ci-dessous. signature_date, name, email et read_only sont acceptés comme alias. |
| largeur, hauteur | non | En points. À défaut, la taille par défaut du type. |
nom=valeur |
non | Une option du type, avec les mêmes noms que dans l’API. |
optional |
non | Le champ peut rester vide. |
Le coin haut gauche du champ se pose au début de l’ancre, au haut de ses lettres ; un champ qui déborderait est ramené dans la page. Sur le document final, le champ couvre ce qui était dessous : une ancre oubliée en noir ne se voit pas non plus.
Une ancre fausse fait refuser la demande avec invalid_anchor, et
field désigne le document : un signataire qui n’existe pas (s3 pour deux signataires), un
destinataire en copie, un type inconnu, une option d’un autre type. Rien n’est ignoré en silence.
Un texte entre accolades qui ne commence pas par s suivi d’un rang ({{montant}}) est laissé
tranquille.
La réponse de la demande rend les champs de chaque signataire, ceux des ancres compris
(signers[].fields) : vous y voyez où chaque ancre a posé son champ.
Les types de champ
Section intitulée « Les types de champ »kind |
Ce que fait le signataire | Ce qui s’inscrit sur le document | Taille par défaut |
|---|---|---|---|
signature |
Rien de plus : son geste suffit. | Détaillé : « Signé électroniquement par nom, le date à heure UTC ». Minimal : le nom. Le motif en dessous, s’il y en a un. | 170 × 50 |
initials |
Rien de plus. | Ses initiales (Aya Koné → AK). |
60 × 30 |
date |
Rien de plus. | La date de sa signature, au format choisi. | 80 × 20 |
signer_name |
Rien de plus. | Son nom, prénom ou nom de famille. | 160 × 20 |
signer_email |
Rien de plus. | Son adresse. Refusé pour un signataire sans adresse. | 200 × 20 |
read_only_text |
Il le lit. | Le texte fixé par vous. | 200 × 20 |
text |
Il saisit un texte, ou garde la valeur proposée. | Le texte. | 160 × 20 |
mention |
Il recopie une phrase, à l’identique. | La phrase recopiée. | 220 × 30 |
checkbox |
Il coche la case. | X si la case est cochée. |
14 × 14 |
radio |
Il choisit une option du groupe. | X sur l’option choisie. |
14 × 14 |
Tout signataire de rôle signer a au moins un champ signature. Un approbateur
(approver) n’en a pas besoin ; un destinataire en copie (viewer) n’a aucun champ.
Les options
Section intitulée « Les options »Chaque type n’accepte que ses options : une option donnée à un autre type est refusée avec
invalid_field, plutôt qu’ignorée.
| Option | Types | Valeurs |
|---|---|---|
label |
text, checkbox, radio |
Le libellé montré au signataire, 100 caractères au plus. |
max_length |
text |
De 1 à 500 ; 200 par défaut. |
default_value |
text |
La valeur proposée, que le signataire peut changer ; gardée s’il n’y touche pas. |
mention |
mention |
La phrase à recopier, 200 caractères au plus ; %date% y devient la date du jour. |
date_format |
date |
dd/MM/yyyy (par défaut), dd-MM-yyyy, dd.MM.yyyy, yyyy-MM-dd, MM/dd/yyyy, dd MMMM yyyy (« 14 novembre 2026 »). |
layout |
signature |
detailed (par défaut) ou minimal. |
reason |
signature |
Un motif inscrit sous la signature, 150 caractères au plus. |
group, value |
radio |
Le groupe (lettres, chiffres, -, _) et la valeur de l’option. Deux options au moins par groupe, de valeurs distinctes. |
name_format |
signer_name |
full (par défaut), given ou family. |
text |
read_only_text |
Le texte inscrit, 500 caractères au plus. |
Les propriétés d’un champ placé par coordonnées
Section intitulée « Les propriétés d’un champ placé par coordonnées »| Propriété | Obligatoire | Description |
|---|---|---|
document |
oui | L’indice du document dans la demande, à partir de 0. |
kind |
oui | Le type, ci-dessus. |
page |
oui | Le numéro de page, à partir de 1. |
x, y |
oui | Le coin bas gauche du champ, en points, depuis le coin bas gauche de la page. |
width, height |
oui | La taille du champ, en points. |
required |
non | true par défaut. Un champ facultatif peut rester vide. Un groupe de boutons radio est obligatoire si l’une de ses options l’est. |
| les options | selon le type | À plat dans le champ : "label": "Ville", "group": "duree"… |
Le signataire ne peut pas signer tant qu’un champ obligatoire est vide, qu’un groupe n’a pas son option, ou qu’une mention n’est pas recopiée à l’identique (les espaces en trop ne comptent pas, les accents si). Tano vérifie tout cela de son côté aussi, pas seulement la page.
Positionner un champ
Section intitulée « Positionner un champ »Les positions s’expriment en points PDF (1 point = 1/72 de pouce, environ 0,35 mm), avec
l’origine en bas à gauche de la page, comme dans le format PDF lui-même. y grandit vers le
haut.
x = 60 et y = 80, de 180 × 50 points, sur une page A4 : son coin bas gauche est à 60 points du bord gauche et à 80 points du bas.| Format | Largeur × hauteur, en points |
|---|---|
| A4 | 595 × 842 |
| A5 | 420 × 595 |
| Lettre US | 612 × 792 |
Le nombre de pages de chaque document est rendu dans la réponse (documents[].pages). Un champ
doit tenir entièrement dans sa page : sinon la demande est refusée avec
invalid_field, et field désigne le signataire en cause.
Depuis un outil qui compte depuis le haut
Section intitulée « Depuis un outil qui compte depuis le haut »La plupart des visionneuses et des bibliothèques d’affichage (pdf.js, un éditeur d’image) placent l’origine en haut à gauche. Pour convertir une zone mesurée depuis le haut :
x = gauchey = hauteur_de_la_page − haut − hauteur_du_champ// Une zone mesurée depuis le haut de la page, en points (pdf.js : viewport à l'échelle 1).function versChampTano({ gauche, haut, largeur, hauteur }, hauteurPage) { return { x: gauche, y: hauteurPage - haut - hauteur, width: largeur, height: hauteur };}
versChampTano({ gauche: 60, haut: 712, largeur: 180, hauteur: 50 }, 842);// → { x: 60, y: 80, width: 180, height: 50 }def vers_champ_tano(gauche: float, haut: float, largeur: float, hauteur: float, hauteur_page: float) -> dict: """Une zone mesurée depuis le haut de la page, en points.""" return {"x": gauche, "y": hauteur_page - haut - hauteur, "width": largeur, "height": hauteur}
vers_champ_tano(60, 712, 180, 50, 842)# → {"x": 60, "y": 80, "width": 180, "height": 50}Un exemple
Section intitulée « Un exemple »Un bail de trois pages : le locataire paraphe chaque page, coche les conditions générales, recopie « Lu et approuvé », puis date et signe la dernière page.
{ "given_name": "Koffi", "family_name": "Yao", "phone": "+2250701021234", "auth_method": "otp_sms", "fields": [ {"document": 0, "kind": "initials", "page": 1, "x": 500, "y": 30, "width": 60, "height": 30}, {"document": 0, "kind": "initials", "page": 2, "x": 500, "y": 30, "width": 60, "height": 30}, {"document": 0, "kind": "checkbox", "page": 3, "x": 60, "y": 260, "width": 14, "height": 14}, {"document": 0, "kind": "mention", "page": 3, "x": 60, "y": 200, "width": 220, "height": 30, "mention": "Lu et approuvé"}, {"document": 0, "kind": "date", "page": 3, "x": 60, "y": 160, "width": 80, "height": 20}, {"document": 0, "kind": "signature", "page": 3, "x": 60, "y": 80, "width": 170, "height": 50} ]}| Au plus | |
|---|---|
| Champs par signataire | 50 |
| Documents par demande | 10 |
| Pages par document | 200 |
| Signataires par demande | 20 |
Étapes suivantes
Section intitulée « Étapes suivantes »- Faire signer un document avec ces champs.
- L’exemple complet, en Node.js et en Python.
© 2026 Qalebasse · Tano, plateforme de confiance numériquetano.africaDemander un accès[email protected]