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

Nous avons publié deux versions d’API coup sur coup, rien que la semaine dernière. Rien de cassant, mais de nouvelles fonctionnalités … le tout en février 2026. 👊

La version 1.3 est arrivée avec des domaines e-mail 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 des champs individuels.

Les deux versions partagent le même thème : plus de contrôle sans plus de complexité. Et aucune n’introduit de changements cassants, vous pouvez donc adopter ces fonctionnalités à votre rythme.

Si vous cherchez une solution d’API de signature qui vous offre de la flexibilité sans imposer de migrations, voici à quoi cela ressemble.

Voici tout ce qui est nouveau dans v1.3 et v1.4.

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

Date de sortie : 31 janvier 2026

La version 1.4 élargit ce que vous pouvez faire avec les champs de document et la façon dont vous les mettez à jour. Trois nouveaux types de champs vous offrent davantage 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 l’association des destinataires explicite.

Trois nouveaux types de champs

L’énumération des types de champs inclut désormais textarea, url et radio_buttons :

Le type radio fonctionne toujours pour la compatibilité ascendante, mais radio_buttons est le nom canonique pour la suite.

Le type de champ url

Le nouveau type de champ url vous permet d’intégrer des liens cliquables directement dans vos documents de signature. Le champ est automatiquement défini sur read_only: true, car 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": "Voir 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": "Voir 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": "Voir les conditions générales" }
  }
}

Cas d’usage : conditions et politiques intégrées. Si votre flux de signature exige que les signataires reconnaissent les conditions générales, les politiques de confidentialité ou des contrats externes, le type de champ url garde tout dans un seul document. Les signataires cliquent sur le lien, consultent le contenu référencé, puis poursuivent la signature. Plus besoin de joindre plusieurs PDF ni de rediriger les signataires vers des pages externes avant qu’ils puissent terminer le workflow.

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 pointe vers la version actuelle.

Le type de champ textarea

Le type de champ textarea prend en charge la saisie de texte multilignes. 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 sur une seule ligne.

Opérations PATCH pour des champs individuels

Auparavant, mettre à jour un seul champ sur un template signifiait envoyer la charge utile complète du template ou utiliser le point de terminaison PUT complet. Désormais, les points de terminaison PATCH de template et de demande de signature prennent en charge les opérations sur un seul champ.

PATCH de template (PATCH /templates/{id}) peut mettre à jour :

• Les propriétés du template

• Un seul utilisateur

• Un seul champ (nouveau dans v1.4)

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

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

• Un seul destinataire

• Un seul champ (nouveau dans 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 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 son statut obligatoire ou ajouter un nouveau champ sans reconstruire toute la charge utile du template.

Correspondance des utilisateurs du template avec template_user_id

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

{
  "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 v1.4, la correspondance des destinataires reposait sur la propriété order. Cela fonctionne toujours en solution de repli, maistemplate_user_id supprime toute ambiguïté. Si votre template comporte plusieurs signataires et que vous voulez garantir que Jane obtienne le rôle « Acheteur » (et non le rôle « Vendeur »), la correspondance explicite garantit que la bonne personne obtient les bons champs.

Modifications du schéma v1.4

Énumération des types de champs mise à jour 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"]

Schéma des destinataires inclut désormais template_user_id pour une correspondance explicite avec les utilisateurs du template lors de la création de demandes de signature.

v1.3.0 : Domaines e-mail personnalisés et visibilité de l’utilisation

La version 1.3 a introduit l’API des domaines e-mail 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 des domaines e-mail

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

Huit nouveaux points de terminaison :

Nouveaux schémas :

• Domain : configuration du domaine e-mail avec statut de vérification

• DomainDnsRecord : détails des enregistrements DNS pour la vérification du domaine

Le flux de vérification fonctionne comme la plupart des configurations de domaines e-mail : ajoutez votre domaine, vérifiez la propriété avec un enregistrement TXT, configurez SPF/DKIM/DMARC, finalisez avec le fournisseur d’e-mail, puis 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 à recevoir des e-mails de votre marque. Un e-mail de demande de signature envoyé depuis contracts@yourplatform.com inspire confiance. Un e-mail provenant de noreply@firma.dev soulève des questions.

Les domaines e-mail personnalisés se marient bien avec Espaces de travail client pour des déploiements complets en marque blanche. Chacun de vos clients obtient un espace de travail isolé avec des templates et des demandes de signature qui ne mentionnent jamais Firma.dev dans l’expérience du signataire.

Pour aller plus loin sur les options de marque blanche, consultez nos guides sur API de signature de documents en marque blanche et 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 dans le schéma Template : nombre de crédits consommés lors de l’envoi d’une demande de signature à partir de ce template

• credit_cost dans le schéma SigningRequest : crédits consommés lors de l’envoi de cette demande de signature

Un nouveau paramètre de workspace, 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 template et de signature.

Cela compte pour les plateformes SaaS qui répercutent les coûts sur leurs clients ou qui doivent suivre l’utilisation par workspace. Avec le coût en crédits visible au niveau du template et de la demande de signature, vous pouvez créer des tableaux de bord de facturation, définir des alertes d’utilisation ou montrer aux clients leur consommation sans interroger des points de terminaison d’analyse distincts.

À 0,029 € par enveloppe, les coûts restent prévisibles. Mais savoir où vont ces crédits vous aide à optimiser.

Statut de refus de la demande de signature

Les demandes de signature prennent désormais en charge un statut declined :

• 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 de SigningRequestUser livrés en v1.2.

Améliorations du schéma v1.3

Champs du template :

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

• Description améliorée de multi_group_id pour expliquer le regroupement mutuellement exclusif des champs pour les cases à cocher et les boutons radio

• Clarification : page_number est indexé à partir de 1 et ne doit pas dépasser le nombre de pages du document

Champs de la demande de signature :

• Mêmes améliorations de multi_group_id que pour les champs du template

Notes de migration

Ni v1.3 ni v1.4 n’introduisent de changements cassants.

Migration de v1.2 vers v1.3 :

• La configuration du domaine e-mail est disponible mais facultative

• Le statut declined est ajouté à l’énumération des statuts de demande de signature

• Le suivi du coût en crédits est disponible sur les templates et les demandes de signature

Migration de v1.3 vers v1.4 :

• Le type de champ radio est renommé en radio_buttons (les deux sont acceptés pour la compatibilité ascendante)

• Nouvelles capacités PATCH pour des mises à jour granulaires des champs

• template_user_id disponible pour une correspondance explicite des destinataires

Vous pouvez adopter ces fonctionnalités progressivement. 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 surcharge de contrats d’entreprise ni d’intégrations complexes. Tarification à l’usage à 0,029 € par enveloppe. Pas de minimum. Pas de contrat.

Ces versions reflètent ce que nous entendons de la part des clients : plus de flexibilité des champs, une meilleure marque blanche et un contrôle granulaire des templates et des demandes de signature.

Consultez le journal complet des modifications de l’API pour l’historique des versions et les guides de migration. Ou commencez à construire dès maintenant.

Commencez avec Firma.dev gratuitement — aucune carte bancaire requise.