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 de l'API consécutivement, juste la semaine dernière. Rien de cassant, mais de nouvelles fonctionnalités... tout ça en février 2026. 👊

La version 1.3 est arrivée avec des domaines de messagerie 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 cassants, vous pouvez donc adopter ces fonctionnalités à votre propre rythme.

Si vous cherchez une solution de signature d'api qui vous offre de la flexibilité sans vous contraindre à des migrations, c'est ce à 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 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

L'énumération des types de champs inclut maintenant 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 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 nécessite que les signataires reconnaissent les conditions 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 la signature. Pas besoin d'attacher 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 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 l'entrée de texte multi-lignes. Utilisez-le lorsque vous avez besoin que les signataires fournissent des réponses plus longues : instructions spéciales, notes de livraison, ou n'importe quel texte libre qui ne tiendrait pas en une seule ligne de champ text.

Opérations PATCH pour les champs individuels

Auparavant, mettre à jour 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 du modèle et de la demande de signature prennent en charge les opérations à champ unique.

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

• Les propriétés du modèle

• Un seul utilisateur

• Un seul champ (nouveau dans v1.4)

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

Correspondance des utilisateurs de 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 en tant que solution de repli, maistemplate_user_id supprime l’ambiguïté. Si votre modèle comporte plusieurs signataires et que vous souhaitez garantir que Jane obtienne le rôle « Acheteur » (pas le rôle « Vendeur »), l'appariement explicite garantit que la bonne personne obtient les bons champs.

Changements de schéma de 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 la correspondance explicite des utilisateurs de modèles 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 des domaines de messagerie pour l'envoi d'e-mails en marque blanche, le suivi des coûts de crédit pour la visibilité de l'utilisation et la gestion du statut refusé pour les demandes de signature.

API des domaines de messagerie

Une catégorie complète d'API pour configurer des domaines de messagerie 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 de messagerie 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 pour la plupart des configurations de domaine de messagerie : ajoutez votre domaine, vérifiez 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’utilisation : E-mails de signature en marque blanche. Si vous construisez 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 venant de contracts@yourplatform.com inspire confiance. Un e-mail de noreply@Firma.dev soulève des questions.

Les domaines de messagerie personnalisés s’associent bien avec Espaces de travail client pour des déploiements en marque blanche complets. Chacun de vos clients obtient un espace de travail isolé avec des modèles et des demandes de signature qui ne référencent jamais Firma.dev dans l'expérience signataire.

Pour un examen plus approfondi des options de marque blanche, consultez nos guides sur l'API de signature de document en marque blanche et les e-mails de signature électronique en marque blanche.

Suivi des coûts de crédit

Deux nouveaux champs fournissent une visibilité sur l’utilisation du crédit :

• 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 lorsque cette demande de signature a été envoyée

Une nouvelle option de configuration d’espace de travail, show_credit_cost_in_editor, vous permet d’activer ou de désactiver l’affichage des coûts de crédit dans les éditeurs de modèles et de signatures intégrés.

Ceci 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 du crédit 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 montrer aux clients leur consommation sans interroger des points de terminaison d'analytique séparés.

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

Statut refusé de la demande de signature

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

• Ajout de declined aux valeurs énumérées de SigningRequest.status

• Ajout du champ date_declined au schéma SigningRequest

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

Améliorations du schéma v1.3

Champs de modèle :

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

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

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

Champs de demande de signature :

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

Notes de migration

Ni la version 1.3 ni la version 1.4 n'introduisent de changements cassants.

Migration de v1.2 à v1.3 :

• La configuration du domaine de messagerie est disponible mais optionnelle

• Statut declined ajouté à l'énumération des statuts des demandes 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 compatibilité ascendante)

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

• template_user_id disponible pour la correspondance explicite des destinataires

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

Construisez votre intégration d'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 les contraintes des contrats d'entreprise ou des intégrations complexes. Tarification à l'utilisation à $0.029 par enveloppe. Aucun minimum. Pas de contrats.

Ces versions reflètent ce que nous entendons des clients : plus de flexibilité de champ, meilleur marquage blanc, et contrôle granulaire des modèles et des demandes de signature.

Consultez le changelog complet de l'API pour l'historique des versions et les guides de migration. Ou commencez à construire maintenant.

Commencez avec Firma.dev gratuitement—pas de carte de crédit requise.