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 en ligne. Il s'agit de la version la plus riche en fonctionnalités à ce jour, proposant cinq fonctionnalités additives sans aucun changement cassant. Si vous êtes sur la v1.9.0, votre intégration existante fonctionne sans modification. Tout ici est une nouvelle capacité, pas un travail de migration.

Voici ce qui est inclus.

Nouveautés de la v1.10.0

Les cinq fonctionnalités sont additives. Les nouveaux champs sont définis par défaut sur null ou false. Aucune suppression de schéma, aucun changement de comportement.

Logique conditionnelle des champs

C'est la fonctionnalité phare. Les champs peuvent désormais avoir des règles dynamiques required_conditions et visibility_conditions évaluées en fonction des valeurs d'autres champs au moment de la signature. Au lieu de créer une logique de formulaire conditionnelle dans votre propre interface utilisateur, vous définissez les règles une seule fois dans l'API et Firma.dev gère l'évaluation à la fois 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 sont liés entre eux, tandis que les conditions au sein 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 où 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 est décochée, le champ du nom du conjoint reste masqué et ignore totalement la validation. Lorsqu'elle est cochée, il apparaît et peut être rendu obligatoire via une règle required_conditions distincte utilisant la même structure.

Quelques cas d'usage que cela débloque directement :

• Champs de divulgation conditionnels 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 ou d'un niveau de risque

• Formulaires progressifs qui s'adaptent au fur et à mesure que le signataire remplit les informations, maintenant la vue initiale épurée

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 par une manipulation côté client. Si un champ doit être obligatoire en fonction de la valeur d'un autre champ, Firma.dev valide cela côté serveur avant d'accepter le document signé.

Prise en charge des documents DOCX

Tous les points de terminaison de téléversement de documents acceptent désormais les fichiers .docx en plus des PDF. Lorsque vous téléversez 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èles, à 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 téléversez déjà des PDF, rien ne change. Cela supprime simplement l'étape de conversion pour les équipes qui rédigent des documents dans Word.

Point de terminaison pour piste 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 à la fois les actions administrateur (créé, modifié, envoyé, annulé) et les actions du signataire (consulté, signé, refusé, téléchargé) dans une chronologie unique.

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

Ce point de terminaison répond à l'exigence de conformité la plus courante : produire un dossier de preuves montrant exactement qui a fait quoi, quand et d'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 accessibles en un seul appel.

Pour consulter le schéma complet de la réponse et les détails du point de terminaison, consultez la référence API de la piste 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 identifiant 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 cas d'usage principal est la marque blanche. 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 ceci sur false au niveau de l'espace de travail et chaque demande de signature dans cet espace en héritera. À l'inverse, les secteurs réglementés exigeant des identifiants de signature visibles peuvent explicitement le laisser activé.

Suppression forcée 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 (provenant de la logique conditionnelle ci-dessus), l'API n'avait auparavant aucun moyen de gérer cette dépendance. Désormais, le paramètre force_remove_conditions contrôle ce comportement :

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

• true : supprime automatiquement les références de condition et procède à la suppression

Cela a son importance lorsque vous gérez par programmation des destinataires dans des flux de travail dynamiques. Sans force_remove_conditions, supprimer un destinataire dont les champs alimentent des conditions sur d'autres champs vous obligerait à nettoyer manuellement chaque référence de condition au préalable.

Résumé technique

Nouveaux schémas : ConditionSet, ConditionGroup, Condition

Mise à niveau depuis la v1.9.0

Aucun changement cassant. Aucune suppression de champ. Aucun changement de comportement. Les nouveaux champs sont définis par défaut sur null ou false, les intégrations existantes ne nécessitent donc aucune modification. Si vous venez d'une version antérieure, la même règle s'applique à chaque version depuis la v1.0.0. Consultez le journal des modifications complet de l'API pour connaître l'historique complet des versions.

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

Commencer

Nouveau sur Firma.dev ? Tarification à l'utilisation à 0,049 € par enveloppe, sans engagement ni minimum. Commencez gratuitement avec Firma.dev, sans carte bancaire requise.

Obtenir la clé API

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