Consigue que GitHub Copilot escriba un código de integración de Firma.dev correcto

GitHub Copilot es bueno escribiendo código que parece correcto. El código de integración es donde eso se convierte en un problema. Pídele que conecte una API de firma electrónica e inventará con total confianza un endpoint, adivinará la estructura de un payload o recurrirá a un prefijo Bearer que tu proveedor no utiliza. Terminas depurando el asistente en lugar de lanzar la funcionalidad.

La solución es proporcionarle a Copilot el contrato real de la API mientras trabaja. Firma.dev incluye un servidor MCP de documentación y un conjunto de convenciones para el repositorio que, juntos, consiguen que Copilot genere código de integración correcto a la primera. Dado que Firma.dev es una plataforma de firma electrónica API-first con un precio de 0,049 € por sobre (~5¢ USD) sin licencias por usuario ni consumos mínimos, la integración en sí es pequeña. El objetivo es dejar que Copilot escriba esa pequeña integración de forma correcta en lugar de plausible.

Esto abarca tres pasos de configuración: conectar el MCP de documentación, añadir un archivo de instrucciones para todo el repositorio y dar a Copilot los patrones de referencia con los que trabajar.

Paso 1: conectar el MCP de documentación de Firma.dev

El servidor MCP de documentación expone toda la documentación de Firma.dev en forma de herramientas de búsqueda. Al estar conectado, Copilot consulta endpoints reales, estructuras de solicitud actuales y esquemas de payload de webhooks en lugar de adivinar. Es de solo lectura y no requiere autenticación, por lo que nunca tendrás que pasarle una clave de API.

En VS Code, añádelo a nivel de espacio de trabajo en .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"
    }
  }
}

Recarga la ventana y confirma que firma-docs aparece en el selector de herramientas de Copilot Chat. Para la CLI de Copilot, añade el mismo servidor a ~/.copilot/mcp-config.json y reinicia. En JetBrains o Visual Studio, abre Settings → Copilot → MCP Servers y añade un servidor HTTP llamado firma-docs con la URL https://docs.firma.dev/mcp.

Paso 2: añadir un archivo de instrucciones de Copilot a nivel de repositorio

.github/copilot-instructions.md se carga automáticamente por Copilot Chat, el agente de programación y la revisión de código en todos los entornos compatibles. Aquí es donde se fijan las convenciones que aseguran que el código generado se ajuste al contrato. Crea o añade al final del archivo:

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

Haz commit de él. A partir de ese momento, una instrucción como «añade una solicitud de firma de Firma.dev cuando el usuario haga clic en Enviar contrato» empezará con los valores predeterminados adecuados integrados. Si tu repositorio tiene un límite claro para el backend, puedes añadir un archivo específico para una ruta en .github/instructions/firma.instructions.md con un patrón glob applyTo para que las reglas se carguen únicamente cuando Copilot modifique el código de tu servidor, manteniendo así breve el archivo global.

Paso 3: proporcionar a Copilot los patrones de referencia

Copilot escribe en el lenguaje que coincida con los archivos circundantes. Las estructuras a continuación son las llamadas canónicas de Firma.dev. El archivo de instrucciones orienta a Copilot hacia ellas y el MCP completa los detalles actuales.

Crear y enviar 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 controlador de webhook evalúa según el tipo de evento y lee la solicitud de firma 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;
    // 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 });
}

Con estos patrones en el repositorio, Copilot tiene algo concreto en lo que basarse en lugar de tener que improvisar sobre una página en blanco.

Extra: el agente de programación de Copilot

Si tu repositorio está configurado para el agente de programación de Copilot, se aplica el mismo .github/copilot-instructions.md. Una vez que el MCP y las instrucciones están en su lugar, una incidencia como «Añadir un botón Enviar contrato que envíe una solicitud de firma de Firma.dev desde la plantilla tmpl_abc123» se transforma en una PR que conecta la variable de entorno, el controlador del backend, la ruta del webhook y el botón de la interfaz sin requerir casi intervención manual. Pídele que muestre la URL del webhook y el ID de la plantilla como tareas pendientes (TODOs) en la descripción de la PR para que tu revisor pueda registrar el webhook antes de fusionar. Incluso con una automatización tan buena, sigues necesitando que una persona reciba y revise esa PR antes de desplegarla.

📘 Lee la guía completa de integración de GitHub Copilot
Cada archivo de configuración, regla específica por ruta y patrón de referencia se encuentra en la documentación: https://docs.firma.dev/guides/github-copilot-integration

Empieza ahora

Conecta el MCP, añade el archivo de instrucciones y Copilot dejará de inventar tu integración. Empieza con Firma.dev gratis, sin necesidad de tarjeta de crédito, y deja que tu asistente escriba el código de firma electrónica correctamente desde el primer intento.