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 concentrée construite sur v1.8.0 sans changements majeurs. Si vous êtes intégré aujourd'hui, rien ne change. Deux nouvelles fonctionnalités sont désormais disponibles lorsque vous en avez besoin : vérification OTP par email du signataire et remplacement de document de 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 à partir de v1.8.0.

Nouveau : Vérification OTP par email du signataire

Le paramètre require_otp_verification ajoute une étape de vérification d'identité avant qu'un signataire ne 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 email, et doivent le saisir avant que le document ne se charge.

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

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 nécessitent 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 indépendamment des paramètres de l'espace de travail.

Changements de schéma

Nouveau : Remplacement de document de modèle

Le nouveau point de terminaison POST /templates/{id}/replace-document vous permet de remplacer le PDF sous-jacent sur un modèle tout en conservant tous les emplacements de champ, attributions de signataire, et paramètres intacts.

Le document de remplacement doit répondre à deux exigences de validation : même nombre de pages que l'original, et dimensions de page dans une tolérance de 1pt. Ces contraintes existent pour garantir que les positions des champs restent valides après l'échange. Si l'une des vérifications échoue, l'API renvoie un 400 avec une erreur 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 à partir de v1.8.0

Aucune action requise. La liste de contrôle :

• Aucun champ supprimé de tout objet existant

• Aucun changement de comportement pour les points de terminaison existants

• require_otp_verification par défaut à null (hérite), donc les intégrations existantes ne sont pas affectées jusqu'à ce que vous l'ayez explicitement défini

• 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 changelog complet de l'API est sur docs.firma.dev/guides/api-changelog.

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