Firma.dev API v1.10.0 : Champs conditionnels, prise en charge DOCX, piste d'audit, et plus

L’API Firma.dev v1.10.0 est disponible. Il s’agit de la version la plus riche en fonctionnalités à ce jour, qui apporte cinq fonctionnalités ajoutées sans aucun changement incompatible. Si vous êtes en v1.9.0, votre intégration existante fonctionne sans modification. Tout ce qui est présenté ici correspond à de nouvelles capacités, pas à un travail de migration.

Voici ce qu’il y a dans la boîte.

Ce qu’il y a dans v1.10.0

Les cinq fonctionnalités sont ajoutées de manière non destructive. Les nouveaux champs ont par défaut null ou false. Aucune suppression de schéma, aucun changement de comportement.

Logique conditionnelle des champs

C’est la fonctionnalité vedette. Les champs peuvent désormais avoir des required_conditions et visibility_conditions dynamiques qui s’évaluent en fonction des valeurs d’autres champs au moment de la signature. Au lieu de construire la logique conditionnelle de formulaire dans votre propre interface, vous définissez les règles une seule fois dans l’API et Firma.dev gère l’évaluation côté client et côté serveur.

La structure est composable. Un ConditionSet contient un ou plusieurs objets ConditionGroup, et chaque groupe contient des objets Condition individuels. L’opérateur logic au niveau de l’ensemble (and ou or) contrôle la manière dont les groupes se rapportent les uns aux autres, tandis que les conditions d’un groupe utilisent l’opérateur opposé.

Dix opérateurs de comparaison sont disponibles : is_filled, is_empty, equals, not_equals, contains, not_contains, greater_than, less_than, greater_than_or_equal, et less_than_or_equal.

Voici un exemple pratique. Supposons que vous ayez un contrat de travail dans lequel un champ pour le nom du conjoint ne doit apparaître que lorsque le signataire coche une case « Marié » :

{
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "married-checkbox-field-id",
            "operator": "equals",
            "value": "true"
          }
        ]
      }
    ]
  }
}

{
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "married-checkbox-field-id",
            "operator": "equals",
            "value": "true"
          }
        ]
      }
    ]
  }
}

{
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "married-checkbox-field-id",
            "operator": "equals",
            "value": "true"
          }
        ]
      }
    ]
  }
}

Lorsque la case n’est pas cochée, le champ du nom du conjoint reste masqué et contourne entièrement la validation. Lorsqu’elle est cochée, il apparaît et peut être défini comme obligatoire via une règle required_conditions distincte utilisant la même structure.

Voici quelques cas d’usage que cela débloque directement :

• Champs de divulgation conditionnelle qui n’apparaissent que lorsqu’un signataire sélectionne une option spécifique

• Sections d’approbation dépendantes où des champs de validation supplémentaires apparaissent en fonction d’un montant en dollars ou d’un niveau de risque

• Formulaires progressifs qui s’adaptent au fur et à mesure que le signataire renseigne des informations, en gardant l’affichage initial clair

Le détail clé pour les intégrations sensibles à la conformité : les conditions sont appliquées côté serveur lors de la soumission. Un signataire ne peut pas contourner les règles de visibilité ou d’obligation via une manipulation côté client. Si un champ doit être obligatoire en fonction de la valeur d’un autre champ, Firma.dev le valide côté serveur avant d’accepter le document signé.

Prise en charge des documents DOCX

Tous les points de terminaison d’import de documents acceptent désormais les fichiers .docx en plus du PDF. Lorsque vous importez un document Word, Firma.dev le convertit automatiquement en PDF côté serveur. Aucun prétraitement côté client, aucune dépendance supplémentaire dans votre pipeline.

Cela s’applique à la création de modèles, au remplacement de documents de modèle, à la création de demandes de signature et à toutes les opérations de mise à jour PUT/PATCH.

curl -X POST https://api.firma.dev/v1.10.0/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employment Agreement",
    "document": "BASE64_ENCODED_DOCX_CONTENT"
  }'

curl -X POST https://api.firma.dev/v1.10.0/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employment Agreement",
    "document": "BASE64_ENCODED_DOCX_CONTENT"
  }'

