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 sur la version 1.8.0 sans modifications de rupture. Si vous êtes intégré aujourd'hui, rien ne se casse. Deux nouvelles fonctionnalités sont désormais disponibles lorsque vous en avez besoin : la vérification OTP par email du signataire et le remplacement du document modèle.

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

Les deux changements sont additifs. Aucun champ n'a été retiré, aucun comportement de point de terminaison n'a été modifié, aucune migration n'est requise par rapport à la version 1.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 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 substitution fonctionne entreprise → espace de travail → modèle → demande de signature, 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ésactivation de 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 du paramètre de l'espace de travail.

Changements de schéma

Nouveau : Remplacer le document modèle

Le nouveau point de terminaison POST /templates/{id}/replace-document vous permet d'échanger le PDF sous-jacent sur un modèle tout en conservant tous les placements de champs, les affectations de signataires et les 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 ou l'autre de ces vérifications échoue, l'API renvoie une 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'erreurs :

Nouveaux points de terminaison

Mise à niveau de la version 1.8.0

Aucune action requise. La liste de vérification :

• Aucun champ retiré d’un objet existant

• Aucun changement de comportement des points de terminaison existants

• require_otp_verification est par défaut à null (hérite), donc les intégrations existantes ne sont pas affectées jusqu'à ce que vous le définissiez 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 est disponible sur docs.firma.dev. Le journal complet des modifications de l'API est disponible sur docs.firma.dev/guides/api-changelog.

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