Faites écrire à GitHub Copilot du code d'intégration Firma.dev correct

GitHub Copilot sait très bien générer du code qui a l'air correct. Pour le code d'intégration, c'est là que les problèmes commencent. Demandez-lui d'intégrer une API de signature électronique et il inventera avec assurance un endpoint, devinera la structure d'un payload 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 d'API pendant qu'il travaille. Firma.dev propose un serveur MCP de documentation ainsi qu'un ensemble de conventions de dépôt qui, ensemble, permettent à Copilot de générer du code d'intégration correct dès le premier essai. Comme Firma.dev est une plateforme de signature électronique API-first facturée 0,049 € par enveloppe (~5 ¢ USD) sans abonnement par utilisateur ni engagement minimum, l'intégration elle-même est légère. L'objectif est de permettre à Copilot d'écrire cette petite intégration correctement, et non pas simplement de façon plausible.

Cela comprend trois étapes de configuration : connecter le MCP Docs, ajouter un fichier d'instructions au niveau du dépôt, et fournir à Copilot les modèles de référence à reproduire.

Étape 1 : connecter le MCP Docs de Firma.dev

Le serveur MCP Docs expose l'intégralité de la documentation de Firma.dev sous forme d'outils interrogeables. Une fois connecté, Copilot consulte les véritables endpoints, les formats de requête actuels et les schémas de payload des webhooks au lieu de deviner. Il est en lecture seule et sans authentification, vous n'avez donc jamais à 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 vérifiez que firma-docs apparaît dans le sélecteur d'outils de Copilot Chat. Pour la CLI 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

.github/copilot-instructions.md est chargé automatiquement par Copilot Chat, l'agent de code et la revue de code sur tous les environnements pris en charge. C'est ici que vous définissez les conventions qui garantissent la conformité du code généré avec le contrat. Créez ou complétez le fichier :

## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess

## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess

## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess

Committez-le. Dès lors, un prompt comme « ajouter une demande de signature Firma.dev lorsque l'utilisateur clique sur Envoyer le contrat » partira immédiatement avec les bons paramètres par défaut. Si votre dépôt possède une séparation nette pour le backend, vous pouvez ajouter un fichier spécifique au chemin d'accès sous .github/instructions/firma.instructions.md avec un glob applyTo afin que les règles ne se chargent que lorsque Copilot modifie votre code serveur, ce qui permet de garder le fichier global concis.

Étape 3 : fournir à Copilot les modèles de référence

Copilot écrit dans le langage correspondant aux fichiers environnants. Les structures ci-dessous constituent les appels Firma.dev canoniques. Le fichier d'instructions oriente Copilot vers ces modèles et le MCP complète les détails à jour.

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 s'oriente selon le type d'événement et extrait 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;
    // Update the matching record and trigger follow-up logic
  }

  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;
    // Update the matching record and trigger follow-up logic
  }

  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;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}

Avec ces modèles dans le dépôt, Copilot dispose d'éléments concrets sur lesquels s'appuyer plutôt que d'une page blanche où improviser.

Bonus : l'agent de code Copilot

Si votre dépôt est configuré pour l'agent de code Copilot, le même fichier .github/copilot-instructions.md s'applique. Une fois le MCP et les instructions en place, une issue telle que « Ajouter un bouton Envoyer le contrat qui envoie une demande de signature Firma.dev à partir du modèle tmpl_abc123 » donne naissance à une PR configurant la variable d'environnement, le gestionnaire backend, la route du webhook et le bouton de l'interface utilisateur, sans nécessiter beaucoup d'aide. Demandez-lui d'indiquer l'URL du webhook et l'identifiant du modèle sous forme de TODO dans la description de la PR afin que votre relecteur puisse enregistrer le webhook avant de fusionner. Même avec une automatisation de cette qualité, il reste essentiel qu'un humain reçoive et vérifie cette PR avant sa mise en production.

📘 Consultez 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

Commencer

Connectez le MCP, ajoutez le fichier d'instructions, et Copilot cessera de faire des suppositions sur votre intégration. Démarrez gratuitement avec Firma.dev, sans carte bancaire requise, et laissez votre assistant rédiger le code de signature électronique correctement dès le premier essai.