Firma.dev API v1.6, v1.7 et v1.8 : Diviser des PDF, signatures manuscrites et modèles d'e-mail personnalisés

Trois versions de l'API ont été publiées depuis v1.5, et elles sont toutes rétrocompatibles et s'installent sans modification. Voici les nouveautés et comment les utiliser.

v1.6.0 : téléchargements PDF séparés et nettoyage des types de champs

Publié le 12 février 2026

La fonctionnalité la plus demandée de la v1.6 est le téléchargement de PDF séparés. Auparavant, lorsqu'une demande de signature était finalisée, vous receviez un seul PDF combiné contenant à la fois le document signé et le certificat de piste d'audit. Désormais, vous pouvez les télécharger séparément.

Deux nouveaux champs sont disponibles sur les demandes de signature finalisées :

{
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf"
}

{
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf"
}

{
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf"
}

Les deux URL sont pré-signées et expirent après 1 heure. Si vous avez besoin d'un lien récent, il vous suffit de récupérer à nouveau la demande de signature. C'est particulièrement utile si vous devez stocker le document signé dans un système et la piste d'audit dans un autre, ou si vos utilisateurs finaux n'ont besoin que du PDF signé propre sans les pages du certificat ajoutées.

La v1.6 a également nettoyé la nomenclature des types de champs. L'API accepte désormais à la fois initials et initial, ainsi que textarea et text_area, et les normalise automatiquement. Si votre intégration utilisait déjà les noms d'origine, rien ne casse. Si vous préférez les formes normalisées, elles fonctionnent aussi.

Journal complet des modifications de la v1.6

v1.7.0 : signatures dessinées à la main

Publié le 27 février 2026

Certains flux de travail exigent que les signataires dessinent physiquement leur signature plutôt que de sélectionner une option saisie au clavier ou générée par une police. La v1.7 introduit le paramètre hand_drawn_only pour imposer exactement cela.

Ajoutez-le aux paramètres de votre demande de signature :

{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}

{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}

{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}

Lorsqu'il est activé, l'interface de signature supprime entièrement les options de signature saisies au clavier et basées sur une police. Les signataires doivent dessiner leur signature à la main. Cela est utile dans les secteurs soumis à de fortes exigences de conformité, comme la santé et les services financiers, où les régulateurs ou les auditeurs attendent précisément des signatures manuscrites.

Le paramètre est défini par défaut sur false, donc les demandes de signature existantes ne sont pas affectées.

Cette version a également ajouté des champs de paramètres hérités rétrocompatibles au schéma SigningRequest. Il s'agit de versions basées sur des entiers (0/1) des paramètres booléens, conçues pour les anciennes intégrations qui attendent ce format. Si vous créez quelque chose de nouveau, restez sur l'objet settings. Les champs hérités sont là pour les équipes qui migrent depuis d'anciens systèmes.

Journal complet des modifications de la v1.7

v1.8.0 : API des modèles d'e-mails et prise en charge des langues

Publié le 3 mars 2026

La v1.8 est la plus importante des trois. La fonctionnalité phare est l'API des modèles d'e-mails, qui vous donne un contrôle total sur les e-mails de notification que Firma.dev envoie pendant le processus de signature.

Vous pouvez personnaliser les modèles pour cinq types d'e-mails : signing_invite, next_signer, signing_expired, signing_cancelled et signing_declined. Les modèles prennent en charge des corps HTML avec des variables telles que {{signer_name}}, {{document_name}} et {{signing_link}}.

Voici un exemple rapide :

PUT /workspace/{workspace_id}/email-templates/signing_invite
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please review and sign using this link: {{signing_link}}</p>"
}

PUT /workspace/{workspace_id}/email-templates/signing_invite
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please review and sign using this link: {{signing_link}}</p>"
}

PUT /workspace/{workspace_id}/email-templates/signing_invite
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please review and sign using this link: {{signing_link}}</p>"
}

Les modèles suivent une hiérarchie : les modèles au niveau de l'espace de travail remplacent les modèles au niveau de l'entreprise, qui remplacent les valeurs par défaut intégrées. Cela signifie que vous pouvez définir un modèle à l'échelle de l'entreprise puis le personnaliser pour chaque Espace de travail client dans des scénarios en marque blanche, lorsque chacun de vos clients a besoin de ses propres e-mails de marque.

En plus des modèles personnalisés, la v1.8 ajoute un champ language à la fois à Company et à WorkspaceSettings. Définissez-le sur l'une des sept langues prises en charge (en, es, it, pt, fr, de, el) et les modèles d'e-mails intégrés de Firma.dev utiliseront automatiquement cette langue. Associés aux remplacements au niveau de l'espace de travail, vous pouvez servir les marchés internationaux sans gérer une infrastructure d'e-mails séparée.

Améliorations du schéma

La v1.8 a également livré plusieurs améliorations de schéma dignes d'intérêt :

Le schéma Template inclut désormais en ligne recipients, fields, settings, page_count et expiration_hours lorsque vous récupérez un modèle unique. Cela signifie moins d'appels API pour obtenir une vue complète de la configuration d'un modèle.

Les réponses de demande de signature ont été réparties en formes spécifiques à chaque point de terminaison (SigningRequestListItem, SigningRequestCreateResponse, SigningRequestDetail) avec des données en ligne et des champs d'horodatage standardisés. Cela rend les réponses plus prévisibles et plus faciles à typer dans votre base de code.

Les webhooks ont gagné trois nouveaux champs : description, consecutive_failures et auto_disabled_at. Les champs de suivi des échecs sont particulièrement pratiques pour la supervision. Si un webhook commence à échouer, vous pouvez désormais voir combien d'échecs consécutifs se sont produits et si Firma.dev l'a désactivé automatiquement.

Notez que la v1.8 a également corrigé plusieurs noms de champs dans la spécification OpenAPI afin de les faire correspondre aux réponses réelles de l'API. Si votre intégration gère déjà les vrais champs de réponse (ce qu'elle fait presque certainement), aucune modification n'est nécessaire.

Journal complet des modifications de la v1.8

Mise à niveau

Les trois versions sont entièrement rétrocompatibles. Aucun changement incompatible, aucune étape de migration requise. Vous pouvez faire passer la version de votre API de v1.5 directement à v1.8 et tout continuera de fonctionner comme avant, avec les nouvelles fonctionnalités disponibles immédiatement.

Pour le journal complet des modifications, avec chaque changement de schéma et chaque note de migration, consultez le Journal des modifications de l'API dans la documentation. Si vous débutez avec Firma.dev, vous pouvez obtenir gratuitement votre clé API et commencer à construire dès aujourd'hui.

Notes de version précédentes : v1.5 | v1.3 et v1.4