Firma.dev API v1.3 + v1.4 : Nouveaux types de champs, domaines de courriel personnalisés et contrôle granulaire

Nous avons publié deux mises à jour consécutives de l'API, rien que la semaine dernière. Aucun changement perturbateur, mais de nouvelles fonctionnalités… le tout en février 2026. 👊

La version 1.3 est arrivée avec les domaines de messagerie personnalisés et le suivi du coût en crédits. La version 1.4 a suivi avec trois nouveaux types de champs et des opérations PATCH granulaires pour les champs individuels.

Ces deux versions partagent le même thème : plus de contrôle sans plus de complexité. De plus, aucune d'entre elles n'introduit de changements perturbateurs, vous pouvez donc adopter ces fonctionnalités à votre propre rythme.

Si vous recherchez une solution de signature API qui vous offre de la flexibilité sans imposer de migrations, voilà à quoi cela ressemble.

Voici toutes les nouveautés des versions v1.3 et v1.4.

v1.4.0 : Nouveaux types de champs et mises à jour granulaires

Date de publication : 31 janvier 2026

La version 1.4 élargit les possibilités d'action sur les champs de documents et la manière de les mettre à jour. Trois nouveaux types de champs vous offrent plus d'options pour collecter des données. Les opérations PATCH prennent désormais en charge les mises à jour de champs individuels. Et un nouveau paramètre template_user_id rend la correspondance des destinataires explicite.

Trois nouveaux types de champs

La liste d'énumération des types de champs comprend désormais textarea, url et radio_buttons :

Le type radio fonctionne toujours pour la compatibilité ascendante, mais radio_buttons est le nom canonique à l'avenir.

Les types de champs url

Le nouveau type de champ url vous permet d'intégrer des liens cliquables directement dans vos documents à signer. Le champ est automatiquement configuré sur read_only: true puisque les signataires cliquent sur le lien plutôt que de le modifier.

Utilisez read_only_value pour définir l'URL cible et format_rules.urlDisplayText pour personnaliser ce que voient les signataires :

{
  "field": {
    "type": "url",
    "position": { "x": 100, "y": 200, "width": 150, "height": 30 },
    "page_number": 1,
    "read_only_value": "https://example.com/terms",
    "format_rules": { "urlDisplayText": "Consulter les Conditions Générales" }
  }
}

{
  "field": {
    "type": "url",
    "position": { "x": 100, "y": 200, "width": 150, "height": 30 },
    "page_number": 1,
    "read_only_value": "https://example.com/terms",
    "format_rules": { "urlDisplayText": "Consulter les Conditions Générales" }
  }
}

{
  "field": {
    "type": "url",
    "position": { "x": 100, "y": 200, "width": 150, "height": 30 },
    "page_number": 1,
    "read_only_value": "https://example.com/terms",
    "format_rules": { "urlDisplayText": "Consulter les Conditions Générales" }
  }
}

Cas d'usage : Conditions et politiques intégrées. Si votre processus de signature exige que les signataires acceptent des conditions d'utilisation, des politiques de confidentialité ou des contrats externes, le type de champ url permet de tout conserver dans un seul document. Les signataires cliquent sur le lien, consultent le contenu référencé et poursuivent la signature. Pas besoin de joindre plusieurs PDF ou de rediriger les signataires vers des pages externes avant qu'ils ne puissent terminer le processus.

C'est particulièrement utile pour les plateformes SaaS où les conditions changent fréquemment. Mettez à jour l'URL liée une seule fois, et chaque nouvelle demande de signature pointera vers la version actuelle.

Le type de champ textarea

Le type de champ textarea prend en charge la saisie de texte multiligne. Utilisez-le lorsque vous avez besoin que les signataires fournissent des réponses plus longues : instructions spéciales, notes de livraison ou tout texte libre qui ne tiendrait pas dans un champ text d'une seule ligne.

Opérations PATCH pour les champs individuels

Auparavant, la mise à jour d'un seul champ sur un modèle nécessitait l'envoi de l'intégralité de la charge utile du modèle ou l'utilisation du point de terminaison PUT global. Désormais, les points de terminaison PATCH de modèle et de demande de signature prennent en charge les opérations sur un seul champ.

Le PATCH de modèle (PATCH /templates/{id}) peut mettre à jour :

• Les propriétés du modèle

• Un utilisateur unique

• Un champ unique (nouveau dans la v1.4)

Le PATCH de demande de signature (PATCH /signing-requests/{id}) peut mettre à jour :

• Les propriétés de la demande de signature

• Un destinataire unique

• Un champ unique (nouveau dans la v1.4)

Pour créer un nouveau champ, incluez l'objet field sans id :

{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}

{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}

{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}

Pour mettre à jour un champ existant, incluez l'id du champ (field.id) :

{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}

{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}

{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}

Cette approche granulaire simplifie la gestion des champs lorsque vous devez ajuster la position d'un seul champ, modifier le statut obligatoire d'un champ ou ajouter un nouveau champ sans reconstruire toute la charge utile du modèle.

Correspondance des utilisateurs du modèle avec template_user_id

Lors de la création de demandes de signature à partir de modèles, vous pouvez désormais utiliser template_user_id pour faire correspondre explicitement les destinataires aux utilisateurs du modèle :

{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}

{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}

{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}

Avant la version 1.4, la correspondance des destinataires reposait sur la propriété order. Cela fonctionne toujours comme solution de repli, mais template_user_id élimine toute ambiguïté. Si votre modèle comporte plusieurs signataires et que vous souhaitez garantir que Jane reçoive le rôle « Acheteur » (et non le rôle « Vendeur »), la correspondance explicite garantit que la bonne personne reçoive les bons champs.

Changements de schéma de la v1.4

