L'API bSign

Pour commencer

L'API se trouve à https://api.bsign.ca/v1. Tout ce que vous envoyez et recevez est en JSON; les heures sont au format ISO 8601, en UTC.

1. Dans bSign, ouvrez Paramètres > API et webhooks et créez un jeton. Il n'est affiché qu'une fois : gardez-le en lieu sûr, comme un mot de passe.
2. Envoyez-le avec chaque requête sous la forme Authorization: Bearer <token>.
3. Vérifiez qu'il fonctionne :

curl https://api.bsign.ca/v1/me \
  -H "Authorization: Bearer bsign_..."

{ "id": "fL3S02MVAQ", "name": "Jordan Office", "email": "jordan@example.com",
  "site": { "id": "ATCuMMWmob", "name": "Example Dental" } }

Un jeton agit au nom de la personne qui l'a créé : ses modèles (et ceux qu'on partage avec elle) et les documents qu'elle envoie. Créez-en un par intégration, pour pouvoir révoquer chacun séparément. Un jeton dure au plus un an et cesse de fonctionner si le compte est désactivé.

Envoyer à partir d'un modèle

Configurez le document une fois dans bSign comme modèle, avec un rôle pour chaque destinataire (Client, Gestionnaire…) et ses champs. Ensuite :

1. GET /templates liste vos modèles. GET /templates/{id} montre les rôles d'un modèle, et ses champs avec leurs types et leurs choix.
2. POST /templates/{id}/send crée le document et l'envoie. Indiquez une personne pour chaque rôle que le modèle laisse ouvert, et des valeurs pour ses champs, par nom.

curl -X POST https://api.bsign.ca/v1/templates/T9x8Y7w6V5/send \
  -H "Authorization: Bearer bsign_..." \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "Q-11520",
    "recipients": [
      { "role": "Client", "name": "Jane Client", "email": "jane@acmedental.example" }
    ],
    "fields": {
      "Company name": "Acme Dental",
      "Start date": "2026-10-01",
      "Plan": "Business"
    }
  }'

La réponse est le nouveau document (201 Created), envoyé pour signature. Ce qui va dans fields :

• Les champs que le modèle remplit avant l'envoi sont inscrits dans le document. Les champs obligatoires doivent être fournis.
• Les champs propres à un destinataire commencent avec la valeur, et il peut la changer en signant. "Client::Job title" désigne le champ d'un rôle quand deux champs portent le même nom.
• Les dates sous la forme 2026-10-01 (ou dans le format propre au champ), les cases à cocher comme une liste de choix, les listes déroulantes et les boutons radio comme l'un des choix. Les valeurs vides sont ignorées.

Autres options : name, note, expiresInDays (1 à 365), sendInOrder, et sendEmails: false pour n'envoyer aucun courriel et recevoir plutôt le lien de signature de chaque destinataire (pour l'envoyer par texto, par exemple). S'il manque quelque chose ou qu'une valeur est erronée, la réponse est 422, avec chaque problème listé.

Suivre les documents

• GET /documents liste les documents que vous avez envoyés, les plus récemment modifiés d'abord. Filtrez par status (in_progress, completed, declined, voided, expired, draft), reference, templateId, search ou updatedSince.
• GET /documents/{id} donne l'état de chaque destinataire (sent, viewed, signed, waiting son tour…) et le moment de sa signature.
• GET /documents/{id}/file télécharge le PDF : signé et scellé une fois terminé. GET /documents/{id}/certificate télécharge le certificat d'achèvement.
• POST /documents/{id}/remind envoie un courriel à ceux qui doivent encore signer. POST /documents/{id}/void l'annule, avec une raison (reason) communiquée aux destinataires.
• GET /documents/{id}/history donne tout ce qui lui est arrivé.

Webhooks

Plutôt que de demander toutes les quelques minutes, laissez bSign vous prévenir. Ajoutez un webhook dans Paramètres > API et webhooks, ou avec POST /webhooks, et bSign envoie (POST) chaque événement à votre adresse au moment où il se produit :

{
  "id": "Xb3kQ9pLmN",
  "event": "document.completed",
  "createdAt": "2026-09-29T16:20:00.000Z",
  "document": { "id": "a1B2c3D4e5", "name": "Managed Services Agreement",
                "reference": "Q-11520", "status": "completed" },
  "actor": { "name": "Jane Client", "email": "jane@acmedental.example", "role": "recipient" }
}

