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 avec zéro changement disruptif. Si vous utilisez 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.

Qu'y a-t-il dans la v1.10.0

Les cinq fonctionnalités sont additives. Les nouveaux champs ont pour valeur par défaut null ou false. Pas de suppression de schéma, pas de changement de comportement.

Logique de champ conditionnelle

C'est la fonctionnalité phare. Les champs peuvent désormais avoir des required_conditions et des visibility_conditions dynamiques qui s'évaluent 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 fois dans l'API et Firma.dev gère l'évaluation tant du côté client que du 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 de logique au niveau de l'ensemble (and ou or) contrôle la manière dont les groupes sont liés les uns aux autres, 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 de nom de conjoint ne doit apparaître que lorsque le signataire coche la 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 de nom du conjoint reste masqué et ignore complètement 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'utilisation que cela permet de réaliser directement :

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

• Sections de validation 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 saisit des informations, garantissant la clarté de la vue initiale

Le détail clé pour les intégrations sensibles en matière de 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 le biais d'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 du format PDF. Lorsque vous téléversez un document Word, Firma.dev le convertit automatiquement en PDF côté serveur. Pas de prétraitement côté client, pas de dépendances supplémentaires dans votre pipeline de déploiement.

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 leurs documents sous Word.

Point de terminaison de la piste d'audit

Un nouveau point de terminaison GET /signing-requests/{id}/audit renvoie le journal complet et chronologique des événements pour toute demande de signature. Il combine à la fois les actions d'administration (création, modification, envoi, annulation) et les actions du signataire (consultation, signature, refus, téléchargement) dans une chronologie unique.

Chaque événement comprend 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 répond à la demande 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 regroupées en un seul appel.

Pour obtenir le schéma complet des réponses 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 comportent 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 (l'option null hérite de l'élément parent)

3. Demande de signature remplace l'Espace de travail (l'option null hérite de l'élément parent)

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'utilisation ici est la marque blanche. Si vous intégrez Firma.dev dans votre propre produit et que vous souhaitez des signatures épurées sans aucun cadre Firma.dev sur le document final, attribuez à cette variable la valeur false au niveau de l'espace de travail pour que chaque demande de signature de cet espace de travail en hérite. Inversement, les secteurs réglementés qui exigent des identifiants de signature visibles peuvent explicitement la maintenir activée.

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

Il s'agit là d'une amélioration de l'ergonomie pour les développeurs. Lorsque vous supprimiez un destinataire dont les champs étaient référencés dans les conditions d'autres champs (issues de la logique conditionnelle ci-dessus), l'API n'avait auparavant aucun moyen de gérer la 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 répertoriant les champs dépendants

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

Cela s'avère particulièrement utile lorsque vous gérez de manière programmatique des destinataires dans des flux de travail dynamiques. Sans le paramètre force_remove_conditions, la suppression d'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

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

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

Commencer

Nouveau sur Firma.dev ? Tarification à l'usage de 0.049 $ par enveloppe, sans engagement ni minimum. Commencez à utiliser Firma.dev gratuitement, sans carte de crédit requise.

Obtenir la clé API

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