Mises à jour de produit

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

Écrit par

Icônes d'un cadenas, d'un téléchargement de document et de code représentant les mises à jour de l'API Firma.dev v1.9.0, y compris les modifications apportées aux schémas et aux modèles.

La version 1.9.0 est une mise à jour ciblée qui s'appuie sur la v1.8.0 sans aucun changement cassant. Si vous êtes déjà intégré aujourd'hui, rien ne sera interrompu. Deux nouvelles fonctionnalités sont désormais disponibles en cas de besoin : la vérification par OTP par e-mail pour le signataire et le remplacement du document de modèle.

Au programme de la v1.9.0

Quoi

Type

Détails

OTP par e-mail pour le signataire

Nouvelle fonctionnalité + champ de schéma

require_otp_verification sur les paramètres de la demande de signature, de l'espace de travail et de l'entreprise

Remplacement du document de modèle

Nouvelle fonctionnalité + endpoint

POST /templates/{id}/replace-document

Les deux modifications sont cumulatives. Aucun champ n'a été supprimé, aucun comportement d'endpoint n'a été modifié, aucune migration n'est requise depuis la v1.8.0.

Nouveau : Vérification par OTP par e-mail pour le 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'elle est activée, 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.

Ce paramètre est un champ à trois états : true, false ou null. La valeur null signifie qu'il hérite du niveau supérieur. La chaîne de priorité s'applique comme suit : entreprise → espace de travail → modèle → demande de signature, la demande de signature ayant la priorité la plus élevée.

Niveau

Champ

Comportement

Entreprise

require_otp_verification

Valeur par défaut de référence pour tous les espaces de travail

Paramètres de l'espace de travail

require_otp_verification

Remplace l'entreprise ; null hérite de l'entreprise

Modèle

require_otp_verification

Remplace l'espace de travail ; null hérite de l'espace de travail

Paramètres de la demande de signature

require_otp_verification

Priorité la plus élevée ; null hérite du modèle/espace de travail

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 un 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, quel que soit le paramètre de l'espace de travail.

Modifications du schéma

Objet

Champ

Type

SigningRequestSettings

require_otp_verification

boolean | null

WorkspaceSettings

require_otp_verification

boolean | null

Nouveau : Remplacement du document de modèle

Le nouvel endpoint POST /templates/{id}/replace-document vous permet de remplacer le PDF sous-jacent d'un modèle tout en conservant intacts tous les emplacements de champs, les assignations de signataires et les paramètres.

Le document de remplacement doit respecter deux critères 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 le remplacement. Si l'un de ces contrôles é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 :

Statut

Cause

400

Nombre de pages non concordant

400

Dimensions de page non concordantes (dépasse la tolérance de 1 pt)

400

PDF invalide ou corrompu

Nouveaux endpoints

Méthode

Chemin

Description

POST

/templates/{id}/replace-document

Remplacer le PDF du modèle tout en préservant tous les emplacements de champs

Mise à niveau depuis la v1.8.0

Aucune action requise. La liste de contrôle :

  • Aucun champ supprimé d'un objet existant

  • Aucune modification de comportement sur les endpoints existants

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

  • POST /templates/{id}/replace-document est un nouvel endpoint, il n'en remplace aucun autre

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

Obtenez votre clé API et commencez à développer gratuitement, sans carte bancaire requise.

  1. Titre

Articles connexes

Notre plateforme est conçue pour permettre aux entreprises de toutes tailles de travailler plus intelligemment et d'atteindre leurs objectifs avec confiance.

Image de fond

Prêt à ajouter des signatures électroniques à votre application ?

Commencez gratuitement. Aucune carte de crédit requise. Payez seulement 0,049 € par enveloppe lorsque vous serez prêt à lancer votre activité.

Image de fond

Prêt à ajouter des signatures électroniques à votre application ?

Commencez gratuitement. Aucune carte de crédit requise. Payez seulement 0,049 € par enveloppe lorsque vous serez prêt à lancer votre activité.

Image de fond

Prêt à ajouter des signatures électroniques à votre application ?

Commencez gratuitement. Aucune carte de crédit requise. Payez seulement 0,049 € par enveloppe lorsque vous serez prêt à lancer votre activité.