curl -X POST https://api.firma.dev/v1.10.0/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employment Agreement",
    "document": "BASE64_ENCODED_DOCX_CONTENT"
  }'

Les intégrations PDF existantes ne sont absolument pas affectées. Si vous importez déjà des PDF, rien ne change. Cela supprime simplement l’étape de conversion pour les équipes qui rédigent les documents dans Word.

Point de terminaison du journal d’audit

Un nouveau point de terminaison GET /signing-requests/{id}/audit renvoie le journal chronologique complet des événements pour toute demande de signature. Il combine les actions d’administration (créée, modifiée, envoyée, annulée) et les actions du signataire (consultée, signée, refusée, téléchargée) en une seule chronologie.

Chaque événement inclut un horodatage, une source (admin ou signer), un type d’événement, l’identité de l’acteur, l’adresse IP (pour les événements du signataire) et des métadonnées spécifiques à l’événement.

Ce point de terminaison couvre la demande de conformité la plus courante : produire un dossier de preuves qui montre exactement qui a fait quoi, quand et depuis où. Que vous en ayez besoin pour des journaux d’audit internes, des rapports réglementaires ou des flux d’activité destinés aux clients, toutes les données sont disponibles en un seul appel.

Pour le schéma de réponse complet et les détails du point de terminaison, consultez la référence de l’API du journal d’audit.

Contrôle du cadre de signature

Par défaut, les PDF finalisés incluent une bordure visuelle autour de chaque signature avec un ID de signature. Le nouveau paramètre show_signature_frame vous permet de contrôler cela à trois niveaux avec une chaîne d’héritage claire :

1. Entreprise définit la valeur par défaut (activée par défaut)

2. Espace de travail remplace l’Entreprise (null hérite)

3. Demande de signature remplace l’Espace de travail (null hérite)

Pour désactiver le cadre au niveau de l’espace de travail :

PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "show_signature_frame": false
  }
}

PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "show_signature_frame": false
  }
}

PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "show_signature_frame": false
  }
}

Le principal cas d’usage ici est le marquage blanc. Si vous intégrez Firma.dev dans votre propre produit et souhaitez des signatures épurées sans aucun encadrement Firma.dev sur le document final, définissez cette valeur sur false au niveau de l’espace de travail et chaque demande de signature dans cet espace l’hérite. À l’inverse, les secteurs réglementés qui exigent des identifiants de signature visibles peuvent explicitement le laisser activé.

Forcer la suppression des conditions lors de la suppression d’un utilisateur

Il s’agit ici d’une amélioration de l’ergonomie pour les développeurs. Lorsque vous supprimez un destinataire dont les champs sont référencés dans les conditions d’autres champs (comme dans la logique conditionnelle ci-dessus), l’API ne disposait auparavant d’aucun moyen de gérer la dépendance. Désormais, le paramètre force_remove_conditions contrôle le comportement :

• false (par défaut) : la requête est rejetée avec une erreur listant les champs dépendants

• true : supprime automatiquement les références aux conditions et poursuit la suppression

Cela est important lorsque vous gérez programmatiquement des destinataires dans des flux de travail dynamiques. Sans force_remove_conditions, la suppression d’un destinataire dont les champs alimentent des conditions sur d’autres champs vous obligerait d’abord à nettoyer manuellement chaque référence de condition.

Résumé technique

Nouveaux schémas : ConditionSet, ConditionGroup, Condition

Mise à niveau depuis v1.9.0

Aucun changement incompatible. Aucune suppression de champ. Aucun changement de comportement. Les nouveaux champs ont par défaut null ou false, donc les intégrations existantes ne nécessitent aucune modification. Si vous venez d’une version antérieure, cela s’applique à chaque version depuis v1.0.0. Consultez le journal des modifications complet de l’API pour l’historique complet des versions.

Pour les détails sur v1.9.0 (vérification OTP, remplacement de document de modèle), consultez la section du journal des modifications v1.9.0.

Commencer

Nouveau sur Firma.dev ? Tarification à l’usage à 0,029 $ par enveloppe, sans contrat ni minimum. Commencez gratuitement avec Firma.dev, sans carte de crédit requise.

Obtenir la clé API

Pour la référence API complète, consultez la documentation de Firma.dev.