Guide de configuration complet

Comment intégrer des signatures électroniques intégrées dans votre application : guide étape par étape pour configurer les espaces de travail, modèles, demandes de signature et signature intégrée de Firma.dev

Que vous construisiez pour un seul cas d’usage interne ou que vous vouliez évoluer sur des milliers de clients dans un produit SaaS, Firma offre la flexibilité et la tarification nécessaires pour avancer rapidement.

Introduction

Firma.dev est une API légère, pensée pour les développeurs, qui facilite l’intégration des signatures électroniques dans votre application. Elle convient particulièrement bien aux plateformes SaaS qui doivent prendre en charge des modèles et des flux de signature spécifiques à chaque client sans avoir à construire un pipeline documentaire de A à Z.

Pourquoi les développeurs choisissent Firma

Tarification à l’usage à 0,029 € par enveloppe (soit environ 3 centimes de dollar US) - pas d’abonnement, pas de frais cachés
Intégration rapide grâce aux éditeurs de signature et de modèles intégrables
Isolation des espaces de travail pour séparer les modèles et l’utilisation par client
Conformité avec ESIGN, UETA, eIDAS, RGPD, HIPAA, et plus encore

Ce guide vous accompagne de votre première clé API jusqu’à un flux de signature en production, avec des références vers les documents d’implémentation clés et les bonnes pratiques tout au long du parcours.

Prérequis

Avant de commencer, assurez-vous d’avoir les éléments suivants :

Un compte Firma - vous pouvez vous inscrire gratuitement, sans carte bancaire requise.
Un document PDF que vous souhaitez utiliser dans votre flux de signature.
Une bonne connaissance des API REST et des webhooks - la majorité de vos interactions avec Firma se feront via l’API.
Un environnement applicatif où vous pouvez tester des appels API - Node.js ou PHP sont idéaux pour ce guide de démarrage rapide, mais n’importe quel environnement côté serveur conviendra tout aussi bien.

Firma est conçu en tenant compte de la conformité réglementaire. Vous pouvez l’utiliser en toute confiance dans des flux régis par :

ESIGN Act / UETA (États-Unis)
eIDAS SES/AdES (UE/Royaume-Uni)
HIPAA (santé)
RGPD (protection des données personnelles)

Créer votre compte et obtenir votre clé API

Pour commencer à intégrer Firma, vous devrez d’abord créer un compte et accéder à votre clé API :

Rendez-vous sur firma.dev et créez un compte.
Une fois connecté, accédez à votre tableau de bord. Vous y trouverez votre clé API.
Firma propose un environnement unifié avec des enveloppes au prix si bas (seulement 0,029 € chacune) que tester et itérer ne coûte pratiquement rien.

Effectuer des appels API

Vous transmettrez votre clé API via l’en-tête Authorization dans toutes les requêtes :

curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"

Démarrer en mode test

Chaque espace de travail dispose de deux clés API : une clé live et une clé test. Pendant que vous construisez votre intégration, utilisez la clé test - les requêtes authentifiées avec elle ne consomment pas de crédits et produisent des documents marqués comme test et filigranés, ce qui vous permet d’itérer librement. Passez à la clé live lorsque vous êtes prêt pour la production. Les deux clés sont renvoyées lors de la création d’un espace de travail (api_key = live, test_api_key = test) ainsi que par le point de terminaison Get Workspace, et les deux apparaissent dans votre tableau de bord. Consultez Authentification pour savoir comment fonctionne le mode test.

# Mode test — aucun crédit consommé, sortie filigranée
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"

Créer des espaces de travail (pour les applications SaaS ou multi-clients)

Dans Firma, les espaces de travail offrent des environnements isolés pour vos clients. Chaque espace de travail possède son propre :

Modèles
Activité de signature
Indicateurs d’utilisation et de facturation
Clé de sécurité pour un accès API limité

Cela rend les espaces de travail essentiels pour les plateformes SaaS qui gèrent des documents et des flux spécifiques à chaque client. Vous créerez généralement un nouvel espace de travail pour chaque compte client.

Sécurité et isolation des espaces de travail

Chaque espace de travail dans Firma est accompagné de sa propre clé API spécifique à l’espace de travail, utilisée pour restreindre les actions de manière sécurisée à cet espace de travail. Cela garantit que les modèles, demandes de signature et enveloppes créés au sein d’un espace de travail ne peuvent pas se mélanger avec ceux des autres - maintenant ainsi une forte séparation logique entre vos clients.

Créer un espace de travail

Voici comment créer un espace de travail via l’API :

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'

La réponse inclura deux valeurs importantes : id et api_key. Elles correspondent à l’identifiant unique de l’espace de travail et à sa clé de sécurité limitée. Vous utiliserez les deux pour gérer l’activité liée à ce client spécifique. 📘 Guide de création d’espaces de travail 📘 Guide des paramètres d’espace de travail

Créer un modèle

