GitHub Copilot ist gut darin, Code zu schreiben, der richtig aussieht. Bei Integrationscode wird das jedoch zum Problem. Bittet man ihn, eine E-Signatur-API anzubinden, erfindet er selbstbewusst einen Endpunkt, rät das Format der Payload oder greift zu einem Bearer-Präfix, das der eigene Anbieter gar nicht verwendet. Am Ende verbringt man mehr Zeit mit dem Debuggen des Assistenten, als das Feature zu veröffentlichen.
Die Lösung besteht darin, Copilot während der Arbeit den echten API-Vertrag zur Verfügung zu stellen. Firma.dev bietet einen Docs-MCP-Server und eine Reihe von Repository-Richtlinien, die zusammen dafür sorgen, dass Copilot bereits im ersten Anlauf korrekten Integrationscode generiert. Da Firma.dev eine API-first E-Signatur-Plattform ist, die mit 0,049 € pro Umschlag (~5¢ USD) abgerechnet wird – ohne feste Plätze oder Mindestumsätze –, ist die Integration selbst minimal. Der Sinn ist, Copilot diese kleine Integration korrekt und nicht nur plausibel schreiben zu lassen.
Dies umfasst drei Einrichtungsschritte: Verbinden des Docs MCP, Hinzufügen einer repositoryweiten Anweisungsdatei und Bereitstellen der Referenzmuster für Copilot.
Schritt 1: Den Firma.dev Docs MCP verbinden
Der Docs-MCP-Server stellt die vollständige Dokumentation von Firma.dev als durchsuchbare Tools zur Verfügung. Sobald er verbunden ist, fragt Copilot echte Endpunkte, aktuelle Request-Formate und Webhook-Payload-Schemas ab, anstatt zu raten. Er ist schreibgeschützt und unauthentifiziert, sodass man niemals einen API-Schlüssel übergeben muss.
Fügen Sie ihn in VS Code auf Workspace-Ebene in .vscode/mcp.json hinzu:
{
"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 überprüfen Sie, ob firma-docs in der Tool-Auswahl von Copilot Chat angezeigt wird. Für die Copilot-CLI fügen Sie denselben Server zu ~/.copilot/mcp-config.json hinzu und starten Sie neu. In JetBrains oder Visual Studio öffnen Sie Einstellungen → Copilot → MCP-Server und fügen Sie einen HTTP-Server namens firma-docs mit der URL https://docs.firma.dev/mcp hinzu.
Schritt 2: Eine repositoryweite Copilot-Anweisungsdatei hinzufügen
Die Datei .github/copilot-instructions.md wird von Copilot Chat, dem Coding-Agenten und bei Code-Reviews in jeder unterstützten Umgebung automatisch geladen. Hier legen Sie die Konventionen fest, die dafür sorgen, dass der generierte Code vertragskonform bleibt. Erstellen Sie die Datei oder hängen Sie Folgendes an:
## Firma.dev E-Signatur-Integration
Wenn Code generiert wird, der Firma-E-Signaturen sendet, empfängt oder einbettet, müssen folgende Konventionen eingehalten werden:
- API-Basis-URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: Der Header `Authorization` wird direkt auf den rohen Firma-API-Schlüssel gesetzt (kein `Bearer`-Präfix)
- Der Schlüssel befindet sich in der Umgebungsvariable `FIRMA_API_KEY`. Firma darf nur vom Backend aufgerufen werden, niemals im Browser. Den Wert niemals im Repository speichern.
- Standardmäßig `POST /signing-requests/create-and-send` verwenden, wenn aus einer Vorlage gesendet wird. Den zweistufigen Ablauf `POST /signing-requests` gefolgt von `POST /signing-requests/{id}/send` nur dann nutzen, wenn der Benutzer den Entwurf vor dem Senden prüfen muss.
- Format des Empfänger-Objekts: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- Bei Webhook-Handlern nach `payload.type` unterscheiden (z. B. `signing_request.completed`). Das Signaturanfrage-Objekt befindet sich unter `payload.data.signing_request`.
- Für eingebettetes Signieren ein iframe unter `https://app.firma.dev/signing/{signing_request_user_id}` mit `allow="camera;microphone;clipboard-write"` einbinden.
- Bei Unsicherheiten über einen Endpunkt oder ein Feld-Format den MCP-Server `firma-docs` nutzen. Nicht raten
## Firma.dev E-Signatur-Integration
Wenn Code generiert wird, der Firma-E-Signaturen sendet, empfängt oder einbettet, müssen folgende Konventionen eingehalten werden:
- API-Basis-URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: Der Header `Authorization` wird direkt auf den rohen Firma-API-Schlüssel gesetzt (kein `Bearer`-Präfix)
- Der Schlüssel befindet sich in der Umgebungsvariable `FIRMA_API_KEY`. Firma darf nur vom Backend aufgerufen werden, niemals im Browser. Den Wert niemals im Repository speichern.
- Standardmäßig `POST /signing-requests/create-and-send` verwenden, wenn aus einer Vorlage gesendet wird. Den zweistufigen Ablauf `POST /signing-requests` gefolgt von `POST /signing-requests/{id}/send` nur dann nutzen, wenn der Benutzer den Entwurf vor dem Senden prüfen muss.
- Format des Empfänger-Objekts: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- Bei Webhook-Handlern nach `payload.type` unterscheiden (z. B. `signing_request.completed`). Das Signaturanfrage-Objekt befindet sich unter `payload.data.signing_request`.
- Für eingebettetes Signieren ein iframe unter `https://app.firma.dev/signing/{signing_request_user_id}` mit `allow="camera;microphone;clipboard-write"` einbinden.
- Bei Unsicherheiten über einen Endpunkt oder ein Feld-Format den MCP-Server `firma-docs` nutzen. Nicht raten
## Firma.dev E-Signatur-Integration
Wenn Code generiert wird, der Firma-E-Signaturen sendet, empfängt oder einbettet, müssen folgende Konventionen eingehalten werden:
- API-Basis-URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: Der Header `Authorization` wird direkt auf den rohen Firma-API-Schlüssel gesetzt (kein `Bearer`-Präfix)
- Der Schlüssel befindet sich in der Umgebungsvariable `FIRMA_API_KEY`. Firma darf nur vom Backend aufgerufen werden, niemals im Browser. Den Wert niemals im Repository speichern.
- Standardmäßig `POST /signing-requests/create-and-send` verwenden, wenn aus einer Vorlage gesendet wird. Den zweistufigen Ablauf `POST /signing-requests` gefolgt von `POST /signing-requests/{id}/send` nur dann nutzen, wenn der Benutzer den Entwurf vor dem Senden prüfen muss.
- Format des Empfänger-Objekts: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- Bei Webhook-Handlern nach `payload.type` unterscheiden (z. B. `signing_request.completed`). Das Signaturanfrage-Objekt befindet sich unter `payload.data.signing_request`.
- Für eingebettetes Signieren ein iframe unter `https://app.firma.dev/signing/{signing_request_user_id}` mit `allow="camera;microphone;clipboard-write"` einbinden.
- Bei Unsicherheiten über einen Endpunkt oder ein Feld-Format den MCP-Server `firma-docs` nutzen. Nicht raten
Prägen Sie dies ein (Commit). Ab diesem Zeitpunkt startet ein Prompt wie „Füge eine Firma.dev-Signaturanfrage hinzu, wenn der Benutzer auf Vertrag senden klickt“ bereits mit den richtigen Standardwerten im Hintergrund. Wenn Ihr Repository eine klare Backend-Grenze hat, können Sie eine pfadspezifische Datei unter .github/instructions/firma.instructions.md mit einem applyTo-Glob erstellen, sodass die Regeln nur geladen werden, wenn Copilot den Backend-Code bearbeitet, wodurch die globale Datei übersichtlich bleibt.
Schritt 3: Copilot die Referenzmuster zur Verfügung stellen
Copilot schreibt in der Programmiersprache, die zu den umgebenden Dateien passt. Die unten gezeigten Formate sind die kanonischen Firma.dev-Aufrufe. Die Anweisungsdatei lenkt Copilot dorthin, und der MCP steuert die aktuellen Details bei.
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 Event-Typ 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;
}
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 });
}Mit diesen Mustern im Repository hat Copilot ein konkretes Vorbild, statt auf einer leeren Seite improvisieren zu müssen.
Bonus: Der Copilot-Coding-Agent
Wenn Ihr Repository für den Copilot-Coding-Agenten eingerichtet ist, gilt dieselbe Datei .github/copilot-instructions.md. Sobald der MCP und die Anweisungen vorhanden sind, wird aus einem Issue wie „Füge einen Button ,Vertrag senden‘ hinzu, der eine Firma.dev-Signaturanfrage aus der Vorlage tmpl_abc123 sendet“ ein fertiger PR, der die Umgebungsvariable, den Backend-Handler, die Webhook-Route und den UI-Button fast ohne manuelle Eingriffe einbaut. Bitten Sie den Agenten, 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 einer so guten Automatisierung sollte am Ende immer noch ein Mensch diesen PR prüfen und freigeben, bevor er live 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 den MCP, hinterlegen Sie die Anweisungsdatei, und Copilot hört auf, bei Ihrer Integration zu raten. Starten Sie kostenlos mit Firma.dev, ganz ohne Kreditkarte, und lassen Sie Ihren Assistenten den E-Signatur-Code direkt beim ersten Mal fehlerfrei schreiben.
