Aller au contenu

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.

  • 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, height en 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.

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

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.

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.

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.

page A4 : 595 × 842 pointssignaturexy(0, 0)y ↑x →(595, 0)(595, 842)
Un champ placé à 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.

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 = gauche
y = 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 }

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

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