Un modèle définit un flux documentaire réutilisable. Il comprend la structure du document, les rôles des signataires et le placement des champs (comme les zones de signature, les initiales et les dates). C’est particulièrement puissant lorsque vous automatisez des contrats, des accords ou des documents internes. Vous devez commencer avec un fichier PDF statique - c’est la base de votre modèle.

Deux façons de créer des modèles

Option 1 : Éditeur de modèles intégré

L’éditeur de modèles intégré permet à votre équipe interne ou à vos clients de placer visuellement des champs et de configurer les rôles des signataires directement dans votre application. Il est facile à intégrer et élimine le besoin pour les utilisateurs non techniques de définir des mises en page via du code. 📘 Guide de l’éditeur de modèles intégré

Option 2 : Créer via l’API

Si vous développez de manière programmatique, vous pouvez utiliser l’API pour définir des modèles. Vous téléverserez votre document et définirez manuellement les rôles des signataires et les coordonnées des champs. Exemple de création de modèle :

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'

Le champ document accepte un fichier PDF ou DOCX encodé en base64. La réponse renvoie l’ID du modèle, que vous pouvez ensuite utiliser pour ajouter des destinataires et des champs via l’éditeur de modèles ou l’API. 📘 API des modèles

Envoyer une demande de signature

Une demande de signature est la transaction active qui envoie un document à une ou plusieurs personnes pour signature. Elle est toujours liée à un espace de travail et soit à un modèle, soit à un téléversement de document. Vous devrez préciser :

L’ID de l’espace de travail
L’ID du modèle (ou un téléversement de document brut)
Les signataires - chacun avec un nom, un email et un rôle
Facultatif : l’ordre de signature, les métadonnées et l’expiration

Exemple de requête (à partir d’un modèle) :

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'

Vous pouvez également créer des demandes de signature directement à partir d’un document (PDF ou DOCX encodé en base64) au lieu d’un modèle, en passant document à la place de template_id. 📘 Demandes de signature

Utiliser l’éditeur de demandes de signature intégrable

Si vous préférez proposer une interface pour configurer le destinataire du document et la manière dont il est envoyé, plutôt que de construire vous-même la charge utile JSON, vous pouvez intégrer l’éditeur de demandes de signature dans votre produit. Un flux typique ressemble à ceci :

Votre backend crée une demande de signature dans l’espace de travail approprié (souvent à l’état de brouillon) à partir d’un modèle.
Votre backend génère un jeton JWT à courte durée de vie pour cette demande de signature via le point de terminaison JWT de Firma.
Votre frontend charge l’éditeur de demandes de signature intégrable dans une iframe ou une vue dédiée et lui transmet le JWT.
Les informations des signataires (noms, emails, rôles) et les options telles que l’expiration ou le message sont renseignées via l’interface.
Lorsqu’ils cliquent sur Envoyer, Firma met à jour ou envoie la demande de signature, et vous pouvez réagir grâce aux webhooks ou aux événements postMessage.

Cela convient bien pour :

Les équipes internes qui envoient beaucoup de documents mais ne souhaitent pas travailler avec des requêtes API brutes.
Les administrateurs clients dans une application SaaS qui devraient pouvoir gérer eux-mêmes les destinataires sans exposer vos clés API.

📘 Guide de l’éditeur de demandes de signature intégrable

Effectuer la signature (intégrée ou par redirection)

Après la création d’une demande de signature, Firma génère des URL de signature sécurisées pour chaque signataire. Vous pouvez intégrer ces URL directement dans votre produit ou utiliser une simple redirection.

Option 1 : Signature intégrée

Intégrez le flux de signature au sein de votre application pour une expérience fluide. C’est idéal si vous construisez un produit en marque blanche ou totalement intégré. 📘 Guide de la signature intégrée

Option 2 : Signature par redirection

Vous pouvez également rediriger l’utilisateur vers l’interface de signature hébergée par Firma en utilisant l’URL sécurisée renvoyée dans la réponse de la demande de signature. Une fois la signature terminée :

Vous pouvez récupérer le PDF signé via l’API
Accéder à la piste d’audit et aux métadonnées à des fins de conformité

Suivre l’utilisation et vérifier les crédits

Firma utilise un modèle de tarification basé sur les crédits. Chaque enveloppe (un document envoyé pour signature) coûte seulement 0,029 € (soit environ 3 centimes de dollar US). Il n’y a ni abonnement, ni minimum, ni frais surprise.

Vérifier votre solde de crédits actuel

Pour voir combien de crédits il vous reste à tout moment, appelez le point de terminaison Get Company Information en utilisant votre clé API au niveau de l’entreprise :

curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"

La réponse inclut un champ credits, accompagné d’autres informations sur votre entreprise. Par exemple :

{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}

Ici, "credits": 17 signifie que vous pouvez envoyer 17 enveloppes supplémentaires avant de devoir recharger votre compte. Vous pouvez utiliser cette valeur dans vos propres outils d’administration pour afficher les crédits restants à votre équipe ou pour bloquer les nouvelles demandes de signature lorsque le solde est trop bas.

