Prérequis
- Un compte Firma avec une clé API
- Un compte v0 avec un projet actif (le niveau gratuit convient)
- Au moins un modèle Firma avec des champs de signature configurés
Firma utilise la clé API brute comme valeur de l’en-tête
Authorization : ne la préfixez pas avec Bearer. Cela diffère de nombreuses autres API.Étape 1 : Stocker votre clé API en tant que variable d’environnement
v0 gère les variables d’environnement via le panneau Vars dans la barre latérale du chat. Les valeurs sont synchronisées avec le projet Vercel connecté, de sorte que le même secret fonctionne à la fois en aperçu et en production.- Ouvrez votre projet v0 et cliquez sur l’onglet Vars dans la barre latérale
- Cliquez sur Add Variable
- Définissez la clé sur
FIRMA_API_KEYet collez votre clé API Firma comme valeur - Enregistrez
process.env.FIRMA_API_KEY dans tout code côté serveur généré par v0.
Étape 2 : Créer un gestionnaire de route pour envoyer des demandes de signature
Demandez à v0 de créer un gestionnaire de route, ou ajoutez le fichier directement. v0 génère par défaut du code Next.js App Router, donc les gestionnaires de route se trouvent dansapp/api/<route-name>/route.ts.
Cet exemple crée et envoie une demande de signature à partir d’un modèle en un seul appel, via l’endpoint create-and-send :
L’endpoint
create-and-send crée la demande de signature et l’envoie aux destinataires de manière atomique. Si vous devez examiner ou modifier la demande avant de l’envoyer, utilisez POST /signing-requests pour créer un brouillon, puis POST /signing-requests/{id}/send séparément.Étape 3 : Appeler le gestionnaire de route depuis votre interface
Depuis un composant client, envoyez une requête POST vers votre nouvelle route lorsque l’utilisateur termine le formulaire :/api/send-signing-request avec l’ID du modèle, l’email du signataire, son prénom et son nom depuis le formulaire. » v0 générera le formulaire, le bouton et l’appel fetch ensemble.
Intégration des webhooks
Pour suivre le moment où les documents sont signés, ajoutez un gestionnaire de route pour les webhooks et enregistrez-le dans le tableau de bord Firma.- Publiez votre application (voir ci-dessous) afin que la route soit accessible publiquement
- Dans le tableau de bord Firma, sous Paramètres → Webhooks, ajoutez un webhook pointant vers
https://<your-app-domain>/api/webhooks/firma - Sélectionnez les événements que vous souhaitez recevoir. Consultez le guide des webhooks pour tous les types d’événements et la vérification de signature
Publication sur Vercel
Les projets v0 se connectent automatiquement à un projet Vercel. Pour mettre votre application en production :- Cliquez sur Publish en haut à droite de l’interface v0, ou connectez un projet Vercel existant depuis Project settings
- Les variables d’environnement définies dans le panneau Vars se synchronisent automatiquement avec Vercel. Pour définir des valeurs différentes par environnement (Production, Preview, Development), modifiez-les sous Project → Settings → Environment Variables dans le tableau de bord Vercel
- Une fois publiée, l’URL de votre webhook sera
https://<project-name>.vercel.app/api/webhooks/firma. Utilisez-la lors de l’enregistrement du webhook dans Firma
Si vous avez besoin d’une clé API Firma différente pour les environnements de preview et de production, définissez
FIRMA_API_KEY par environnement dans le tableau de bord Vercel. Le panneau Vars de v0 écrit dans tous les environnements par défaut.Signature intégrée
Pour les applications où les signataires remplissent les documents directement dans votre interface plutôt que via l’email, Firma propose une expérience de signature intégrable. La réponse decreate-and-send inclut un first_signer.id (le signing_request_user_id) ainsi qu’un first_signer.signing_link prêt à l’emploi. Affichez-le dans une iframe :
Bonus : connexion MCP pour la construction assistée par IA
Firma propose un serveur MCP de documentation auquel le chat de v0 peut se connecter directement. Une fois connecté, v0 consulte la documentation Firma pendant la génération de code afin d’utiliser les bons endpoints, noms de champs et schémas. Pour le configurer :- Dans v0, cliquez sur Add MCP sur le formulaire de prompt ou allez dans Settings → MCP Connections
- Ajoutez un serveur MCP personnalisé avec l’URL :
https://docs.firma.dev/mcp - Enregistrez
abc123 en utilisant l’email du formulaire » généreront du code conforme à l’API Firma actuelle. Il s’agit d’une aide au moment du développement qui n’affecte pas votre application déployée.
Prochaines étapes
- Authentification API — clés API et portée des espaces de travail
- Guide des webhooks — types d’événements, payloads et vérification de signature
- Signature intégrée — expérience de signature intégrée à l’application
- Créer des espaces de travail — configurations multi-tenant pour les applications SaaS
- Guide de configuration complet — parcours d’intégration Firma de bout en bout
- Référence API — documentation complète des endpoints