Mise à jour de l'énumération des types de champs de :

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]

À :

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]

Le schéma des destinataires inclut désormais template_user_id pour une correspondance explicite des utilisateurs du modèle lors de la création de demandes de signature.

v1.3.0 : Domaines de messagerie personnalisés et visibilité de l'utilisation

La version 1.3 a introduit l'API Email Domains pour l'envoi d'e-mails en marque blanche, le suivi du coût en crédits pour la visibilité de l'utilisation et la gestion du statut refusé pour les demandes de signature.

API Email Domains

Une catégorie complète d'API pour configurer des domaines de messagerie personnalisés. Au lieu de recevoir les e-mails de demande de signature de la part de noreply@firma.dev, ils peuvent provenir de signing@yourbrand.com.

Huit nouveaux points de terminaison :

Nouveaux schémas :

• Domain : Configuration du domaine de messagerie avec statut de vérification

• DomainDnsRecord : Détails de l'enregistrement DNS pour la vérification du domaine

Le flux de vérification fonctionne comme la plupart des configurations de domaine de messagerie : ajoutez votre domaine, vérifiez-en la propriété avec un enregistrement TXT, configurez SPF/DKIM/DMARC, finalisez avec le fournisseur de messagerie et définissez votre domaine d'envoi principal.

Cas d'usage : E-mails de signature en marque blanche. Si vous créez une intégration d'API de signature électronique pour votre produit SaaS, vos clients s'attendent à ce que les e-mails proviennent de votre marque. Un e-mail de demande de signature émanant de contracts@yourplatform.com renforce la confiance. Un e-mail provenant de noreply@firma.dev suscite des interrogations.

Les domaines de messagerie personnalisés s'associent parfaitement aux Workspaces client pour des déploiements complets en marque blanche. Chacun de vos clients bénéficie d'un espace de travail isolé avec des modèles et des demandes de signature qui ne font jamais référence à Firma.dev dans l'expérience du signataire.

Pour un aperçu plus détaillé des options de marque blanche, consultez nos guides sur l'API de signature de documents en marque blanche et les e-mails de signature électronique en marque blanche.

Suivi du coût en crédits

Deux nouveaux champs offrent une visibilité sur l'utilisation des crédits :

• credit_cost sur le schéma Template : Nombre de crédits consommés lors de l'envoi d'une demande de signature à partir de ce modèle

• credit_cost sur le schéma SigningRequest : Crédits consommés lors de l'envoi de cette demande de signature

Un nouveau paramètre d'espace de travail, show_credit_cost_in_editor, vous permet d'activer ou de désactiver l'affichage des coûts en crédits dans les éditeurs intégrés de modèles et de signatures.

Ceci est important pour les plateformes SaaS qui répercutent les coûts sur leurs clients ou qui doivent suivre l'utilisation par espace de travail. Grâce au coût en crédits visible au niveau du modèle et de la demande de signature, vous pouvez créer des tableaux de bord de facturation, définir des alertes d'utilisation ou présenter à vos clients leur consommation sans avoir à interroger des points de terminaison d'analyse distincts.

À 0,049 € par enveloppe, les coûts restent prévisibles. Mais la visibilité sur la destination de ces crédits vous aide à optimiser votre budget.

Statut refusé pour les demandes de signature

Les demandes de signature prennent désormais en charge le statut declined (refusé) :

• Ajout de declined aux valeurs de l'énumération SigningRequest.status

• Ajout du champ date_declined au schéma SigningRequest

Lorsqu'un signataire refuse de signer, vous le verrez reflété dans le statut et l'horodatage. Cela complète les champs declined_on et decline_reason sur SigningRequestUser qui ont été livrés dans la v1.2.

Améliorations du schéma de la v1.3

Champs de modèle :

• Ajout du champ date_default pour définir des valeurs de date par défaut (format ISO 8601)

• Amélioration de la description de multi_group_id pour expliquer le regroupement de champs mutuellement exclusifs pour les cases à cocher et les boutons radio

• Clarification du fait que page_number utilise un index commençant à 1 et ne doit pas dépasser le nombre de pages du document

Champs de demande de signature :

• Mêmes améliorations de multi_group_id que pour les champs de modèle

Notes de migration

Ni la v1.3 ni la v1.4 n'introduisent de changements perturbateurs.

Migration de la v1.2 à la v1.3 :

• La configuration du domaine de messagerie est disponible mais facultative

• Statut declined ajouté à l'énumération des statuts des demandes de signature

• Suivi du coût en crédits disponible sur les modèles et les demandes de signature

Migration de la v1.3 à la v1.4 :

• Le type de champ radio a été renommé en radio_buttons (tous deux acceptés pour la compatibilité ascendante)

• Nouvelles fonctionnalités PATCH pour les mises à jour de champs granulaires

• template_user_id disponible pour une correspondance explicite des destinataires

Vous pouvez adopter ces fonctionnalités de manière progressive. Les intégrations existantes continuent de fonctionner sans modification.

Créez votre intégration d'API de signature électronique

irma.dev est conçu pour les développeurs qui ont besoin d'ajouter la signature de documents à leurs produits sans la lourdeur des contrats d'entreprise ou des intégrations complexes. Tarification à l'usage à 0,049 € par enveloppe. Sans minimum requis. Sans engagement.

Ces versions reflètent ce que nous demandent nos clients : plus de flexibilité au niveau des champs, une meilleure personnalisation en marque blanche et un contrôle granulaire des modèles et des demandes de signature.

Consultez le journal des modifications complet de l'API pour connaître l'historique des versions et les guides de migration. Ou commencez à développer dès maintenant.

Commencez à utiliser Firma.dev gratuitement — aucune carte de crédit requise.