GitHub Copilot est doué pour écrire du code qui semble correct. Le code d'intégration est l'endroit où cela devient un problème. Demandez-lui de configurer une API de signature électronique et il inventera en toute confiance un point de terminaison, devinera la forme d'une charge utile ou utilisera 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 à donner à Copilot le véritable contrat d'API pendant qu'il travaille. Firma.dev propose un serveur Docs MCP et 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 passage. Comme Firma.dev est une plateforme de signature électronique conçue pour l'API facturée 0,049 € par enveloppe (~5¢ USD) sans frais par utilisateur ni minimum, l'intégration elle-même est minime. L'objectif est de laisser Copilot écrire cette petite intégration correctement plutôt que de façon plausible.
Cela comprend trois étapes de configuration : connecter le Docs MCP, ajouter un fichier d'instructions à l'échelle du dépôt et donner à Copilot les modèles de référence à suivre.
Étape 1 : connecter le Docs MCP de Firma.dev
Le serveur Docs MCP expose la documentation complète de Firma.dev en tant qu'outils de recherche. Une fois connecté, Copilot interroge de vrais points de terminaison, des structures de requêtes actuelles et des schémas de charge utile de webhook au lieu de deviner. Il est en lecture seule et non authentifié, vous n'avez donc jamais besoin de lui transmettre de clé d'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 la CLI de Copilot, ajoutez le même serveur à ~/.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 à l'échelle du dépôt
.github/copilot-instructions.md est chargé automatiquement par Copilot Chat, l'agent de codage, et la révision de code sur l'ensemble des environnements pris en charge. C'est ici que vous définissez les conventions qui maintiennent le code généré conforme au contrat. 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 avec la clé d'API Firma brute (sans préfixe `Bearer`)
- La clé se trouve dans la variable d'environnement `FIRMA_API_KEY`. Appelez Firma uniquement depuis le backend, jamais depuis le navigateur. Ne committez jamais cette 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 doit réviser 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 branchement sur `payload.type` (par ex. `signing_request.completed`). L'objet de demande de signature se trouve dans `payload.data.signing_request`.
- Pour la signature intégrée, chargez dans un iframe `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 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 avec la clé d'API Firma brute (sans préfixe `Bearer`)
- La clé se trouve dans la variable d'environnement `FIRMA_API_KEY`. Appelez Firma uniquement depuis le backend, jamais depuis le navigateur. Ne committez jamais cette 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 doit réviser 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 branchement sur `payload.type` (par ex. `signing_request.completed`). L'objet de demande de signature se trouve dans `payload.data.signing_request`.
- Pour la signature intégrée, chargez dans un iframe `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 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 avec la clé d'API Firma brute (sans préfixe `Bearer`)
- La clé se trouve dans la variable d'environnement `FIRMA_API_KEY`. Appelez Firma uniquement depuis le backend, jamais depuis le navigateur. Ne committez jamais cette 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 doit réviser 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 branchement sur `payload.type` (par ex. `signing_request.completed`). L'objet de demande de signature se trouve dans `payload.data.signing_request`.
- Pour la signature intégrée, chargez dans un iframe `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 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 configurations par défaut intégrées. Si votre dépôt possède une frontière backend claire, vous pouvez ajouter un fichier spécifique à un chemin sous .github/instructions/firma.instructions.md avec un glob applyTo pour que les règles ne se chargent que lorsque Copilot modifie votre code serveur, ce qui permet de garder le fichier global court.
Étape 3 : donner à Copilot les modèles de référence
Copilot écrit dans le langage qui correspond aux fichiers environnants. Les structures ci-dessous sont les appels Firma.dev canoniques. Le fichier d'instructions guide Copilot vers ceux-ci et le MCP complète 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 webhook effectue un branchement sur le type d'événement et lit la demande de signature à partir de 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 modèles dans le dépôt, Copilot dispose d'un exemple concret sur lequel s'appuyer plutôt que de partir d'une page blanche pour improviser.
Bonus : l'agent de codage Copilot
Si votre dépôt est configuré pour l'agent de codage 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 d'envoi de contrat qui envoie une demande de signature Firma.dev à partir du modèle tmpl_abc123" se transforme en une PR qui configure la variable d'env, le gestionnaire backend, la route du webhook et le bouton de l'interface sans nécessiter beaucoup d'accompagnement. Demandez-lui d'afficher l'URL du webhook et l'ID du modèle sous forme de TODOs dans la description de la PR afin que votre réviseur puisse enregistrer le webhook avant de fusionner. Même avec une automatisation d'une telle qualité, vous voudrez toujours qu'un humain reçoive et vérifie cette PR avant son déploiement.
📘 Lire le guide complet d'intégration de GitHub Copilot
Chaque fichier de configuration, règle spécifique au chemin et modèle de référence se trouve dans la documentation : https://docs.firma.dev/guides/github-copilot-integration
Démarrer
Connectez le MCP, déposez le fichier d'instructions, et Copilot cessera de deviner votre intégration. Commencez à utiliser Firma.dev gratuitement, sans carte de crédit requise, et laissez votre assistant écrire le code de signature électronique correctement dès la première fois.
