Firma.dev API v1.9.0 : Vérification OTP, Remplacement de Modèle de Document et Mises à Jour de Schéma

v1.9.0 est une version ciblée, construite au-dessus de v1.8.0, sans changements incompatibles. Si vous êtes déjà intégré aujourd’hui, rien ne casse. Deux nouvelles fonctionnalités sont désormais disponibles quand vous en avez besoin : la vérification OTP par e-mail du signataire et le remplacement du document du modèle.

Qu'y a-t-il dans v1.9.0

Les deux changements sont additifs. Aucun champ n'a été supprimé, aucun comportement de point de terminaison n'a été modifié, aucune migration n'est requise depuis v1.8.0.

Nouveau : vérification OTP par e-mail du signataire

Le paramètre require_otp_verification ajoute une étape de vérification d'identité avant qu'un signataire puisse accéder à un document. Lorsqu'il est activé, les signataires voient un écran de vérification à l'ouverture de leur lien de signature, reçoivent un code à 6 chiffres par e-mail et doivent le saisir avant le chargement du document.

Le paramètre est un champ à trois états : true, false ou null. null signifie hériter du niveau supérieur. La chaîne de remplacement s'exécute entreprise → espace de travail → modèle → demande de signature, la demande de signature ayant la priorité la plus élevée.

Activer l'OTP au niveau de l'espace de travail

PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}

PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}

PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}

Toutes les demandes de signature dans cet espace de travail requièrent désormais l'OTP par défaut.

Désactiver l'OTP pour une demande de signature spécifique

PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}

PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}

PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}

Cette demande ignore l'OTP quelle que soit la configuration de l'espace de travail.

Modifications du schéma

Nouveau : remplacement du document du modèle

Le nouveau POST /templates/{id}/replace-document point de terminaison vous permet de remplacer le PDF sous-jacent d'un modèle tout en conservant intactes toutes les positions des champs, les affectations des signataires et les paramètres.

Le document de remplacement doit satisfaire à deux exigences de validation : le même nombre de pages que l'original, et des dimensions de page dans une tolérance de 1 pt. Ces contraintes existent pour garantir que les positions des champs restent valides après l'échange. Si l'une ou l'autre vérification échoue, l'API renvoie une erreur 400 claire.

const fs = require("fs");

const base64PDF = fs.readFileSync("./updated-contract.pdf").toString("base64");

const response = await fetch(
  `https://api.firma.dev/v1/templates/${templateId}/replace-document`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ document: base64PDF })
  }
);

const updatedTemplate = await response.json();

const fs = require("fs");

const base64PDF = fs.readFileSync("./updated-contract.pdf").toString("base64");

const response = await fetch(
  `https://api.firma.dev/v1/templates/${templateId}/replace-document`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ document: base64PDF })
  }
);

const updatedTemplate = await response.json();

const fs = require("fs");

const base64PDF = fs.readFileSync("./updated-contract.pdf").toString("base64");

const response = await fetch(
  `https://api.firma.dev/v1/templates/${templateId}/replace-document`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ document: base64PDF })
  }
);

const updatedTemplate = await response.json();

Cas d'erreur :

Nouveaux points de terminaison

Mise à niveau depuis v1.8.0

Aucune action requise. Liste de contrôle :

• Aucun champ n'a été supprimé d'aucun objet existant

• Aucun changement de comportement pour les points de terminaison existants

• require_otp_verification est par défaut à null (hérite), donc les intégrations existantes ne sont pas affectées tant que vous ne le définissez pas explicitement

• POST /templates/{id}/replace-document est un nouveau point de terminaison, pas un remplacement de quoi que ce soit

La documentation complète de l'API se trouve sur docs.firma.dev. Le journal complet des modifications de l'API se trouve sur docs.firma.dev/guides/api-changelog.

Obtenez votre clé API et commencez à développer gratuitement, aucune carte de crédit requise.