GitHub Copilot est doué pour écrire du code qui semble correct. C'est lors de l'écriture du code d'intégration que cela devient un problème. Demandez-lui d'intégrer une API de signature électronique et il inventera avec assurance un point de terminaison, devinera la structure des données transmises ou ajoutera un préfixe Bearer que votre fournisseur n'utilise pas. Vous finissez par déboguer l'assistant au lieu de livrer la fonctionnalité.
La solution consiste à fournir à Copilot le véritable contrat de l'API pendant qu'il travaille. Firma.dev propose un serveur Docs MCP ainsi qu'un ensemble de conventions de dépôt qui, ensemble, permettent à Copilot de générer un code d'intégration correct dès le premier coup. Comme Firma.dev est une plateforme de signature électronique conçue comme une API facturée 0,049 € par enveloppe (~5¢ USD) sans abonnement par utilisateur ni minimum de facturation, l'intégration elle-même reste légère. L'objectif est de laisser Copilot écrire cette petite intégration correctement au lieu de la rendre simplement vraisemblable.
Cela comprend trois étapes de configuration : connecter le Docs MCP, ajouter un fichier d'instructions pour l'ensemble du dépôt et fournir à Copilot les modèles de référence à reproduire.
Étape 1 : connecter le Docs MCP de Firma.dev
Le serveur Docs MCP expose l'intégralité de la documentation de Firma.dev sous forme d'outils interrogeables. Une fois connecté, Copilot interroge de vrais points de terminaison, les structures de requêtes actuelles et les schémas de données des webhooks au lieu de deviner. Il est en lecture seule et non authentifié, vous ne lui transmettez donc jamais de clé API.
Dans VS Code, ajoutez-le au niveau de l'espace de travail dans .vscode/mcp.json :
{
"servers": {
"firma-docs": {
"type": "http",
"url": "https://docs.firma.dev/mcp"
}
}
}{
"servers": {
"firma-docs": {
"type": "http",
"url": "https://docs.firma.dev/mcp"
}
}
}{
"servers": {
"firma-docs": {
"type": "http",
"url": "https://docs.firma.dev/mcp"
}
}
}Rechargez la fenêtre et confirmez que firma-docs apparaît dans le sélecteur d'outils de Copilot Chat. Pour le CLI de Copilot, ajoutez le même serveur dans ~/.copilot/mcp-config.json et redémarrez. Dans JetBrains ou Visual Studio, ouvrez **Paramètres → Copilot → Serveurs MCP** et ajoutez un serveur HTTP nommé firma-docs avec l'URL https://docs.firma.dev/mcp.
Étape 2 : ajouter un fichier d'instructions Copilot pour tout le dépôt
Le fichier .github/copilot-instructions.md est chargé automatiquement par Copilot Chat, l'agent de développement, ainsi que lors des revues de code sur tous les environnements pris en charge. C'est ici que vous définissez les conventions qui maintiennent le code généré en conformité avec le contrat de l'API. Créez ou complétez le fichier :
## Intégration de la signature électronique Firma.dev
Lors de la génération de code qui envoie, reçoit ou intègre des signatures électroniques Firma, respectez ces conventions :
- URL de base de l'API : `https://api.firma.dev/functions/v1/signing-request-api`
- Authentification : en-tête `Authorization` défini par la clé API brute Firma (sans préfixe `Bearer`)
- La clé réside dans `FIRMA_API_KEY` sous forme de variable d'environnement. Appelez Firma uniquement depuis le backend, jamais depuis le navigateur. Ne commitez jamais sa valeur.
- Utilisez par défaut `POST /signing-requests/create-and-send` lors de l'envoi à partir d'un modèle. Utilisez le flux en deux étapes `POST /signing-requests` puis `POST /signing-requests/{id}/send` uniquement lorsque l'utilisateur a besoin de vérifier le brouillon avant l'envoi.
- Structure de l'objet destinataire : `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- Pour les gestionnaires de webhooks, effectuez un embranchement sur `payload.type` (ex. `signing_request.completed`). L'objet de la demande de signature se trouve dans `payload.data.signing_request`.
- Pour l'intégration de signature (embedded), utilisez un iframe pointant vers `https://app.firma.dev/signing/{signing_request_user_id}` avec `allow="camera;microphone;clipboard-write"`.
- En cas de doute sur un point de terminaison ou sur la structure d'un champ, utilisez le serveur MCP `firma-docs`. Ne devinez pas.## Intégration de la signature électronique Firma.dev
Lors de la génération de code qui envoie, reçoit ou intègre des signatures électroniques Firma, respectez ces conventions :
- URL de base de l'API : `https://api.firma.dev/functions/v1/signing-request-api`
- Authentification : en-tête `Authorization` défini par la clé API brute Firma (sans préfixe `Bearer`)
- La clé réside dans `FIRMA_API_KEY` sous forme de variable d'environnement. Appelez Firma uniquement depuis le backend, jamais depuis le navigateur. Ne commitez jamais sa valeur.
- Utilisez par défaut `POST /signing-requests/create-and-send` lors de l'envoi à partir d'un modèle. Utilisez le flux en deux étapes `POST /signing-requests` puis `POST /signing-requests/{id}/send` uniquement lorsque l'utilisateur a besoin de vérifier le brouillon avant l'envoi.
- Structure de l'objet destinataire : `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- Pour les gestionnaires de webhooks, effectuez un embranchement sur `payload.type` (ex. `signing_request.completed`). L'objet de la demande de signature se trouve dans `payload.data.signing_request`.
- Pour l'intégration de signature (embedded), utilisez un iframe pointant vers `https://app.firma.dev/signing/{signing_request_user_id}` avec `allow="camera;microphone;clipboard-write"`.
- En cas de doute sur un point de terminaison ou sur la structure d'un champ, utilisez le serveur MCP `firma-docs`. Ne devinez pas.## Intégration de la signature électronique Firma.dev
Lors de la génération de code qui envoie, reçoit ou intègre des signatures électroniques Firma, respectez ces conventions :
- URL de base de l'API : `https://api.firma.dev/functions/v1/signing-request-api`
- Authentification : en-tête `Authorization` défini par la clé API brute Firma (sans préfixe `Bearer`)
- La clé réside dans `FIRMA_API_KEY` sous forme de variable d'environnement. Appelez Firma uniquement depuis le backend, jamais depuis le navigateur. Ne commitez jamais sa valeur.
- Utilisez par défaut `POST /signing-requests/create-and-send` lors de l'envoi à partir d'un modèle. Utilisez le flux en deux étapes `POST /signing-requests` puis `POST /signing-requests/{id}/send` uniquement lorsque l'utilisateur a besoin de vérifier le brouillon avant l'envoi.
- Structure de l'objet destinataire : `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- Pour les gestionnaires de webhooks, effectuez un embranchement sur `payload.type` (ex. `signing_request.completed`). L'objet de la demande de signature se trouve dans `payload.data.signing_request`.
- Pour l'intégration de signature (embedded), utilisez un iframe pointant vers `https://app.firma.dev/signing/{signing_request_user_id}` avec `allow="camera;microphone;clipboard-write"`.
- En cas de doute sur un point de terminaison ou sur la structure d'un champ, utilisez le serveur MCP `firma-docs`. Ne devinez pas.Committez-le. Dès lors, une invite telle que *« ajouter une demande de signature Firma.dev lorsque l'utilisateur clique sur Envoyer le contrat »* démarrera avec les bonnes valeurs par défaut déjà intégrées. Si votre dépôt possède une séparation claire pour le backend, vous pouvez ajouter un fichier spécifique au chemin dans .github/instructions/firma.instructions.md avec un glob applyTo afin que les règles ne se chargent que lorsque Copilot modifie le code de votre serveur, ce qui permet de garder le fichier global court.
Étape 3 : fournir à Copilot les modèles de référence
Copilot écrit dans le langage qui correspond aux fichiers environnants. Les structures ci-dessous représentent les appels canoniques à Firma.dev. Le fichier d'instructions guide Copilot vers ceux-ci et le MCP se charge de compléter les détails actuels.
Créer et envoyer en TypeScript :
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
export async function sendForSignature(opts: {
templateId: string;
signer: { firstName: string; lastName: string; email: string };
}) {
const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
method: "POST",
headers: {
Authorization: process.env.FIRMA_API_KEY!,
"Content-Type": "application/json",
},
body: JSON.stringify({
template_id: opts.templateId,
recipients: [
{
first_name: opts.signer.firstName,
last_name: opts.signer.lastName,
email: opts.signer.email,
designation: "Signer",
order: 1,
},
],
}),
});
if (!res.ok) throw new Error(`Firma error: ${res.status}`);
return res.json();
}const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
export async function sendForSignature(opts: {
templateId: string;
signer: { firstName: string; lastName: string; email: string };
}) {
const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
method: "POST",
headers: {
Authorization: process.env.FIRMA_API_KEY!,
"Content-Type": "application/json",
},
body: JSON.stringify({
template_id: opts.templateId,
recipients: [
{
first_name: opts.signer.firstName,
last_name: opts.signer.lastName,
email: opts.signer.email,
designation: "Signer",
order: 1,
},
],
}),
});
if (!res.ok) throw new Error(`Firma error: ${res.status}`);
return res.json();
}const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
export async function sendForSignature(opts: {
templateId: string;
signer: { firstName: string; lastName: string; email: string };
}) {
const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
method: "POST",
headers: {
Authorization: process.env.FIRMA_API_KEY!,
"Content-Type": "application/json",
},
body: JSON.stringify({
template_id: opts.templateId,
recipients: [
{
first_name: opts.signer.firstName,
last_name: opts.signer.lastName,
email: opts.signer.email,
designation: "Signer",
order: 1,
},
],
}),
});
if (!res.ok) throw new Error(`Firma error: ${res.status}`);
return res.json();
}Un gestionnaire de webhooks effectue un embranchement selon le type d'événement et récupère la demande de signature depuis data :
export async function POST(req: Request) {
const payload = await req.json();
const { type, data } = payload;
if (type === "signing_request.completed") {
const signingRequestId = data.signing_request.id;
}
return new Response(JSON.stringify({ received: true }), { status: 200 });
}export async function POST(req: Request) {
const payload = await req.json();
const { type, data } = payload;
if (type === "signing_request.completed") {
const signingRequestId = data.signing_request.id;
}
return new Response(JSON.stringify({ received: true }), { status: 200 });
}export async function POST(req: Request) {
const payload = await req.json();
const { type, data } = payload;
if (type === "signing_request.completed") {
const signingRequestId = data.signing_request.id;
}
return new Response(JSON.stringify({ received: true }), { status: 200 });
}Avec ces structures de référence présentes dans le dépôt, Copilot dispose d'une base concrète sur laquelle s'appuyer plutôt que de devoir improviser à partir d'une page blanche.
Bonus : l'agent de développement Copilot
Si votre dépôt est configuré pour l'agent de développement Copilot, le même fichier .github/copilot-instructions.md s'applique. Une fois le MCP et les instructions en place, un ticket comme *« Ajouter un bouton Envoyer le contrat qui envoie une demande de signature Firma.dev à partir du modèle tmpl_abc123 »* se transforme en une pull request (PR) qui configure la variable d'environnement, le gestionnaire backend, la route du webhook et le bouton de l'interface utilisateur, sans nécessiter beaucoup d'accompagnement. Demandez-lui d'indiquer l'URL du webhook et l'identifiant du modèle sous forme de commentaires TODO dans la description de la PR afin que la personne chargée de la revue puisse enregistrer le webhook avant la fusion. Même avec une automatisation aussi efficace, il reste indispensable qu'un humain reçoive et vérifie cette PR avant son déploiement.
📘 Lire le guide d'intégration complet de GitHub Copilot
Tous les fichiers de configuration, les règles spécifiques aux fichiers et les structures de référence sont disponibles dans la documentation : https://docs.firma.dev/guides/github-copilot-integration
Démarrer
Connectez le MCP, ajoutez le fichier d'instructions, et Copilot cessera d'improviser pour votre intégration. Commencez à utiliser Firma.dev gratuitement, sans carte de crédit requise, et laissez votre assistant écrire correctement votre code de signature électronique dès la première fois.
