Exemple complet
Cet exemple fait signer un bail par deux personnes, dans l’ordre : la bailleresse par courriel, puis le locataire par SMS. Il tient en un fichier, sans autre dépendance que Node.js 18 ou Python 3.10, et suit les étapes de la vue d’ensemble. Avec les SDK serveur, le client de l’étape 1 disparaît et chaque étape tient en une ligne.
-
Un client qui signe ses requêtes. Toute requête porte la clé ; les créations sont en plus signées et portent une
Idempotency-Key.tano.mjs import { createHmac, randomUUID } from "node:crypto";import { readFile, writeFile } from "node:fs/promises";const API = "https://api.tano.africa";const CLE = process.env.TANO_API_KEY;const SECRET = CLE.slice(CLE.lastIndexOf("_") + 1);async function tano(methode, cible, donnees) {const entetes = { Authorization: `Bearer ${CLE}` };let corps;if (methode === "POST") {corps = JSON.stringify(donnees ?? {});const horodatage = String(Math.floor(Date.now() / 1000));const message = `${horodatage}.POST.${cible}.${corps}`;Object.assign(entetes, {"Content-Type": "application/json","Idempotency-Key": randomUUID(),"X-Tano-Timestamp": horodatage,"X-Tano-Signature": "v2=" + createHmac("sha256", SECRET).update(message).digest("hex"),});}const reponse = await fetch(API + cible, { method: methode, headers: entetes, body: corps });if (!reponse.ok) throw new Error(JSON.stringify((await reponse.json()).error));const type = reponse.headers.get("content-type") ?? "";return type.includes("json") ? reponse.json() : Buffer.from(await reponse.arrayBuffer());}tano.py import base64, hashlib, hmac, json, os, time, urllib.error, urllib.request, uuidAPI = "https://api.tano.africa"CLE = os.environ["TANO_API_KEY"]SECRET = CLE.rsplit("_", 1)[1]def tano(methode: str, cible: str, donnees: dict | None = None):entetes = {"Authorization": f"Bearer {CLE}"}corps = Noneif methode == "POST":corps = json.dumps(donnees or {}).encode()horodatage = str(int(time.time()))message = f"{horodatage}.POST.{cible}.".encode() + corpsentetes |= {"Content-Type": "application/json","Idempotency-Key": str(uuid.uuid4()),"X-Tano-Timestamp": horodatage,"X-Tano-Signature": "v2=" + hmac.new(SECRET.encode(), message, hashlib.sha256).hexdigest(),}requete = urllib.request.Request(API + cible, data=corps, method=methode, headers=entetes)try:with urllib.request.urlopen(requete) as reponse:contenu = reponse.read()if "json" in reponse.headers.get("Content-Type", ""):return json.loads(contenu)return contenuexcept urllib.error.HTTPError as erreur:raise RuntimeError(erreur.read().decode()) from NoneUne même requête signée ne se rejoue pas : chaque appel prend son propre horodatage et sa propre clé d’idempotence. Pour réessayer une création après une coupure réseau, gardez la même
Idempotency-Key: voir l’idempotence. -
Créer et envoyer la demande. Le PDF voyage en base 64. Chaque signataire porte ses champs, placés en points depuis le coin bas gauche de la page. Si vous produisez le PDF, écrivez plutôt des ancres (
{{s1|signature}}) dedans, et laissezfieldsvide.const pdf = (await readFile("bail.pdf")).toString("base64");const demande = await tano("POST", "/v1/signature-requests", {name: "Bail — appartement Cocody",reference: "BAIL-2026-118",documents: [{ filename: "bail.pdf", content: pdf }],signers: [{given_name: "Aya", family_name: "Koné",fields: [{ document: 0, kind: "signature", page: 1, x: 60, y: 80, width: 170, height: 50 }],},{given_name: "Koffi", family_name: "Yao",phone: "+2250701021234", auth_method: "otp_sms", position: 2,fields: [{ document: 0, kind: "mention", page: 1, x: 300, y: 140, width: 220, height: 30, mention: "Lu et approuvé" },{ document: 0, kind: "signature", page: 1, x: 300, y: 80, width: 170, height: 50 },],},],activate: true,});console.log(demande.id, demande.status); // sr_… ongoingwith open("bail.pdf", "rb") as fichier:pdf = base64.b64encode(fichier.read()).decode()demande = tano("POST", "/v1/signature-requests", {"name": "Bail — appartement Cocody","reference": "BAIL-2026-118","documents": [{"filename": "bail.pdf", "content": pdf}],"signers": [{"given_name": "Aya", "family_name": "Koné","fields": [{"document": 0, "kind": "signature", "page": 1, "x": 60, "y": 80, "width": 170, "height": 50}],},{"given_name": "Koffi", "family_name": "Yao","phone": "+2250701021234", "auth_method": "otp_sms", "position": 2,"fields": [{"document": 0, "kind": "mention", "page": 1, "x": 300, "y": 140, "width": 220, "height": 30, "mention": "Lu et approuvé"},{"document": 0, "kind": "signature", "page": 1, "x": 300, "y": 80, "width": 170, "height": 50},],},],"activate": True,})print(demande["id"], demande["status"]) # sr_… ongoingEn production, la bailleresse reçoit maintenant son invitation par courriel. Le locataire attend son tour (
pending) : il sera invité dès qu’elle aura signé. -
Ou afficher la signature dans votre application. Plutôt que de laisser Tano envoyer le lien, demandez-le pour un signataire invité et ouvrez-le chez vous. Le lien précédent cesse alors de valoir.
const [aya] = demande.signers;const { url } = await tano("POST", `/v1/signature-requests/${demande.id}/signers/${aya.id}/link`);aya = demande["signers"][0]lien = tano("POST", f"/v1/signature-requests/{demande['id']}/signers/{aya['id']}/link")["url"] -
Suivre la demande par webhook. Déclarez une adresse abonnée aux événements de la signature (
POST /v1/webhook-endpoints), puis, à chaque livraison, vérifiez sa signature avant d’agir.Événement Ce que vous faites signer.signedMettre à jour votre suivi : data.signer_ida signé.signer.declinedLa demande s’arrête : prévenir votre équipe. signature_request.completedTélécharger le document signé et la preuve (étape 6). signature_request.expiredRelancer à la main, ou créer une nouvelle demande. data.referencereprend votre référence (BAIL-2026-118) : vous retrouvez votre dossier sans rappeler l’API. -
En bac à sable, faire signer à leur place. Aucun message n’est parti : simulez la réponse de chaque signataire, dans l’ordre. Vous recevez les mêmes webhooks qu’en production.
for (const signataire of demande.signers) {await tano("POST", `/v1/sandbox/signature-requests/${demande.id}/signers/${signataire.id}/sign`);}for signataire in demande["signers"]:tano("POST", f"/v1/sandbox/signature-requests/{demande['id']}/signers/{signataire['id']}/sign")Pour signer vous-même sur la vraie page, ouvrez le lien de l’étape 3 et saisissez le code
000000: voir le bac à sable. -
Télécharger le document signé et la preuve. Une fois la demande
completed, le document porte les champs remplis et le cachet de Tano ; le fichier de preuve dit qui a signé, quand et comment.const finale = await tano("GET", `/v1/signature-requests/${demande.id}`);if (finale.status === "completed") {const [document] = finale.documents;const base = `/v1/signature-requests/${demande.id}`;await writeFile("bail-signe.pdf", await tano("GET", `${base}/documents/${document.id}/download`));await writeFile("bail-preuve.pdf", await tano("GET", `${base}/audit-trail`));}finale = tano("GET", f"/v1/signature-requests/{demande['id']}")if finale["status"] == "completed":document = finale["documents"][0]base = f"/v1/signature-requests/{demande['id']}"with open("bail-signe.pdf", "wb") as fichier:fichier.write(tano("GET", f"{base}/documents/{document['id']}/download"))with open("bail-preuve.pdf", "wb") as fichier:fichier.write(tano("GET", f"{base}/audit-trail"))En bac à sable, les deux fichiers portent le bandeau « SPÉCIMEN » et l’en-tête
X-Tano-Sandbox: true: ils ne valent rien, et c’est voulu.
Passer en production
Section intitulée « Passer en production »Remplacez la clé de bac à sable par une clé tano_prod_…, retirez l’étape 5, et vérifiez la
liste de mise en production. Les invitations, les codes et les relances
partent alors pour de vrai.
Étapes suivantes
Section intitulée « Étapes suivantes »- Faire signer un document : chaque champ du corps, et les erreurs fréquentes.
- Placer les champs : les types et le positionnement.
- La référence de la signature.
© 2026 Qalebasse · Tano, plateforme de confiance numériquetano.africaDemander un accès[email protected]