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

Nous avons expédié deux versions API consécutives, juste la semaine dernière. Rien de cassé, mais de nouvelles fonctionnalités… le tout en février 2026. 👊

La version 1.3 est arrivée avec des domaines d'email personnalisés et le suivi des coûts de crédit. La version 1.4 a suivi avec trois nouveaux types de champs et des opérations PATCH granulaires pour les 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 incompatibles, donc vous pouvez 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, c'est à quoi cela ressemble.

Voici toutes les nouveautés 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 comment vous les mettez à 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 l'appariement des destinataires explicite.

Trois Nouveaux Types de Champs

Le type d'énumération des champs inclut désormais textarea, url, et radio_buttons :

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

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": "View Terms & Conditions" }
  }
}

{
  "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": "View Terms & Conditions" }
  }
}

{
  "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": "View Terms & Conditions" }
  }
}

Cas d'utilisation : Termes et politiques intégrés. Si votre flux de signature exige que les signataires reconnaissent les termes de service, les politiques de confidentialité, ou les contrats externes, le type de champ url garde tout dans un seul document. Les signataires cliquent sur le lien, examinent le contenu référencé, et continuent de signer. Pas besoin de joindre plusieurs PDF ou de rediriger les signataires vers des pages externes avant qu'ils ne puissent compléter le workflow.

C'est particulièrement utile pour les plateformes SaaS où les termes changent fréquemment. Mettez à jour l'URL liée une 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 sur plusieurs lignes. 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 tiendra pas dans un champ text sur une seule ligne.

Opérations PATCH pour les Champs Individuels

Auparavant, la mise à jour d'un seul champ sur un modèle signifiait envoyer la charge utile complète du modèle 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.

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

• Propriétés du modèle

• Un seul utilisateur

• Un seul champ (nouveau dans v1.4)

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

• 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 le 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 champ unique, changer le statut obligatoire d'un champ, ou ajouter un nouveau champ sans reconstruire la charge utile complète du modèle.

Appariement des Utilisateurs de Modèle avec template_user_id

Lors de la création de demandes de signature à partir de modèles, vous pouvez maintenant utiliser template_user_id pour apparier explicitement les destinataires aux utilisateurs de 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 v1.4, l'appariement des destinataires reposait sur la propriété order. Cela fonctionne toujours comme un secours, mais template_user_id supprime l'ambiguïté. Si votre modèle comporte plusieurs signataires et que vous voulez garantir que Jane obtient le rôle "Acheteur" (et non le rôle "Vendeur"), l'appariement explicite garantit que la bonne personne reçoit 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 maintenant template_user_id pour l'appariement explicite des utilisateurs de modèle lors de la création de demandes de signature.

v1.3.0: Domaines de Mail Personnalisés et Visibilité de l'Utilisation

La version 1.3 a introduit l'API des Domaines de Mail pour l'envoi d'emails à marque blanche, le suivi des coûts de crédit pour la visibilité de l'utilisation, et la gestion du statut de refus pour les demandes de signature.

API des Domaines de Mail

Une catégorie API complète pour configurer des domaines de mail personnalisés. Au lieu que les emails 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 de mail avec le 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 domaines de mail : ajoutez votre domaine, vérifiez la propriété avec un enregistrement TXT, configurez SPF/DKIM/DMARC, finalisez avec le fournisseur de mail, et définissez votre domaine d'envoi principal.

Cas d'utilisation : Emails de signature à marque blanche. Si vous construisez une intégration API de signature électronique pour votre produit SaaS, vos clients s'attendent à ce que les emails proviennent de votre marque. Un email de demande de signature de contracts@yourplatform.com construit la confiance. Un email de noreply@firma.dev suscite des questions.

Les domaines de mail personnalisés s'associent bien avec les Espaces de Travail Client pour des déploiements à marque blanche complets. Chacun de vos clients obtient 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 approfondi des options de marque blanche, consultez nos guides sur API de signature de document à marque blanche et emails de signature électronique à marque blanche.

Suivi des Coûts de Crédit

Deux nouveaux champs fournissent 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 depuis ce modèle

• credit_cost sur le schéma SigningRequest : Crédits consommés lorsque cette demande de signature a été envoyée

Un nouveau paramètre d'espace de travail, show_credit_cost_in_editor, vous permet de basculer si les coûts de crédit s'affichent dans les éditeurs intégrés de modèles et de signatures.

Cela est important pour les plateformes SaaS qui répercutent les coûts sur les clients ou qui ont besoin de suivre l'utilisation par espace de travail. Avec le coût de crédit visible au niveau du modèle et de la demande de signature, vous pouvez construire des tableaux de bord de facturation, définir des alertes d'utilisation, ou montrer à vos clients leur consommation sans interroger des points de terminaison d'analyse distincts.

À €0.029 par enveloppe, les coûts restent prévisibles. Mais la visibilité sur l'endroit où ces crédits vont vous aide à optimiser.

Statut de Refus de Demande de Signature

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

• Ajout de declined aux valeurs enum de 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 qui ont été introduits dans v1.2.

Améliorations du Schéma v1.3

Champs Template :

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

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

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

Champs de demande de signature :

• Les mêmes améliorations multi_group_id que les champs de modèle

Notes de Migration

Ni v1.3 ni v1.4 n'introduisent de changements de rupture.

Migration de v1.2 à v1.3 :

• La configuration du domaine de mail est disponible mais facultative

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

• Suivi des coûts de crédit disponible sur les modèles et les demandes de signature

Migration de v1.3 à v1.4 :

• Le type de champ radio renommé en radio_buttons (les deux acceptés pour la rétrocompatibilité)

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

• template_user_id disponible pour l'appariement explicite des destinataires

Vous pouvez adopter ces fonctionnalités progressivement. Les intégrations existantes continuent de fonctionner sans modification.

Construisez Votre Intégration API de Signature Électronique

Firma.dev est conçu pour les développeurs qui ont besoin d'ajouter la signature de documents à leurs produits sans le surcoût des contrats d'entreprise ou des intégrations complexes. Tarification à l'utilisation à 0,029 € par enveloppe. Aucun minimum. Aucun contrat.

Ces versions reflètent ce que nous entendons de nos clients : plus de flexibilité des champs, un meilleur marquage blanc, et un contrôle granulaire sur les modèles et les 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 maintenant.

Commencez avec Firma.dev gratuitement - aucune carte de crédit requise.