Aller au contenu

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.

  1. 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());
    }

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

  2. 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 laissez fields vide.

    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é",
    email: "[email protected]", auth_method: "otp_email", position: 1,
    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_… ongoing

    En 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é.

  3. 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`);
  4. 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.signed Mettre à jour votre suivi : data.signer_id a signé.
    signer.declined La demande s’arrête : prévenir votre équipe.
    signature_request.completed Télécharger le document signé et la preuve (étape 6).
    signature_request.expired Relancer à la main, ou créer une nouvelle demande.

    data.reference reprend votre référence (BAIL-2026-118) : vous retrouvez votre dossier sans rappeler l’API.

  5. 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`);
    }

    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.

  6. 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`));
    }

    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.

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.

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