Les événements : document.sent, viewed, signed, approved, declined, voided, completed, recipient_changed, reminder_sent, expiry_notice, expiry_extended, corrected, skipped et paper_copy. Une livraison qui échoue est retentée après 30 secondes et après 2 minutes; id reste le même, vous pouvez donc ignorer les doublons.

Chaque livraison est signée avec le secret du webhook, dans l'en-tête X-bSign-Signature : t=<unix time>,v1=<HMAC-SHA256 of "t.body">. Vérifiez-la avant de vous fier à l'événement :

// Node.js, with the raw request body
const crypto = require("crypto");
const [t, v1] = req.get("X-bSign-Signature").split(",").map((p) => p.split("=")[1]);
const expected = crypto.createHmac("sha256", process.env.BSIGN_WEBHOOK_SECRET)
  .update(`${t}.${rawBody}`).digest("hex");
const valid = v1.length === expected.length
  && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))
  && Math.abs(Date.now() / 1000 - Number(t)) < 300; // not an old replay

GET /events?type=document.completed liste les derniers événements sous la même forme, pour les outils qui préfèrent demander.

Tous les points de terminaison

Chaque champ est décrit dans le fichier OpenAPI, api.bsign.ca/v1/openapi.json : importez-le dans Postman, Insomnia ou votre générateur de code.

Erreurs et limites

Tout ce qui n'est pas un succès revient sous la forme { "error": { "code", "message" } }, avec les problèmes listés dans details.problems quand il y en a plusieurs :

• 401 aucun jeton, ou jeton révoqué ou expiré;
• 404 introuvable, ou qui ne vous appartient pas;
• 409 impossible pour l'instant (relancer un document terminé, un certificat avant l'achèvement);
• 422 quelque chose de manquant ou d'erroné dans ce que vous avez envoyé;
• 402 l'allocation du forfait du site est épuisée;
• 429 trop de requêtes : 300 par minute par jeton, et 200 documents envoyés toutes les 10 minutes.

Power Automate

Le connecteur bSign pour Microsoft Power Automate fonctionne dès aujourd'hui comme connecteur personnalisé dans votre propre Microsoft 365, sans approbation. Les flux peuvent envoyer des documents à partir de vos modèles, démarrer quand un document est signé, terminé ou refusé, et classer le PDF signé où vous voulez.

1. Dans bSign, ouvrez Paramètres > API et webhooks et créez un jeton nommé « Power Automate ». Les flux agissent en votre nom : vos modèles et les documents que vous envoyez.
2. Téléchargez la définition du connecteur bSign et son icône.
3. Dans make.powerautomate.com, ouvrez Data > Custom connectors > New custom connector > Import an OpenAPI file, nommez-le bSign et choisissez la définition. Dans General, téléversez l'icône et réglez la couleur de fond à #1758c9, puis Create connector.
4. Dans Test, ajoutez une connexion et collez votre jeton. Le déclencheur When a document event happens et les actions (Send document from template, Get document, Download document PDF et autres) sont maintenant dans vos flux.

Vous préférez la ligne de commande? Le connecteur complet en zip fonctionne avec l'outil paconn de Microsoft (paconn create --settings settings.json). Pour que vos collègues l'utilisent, partagez le connecteur depuis Power Automate ou ajoutez-le à une solution.

Zapier

L'application Zapier de bSign démarre des Zaps quand des documents sont envoyés, consultés, signés, terminés, refusés ou annulés, et envoie des documents à partir de vos modèles comme étape de n'importe quel Zap, avec leurs champs remplis par les applications qui précèdent.

1. Ouvrez l'invitation Zapier de bSign et acceptez-la avec votre compte Zapier.
2. Dans bSign, ouvrez Paramètres > API et webhooks et créez un jeton nommé « Zapier ». Les Zaps agissent en votre nom : vos modèles et les documents que vous envoyez.
3. Dans un Zap, choisissez bSign comme déclencheur ou comme action et collez le jeton quand Zapier demande la connexion.

bSign est dans Zapier comme application sur invitation pendant l'examen de Zapier pour son répertoire public; l'invitation vous donne la même application.

Des questions, ou une intégration que vous aimeriez que nous construisions? support@bsign.ca