Recharger des crédits

Lorsque vous êtes proche de zéro crédit :

Achetez plus de crédits directement depuis le tableau de bord Firma
Une fois l’achat effectué, votre nouveau solde sera reflété dans le champ credits renvoyé par le point de terminaison d’informations de l’entreprise
Les crédits sont disponibles pour tous vos espaces de travail rattachés à cette entreprise

Vous pouvez interroger périodiquement le point de terminaison de l’entreprise pour surveiller l’utilisation, ou l’intégrer à vos outils de suivi et tableaux de bord internes.

Exemple de flux de bout en bout

Options d’intégration avancées

Éditeur de modèles intégré

Laissez vos utilisateurs créer et gérer leurs propres modèles directement depuis l’interface de votre application. L’éditeur intégré leur donne un contrôle total pour téléverser des documents, placer des champs et définir la logique de signature de manière visuelle. 📘 Guide de l’éditeur de modèles

Webhooks

Les webhooks permettent à votre backend de réagir en temps réel aux événements liés aux documents. Vous recevrez des rappels lorsque :

Un document est consulté
Un signataire termine sa partie
Le document complet est signé et finalisé

C’est idéal pour les flux qui incluent des mises à jour CRM, des notifications par email, des déclencheurs internes ou des audits de conformité. 📘 Guide des webhooks

Bonnes pratiques

Utilisez des noms de rôles de signataires descriptifs et cohérents entre vos modèles
Gardez vos PDF propres - supprimez les éléments dynamiques et évitez le contenu interactif
Prévoyez les nouvelles tentatives de livraison des webhooks - mettez en place l’idempotence si nécessaire
Utilisez des crédits de test pour explorer les flux avant votre lancement
Suivez l’utilisation par espace de travail pour la facturation ou le reporting par client

Consultez le guide sur les Limites de débit.

Et ensuite ?

Vous disposez désormais de tout ce dont vous avez besoin pour mettre en œuvre un flux de signature électronique complet et intégré avec Firma. Ensuite, vous pouvez :

Étendre vos flux avec le multi-signataires ou le routage séquentiel
Appliquer votre marque aux interfaces de signature intégrées
Utiliser les journaux d’audit pour vos besoins de conformité
Construire un tableau de bord de métriques à partir des données d’utilisation par espace de travail

Firma est conçu pour les développeurs qui veulent avancer vite - et évoluer proprement. Commencer maintenant - à 0,029 € par enveloppe, démarrer ne coûte pratiquement rien.

​Comment intégrer des signatures électroniques intégrées dans votre application : guide étape par étape pour configurer les espaces de travail, modèles, demandes de signature et signature intégrée de Firma.dev

​Introduction

​Pourquoi les développeurs choisissent Firma

​Prérequis

​Créer votre compte et obtenir votre clé API

​Effectuer des appels API

​Démarrer en mode test

​Créer des espaces de travail (pour les applications SaaS ou multi-clients)

​Sécurité et isolation des espaces de travail

​Créer un espace de travail

​Créer un modèle

​Deux façons de créer des modèles

​Option 1 : Éditeur de modèles intégré

​Option 2 : Créer via l’API

​Envoyer une demande de signature

​Utiliser l’éditeur de demandes de signature intégrable

​Effectuer la signature (intégrée ou par redirection)

​Option 1 : Signature intégrée

​Option 2 : Signature par redirection

​Suivre l’utilisation et vérifier les crédits

​Vérifier votre solde de crédits actuel

​Recharger des crédits

​Exemple de flux de bout en bout

​Options d’intégration avancées

​Éditeur de modèles intégré

​Webhooks

​Bonnes pratiques

​Et ensuite ?

Comment intégrer des signatures électroniques intégrées dans votre application : guide étape par étape pour configurer les espaces de travail, modèles, demandes de signature et signature intégrée de Firma.dev

Introduction

Pourquoi les développeurs choisissent Firma

Prérequis

Créer votre compte et obtenir votre clé API

Effectuer des appels API

Démarrer en mode test

Créer des espaces de travail (pour les applications SaaS ou multi-clients)

Sécurité et isolation des espaces de travail

Créer un espace de travail

Créer un modèle

Deux façons de créer des modèles

Option 1 : Éditeur de modèles intégré

Option 2 : Créer via l’API

Envoyer une demande de signature

Utiliser l’éditeur de demandes de signature intégrable

Effectuer la signature (intégrée ou par redirection)

Option 1 : Signature intégrée

Option 2 : Signature par redirection

Suivre l’utilisation et vérifier les crédits

Vérifier votre solde de crédits actuel

Recharger des crédits

Exemple de flux de bout en bout

Options d’intégration avancées

Éditeur de modèles intégré

Webhooks

Bonnes pratiques

Et ensuite ?