Bringen Sie GitHub Copilot dazu, korrekten Firma.dev-Integrationscode zu schreiben

GitHub Copilot ist gut darin, Code zu schreiben, der auf den ersten Blick richtig aussieht. Bei Integrationscode wird das jedoch zum Problem. Bitten Sie es, eine E-Signatur-API anzubinden, und es wird selbstbewusst einen Endpunkt erfinden, die Struktur eines Payloads erraten oder zu einem Bearer-Präfix greifen, das Ihr Anbieter gar nicht verwendet. Am Ende debuggen Sie den Assistenten, anstatt das Feature auszuliefern.

Die Lösung besteht darin, Copilot während der Arbeit den echten API-Vertrag zur Verfügung zu stellen. Firma.dev liefert einen Docs-MCP-Server und eine Reihe von Repo-Konventionen, die zusammen dafür sorgen, dass Copilot bereits beim ersten Versuch korrekten Integrationscode generiert. Da Firma.dev eine API-first E-Signatur-Plattform ist, die mit 0,049 € pro Umschlag (~5 US-Cent) ohne Arbeitsplatzlizenzen oder Mindestmengen abgerechnet wird, ist die Integration selbst schlank. Es geht darum, Copilot diese schlanke Integration korrekt statt nur plausibel schreiben zu lassen.

Dies umfasst drei Einrichtungsschritte: Verbinden des Docs-MCP, Hinzufügen einer repo-weiten Anweisungsdatei und Bereitstellen der Referenzmuster für Copilot.

Schritt 1: Firma.dev Docs-MCP verbinden

Der Docs-MCP-Server stellt die vollständige Dokumentation von Firma.dev als durchsuchbare Tools bereit. Sobald er verbunden ist, fragt Copilot echte Endpunkte, aktuelle Request-Strukturen und Webhook-Payload-Schemas ab, anstatt zu raten. Er ist schreibgeschützt und erfordert keine Authentifizierung, sodass Sie ihm niemals einen API-Schlüssel übergeben müssen.

Fügen Sie ihn in VS Code auf Workspace-Ebene in .vscode/mcp.json ein:

{
  "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"
    }
  }
}

Laden Sie das Fenster neu und vergewissern Sie sich, dass firma-docs in der Tool-Auswahl von Copilot Chat angezeigt wird. Fügen Sie für die Copilot-CLI denselben Server zu ~/.copilot/mcp-config.json hinzu und starten Sie neu. Öffnen Sie in JetBrains oder Visual Studio Settings → Copilot → MCP Servers und fügen Sie einen HTTP-Server namens firma-docs mit der URL https://docs.firma.dev/mcp hinzu.

Schritt 2: Repo-weite Copilot-Anweisungsdatei hinzufügen

.github/copilot-instructions.md wird von Copilot Chat, dem Coding-Agenten und der Code-Review in jeder unterstützten Umgebung automatisch geladen. Hier legen Sie die Konventionen fest, die dafür sorgen, dass generierter Code API-konform bleibt. Erstellen Sie die Datei oder hängen Sie Folgendes an:

## 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

Commiten Sie die Datei. Von da an beginnt ein Prompt wie „Firma.dev-Signaturanfrage hinzufügen, wenn der Benutzer auf Vertrag senden klickt“ direkt mit den richtigen Standardeinstellungen. Wenn Ihr Repo eine klare Backend-Abgrenzung hat, können Sie eine pfadspezifische Datei unter .github/instructions/firma.instructions.md mit einem applyTo-Glob anlegen, sodass die Regeln nur geladen werden, wenn Copilot Ihren Server-Code bearbeitet – so bleibt die globale Datei übersichtlich.

Schritt 3: Copilot die Referenzmuster bereitstellen

Copilot schreibt in der Programmiersprache, die zu den umgebenden Dateien passt. Die folgenden Strukturen sind die kanonischen Firma.dev-Aufrufe. Die Anweisungsdatei leitet Copilot zu ihnen hin und das MCP ergänzt die aktuellen Details.

Erstellen und Senden in 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();
}

Ein Webhook-Handler unterscheidet nach dem Ereignistyp und liest die Signaturanfrage aus data aus:

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 });
}

Mit diesen Mustern im Repository hat Copilot eine konkrete Vorlage, an der es sich orientieren kann, anstatt ins Blaue hinein zu improvisieren.

Bonus: der Copilot Coding Agent

Wenn Ihr Repo für den Copilot Coding Agent eingerichtet ist, gilt dieselbe .github/copilot-instructions.md. Sobald das MCP und die Anweisungen eingerichtet sind, wird aus einem Issue wie „Füge eine Schaltfläche 'Vertrag senden' hinzu, die eine Firma.dev-Signaturanfrage aus der Vorlage tmpl_abc123 sendet“ ein PR, der die Umgebungsvariable, den Backend-Handler, die Webhook-Route und den UI-Button ohne großen manuellen Aufwand verdrahtet. Bitten Sie ihn, die Webhook-URL und die Vorlagen-ID als TODOs in der PR-Beschreibung aufzuführen, damit Ihr Reviewer den Webhook vor dem Mergen registrieren kann. Selbst bei so guter Automatisierung sollten Sie sicherstellen, dass ein Mensch diesen PR prüft und abnimmt, bevor er produktiv geht.

📘 Lesen Sie den vollständigen GitHub Copilot Integrationsleitfaden
Jede Konfigurationsdatei, pfadspezifische Regel und jedes Referenzmuster finden Sie in der Dokumentation: https://docs.firma.dev/guides/github-copilot-integration

Jetzt starten

Verbinden Sie das MCP, fügen Sie die Anweisungsdatei hinzu und Copilot hört auf, bei Ihrer Integration zu raten. Starten Sie kostenlos mit Firma.dev, keine Kreditkarte erforderlich, und lassen Sie Ihren Assistenten den E-Signatur-Code gleich beim ersten Mal fehlerfrei schreiben.