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

Firma.dev API v1.10.0 est en ligne. Il s'agit de la version la plus riche en fonctionnalités à ce jour, proposant cinq fonctionnalités additionnelles sans aucun changement radical. Si vous êtes en v1.9.0, votre intégration existante fonctionne sans modification. Tout ici relève de nouvelles capacités, pas de travaux de migration.

Voici ce qu'il y a dans le package.

Quoi de neuf dans la v1.10.0

Les cinq fonctionnalités sont additionnelles. Les nouveaux champs ont par défaut une valeur 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 required_conditions et visibility_conditions dynamiques qui s'évaluent en fonction d'autres valeurs de champs au moment de la signature. Au lieu de construire 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 à la fois côté client et 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 du set (and ou or) contrôle comment les groupes se rapportent 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 devrait uniquement apparaître 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 de nom de conjoint reste caché et ne requiert aucune validation. Lorsqu'elle est cochée, il apparaît et peut être défini comme requis par une règle required_conditions distincte utilisant la même structure.

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

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

• Sections d'approbation dépendantes où des champs de validation supplémentaires s'activent 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 saisit des informations, gardant la vue initiale propre

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

Support de document DOCX

Tous les points de terminaison de chargement de documents acceptent désormais les fichiers .docx en plus des PDF. Lorsque vous téléchargez un document Word, Firma.dev le convertit automatiquement en PDF côté serveur. Aucun prétraitement côté client, pas de dépendances supplémentaires dans votre pipeline.

Cela s'applique à la création de modèles, au remplacement de documents 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 sont complètement intactes. Si vous téléchargez 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 de la piste de vérification

Un nouveau point de terminaison GET /signing-requests/{id}/audit retourne le journal complet des événements chronologiques pour toute demande de signature. Il combine à la fois les actions des administrateurs (créé, modifié, envoyé, annulé) et les actions des signataires (consulté, signé, refusé, téléchargé) en une seule chronologie.

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

Ce point de terminaison couvre la demande de conformité la plus courante : produire un pack 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és destinés aux clients, les données sont toutes dans un seul appel.

Pour le schéma de réponse complet et les détails des points de terminaison, voir la référence API de la piste de vérification.

Contrôle du cadre de signature

Par défaut, les PDF complété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 propre:

1. Entreprise définit le défaut (activé par défaut)

2. Espace de travail surcharge Entreprise (null hérite)

3. Demande de signature surcharge 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
  }
}

L'utilisation principale ici est le marquage blanc. Si vous intégrez Firma.dev dans votre propre produit et souhaitez des signatures claires sans aucun cadrage Firma.dev sur le document final, définissez cela à false au niveau de l'espace de travail et chaque demande de signature dans cet espace de travail l'hérite. En revanche, les industries réglementées qui nécessitent des identifiants de signature visibles peuvent explicitement le maintenir activé.

Forcer la suppression des conditions lors de la suppression utilisateur

Ceci est une amélioration de l'ergonomie pour les développeurs. Lorsque vous supprimez un destinataire dont les champs sont référencés dans d'autres conditions de champs (à partir 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 le comportement :

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

• true: Supprime automatiquement les références de conditions et poursuit la suppression

Cela a de l'importance lorsque vous gérez programmaticalement des destinataires dans des workflows dynamiques. Sans force_remove_conditions, supprimer un destinataire dont les champs alimentent des conditions sur d'autres champs nécessiterait de nettoyer manuellement chaque référence de condition d'abord.

Résumé technique

Nouveaux schémas : ConditionSet, ConditionGroup, Condition

Mise à niveau depuis v1.9.0

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

Pour les détails sur v1.9.0 (vérification OTP, remplacement de documents modèles), voyez la section des changements de v1.9.0.

Commencer

Nouveau chez Firma.dev ? Tarification à l’utilisation à $0.029 par enveloppe, pas de contrats ou minimums. Commencez avec Firma.dev gratuitement, pas besoin de carte de crédit.

Obtenir la clé API

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