GitHub Copilot es bueno escribiendo código que parece correcto. El problema surge con el código de integración. Si le pides que conecte una API de firma electrónica, se inventará con total confianza un endpoint, adivinará la estructura de un payload o recurrirá a un prefijo Bearer que tu proveedor no utiliza. Acabas depurando los errores del asistente en lugar de desplegar la funcionalidad.
La solución consiste en proporcionarle a Copilot el contrato de la API real mientras trabaja. Firma.dev ofrece un servidor de Docs MCP y un conjunto de convenciones para repositorios que, juntos, hacen 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 coste de 0,049 € por sobre (~5 ¢ USD) sin licencias de usuario ni mínimos, la integración en sí es pequeña. El objetivo es permitir que Copilot escriba esa pequeña integración correctamente en lugar de que lo parezca.
Esto abarca tres pasos de configuración: conectar el MCP de Docs, añadir un archivo de instrucciones para todo el repositorio y darle a Copilot los patrones de referencia que debe seguir.
Paso 1: conectar el Docs MCP de Firma.dev
El servidor Docs MCP expone toda la documentación de Firma.dev como herramientas de búsqueda. Al estar conectado, Copilot consulta endpoints reales, estructuras de solicitud actuales y esquemas de carga útil de webhooks en lugar de adivinar de forma improvisada. Es de solo lectura y no requiere autenticación, por lo que nunca le transmitirás 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"
}
}
}Vuelve a cargar la ventana y confirma que firma-docs aparezca 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 Configuración → Copilot → Servidores MCP 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 para todo el repositorio
.github/copilot-instructions.md se carga automáticamente mediante Copilot Chat, el agente de programación y la revisión de código en todos los entornos compatibles. Aquí es donde fijas las convenciones que mantienen el código generado de acuerdo con el contrato de la API. Crea o añade al archivo:
## Integración de firma electrónica de Firma.dev
Al generar código que envía, recibe o integra firmas electrónicas de Firma, sigue estas convenciones:
- URL base de la API: `https://api.firma.dev/functions/v1/signing-request-api`
- Autenticación: cabecera `Authorization` establecida con la clave de API de Firma sin procesar (sin prefijo `Bearer`)
- La clave reside en `FIRMA_API_KEY` como variable de entorno. Llama a Firma únicamente desde el backend, nunca desde el navegador. No confirmes nunca el valor en el repositorio.
- Usar `POST /signing-requests/create-and-send` de forma predeterminada al enviar desde una plantilla. Utilizar el flujo de dos pasos `POST /signing-requests` y luego `POST /signing-requests/{id}/send` únicamente cuando el usuario necesite revisar el borrador antes de enviarlo.
- Estructura del objeto destinatario: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- Para los controladores de webhooks, realizar una bifurcación según `payload.type` (por ejemplo, `signing_request.completed`). El objeto de solicitud de firma reside en `payload.data.signing_request`.
- Para la firma integrada, iframe `https://app.firma.dev/signing/{signing_request_user_id}` con `allow="camera;microphone;clipboard-write"`.
- Si no estás seguro de la estructura de un endpoint o de un campo, utiliza el servidor MCP `firma-docs`. No adivines de forma improvisada
## Integración de firma electrónica de Firma.dev
Al generar código que envía, recibe o integra firmas electrónicas de Firma, sigue estas convenciones:
- URL base de la API: `https://api.firma.dev/functions/v1/signing-request-api`
- Autenticación: cabecera `Authorization` establecida con la clave de API de Firma sin procesar (sin prefijo `Bearer`)
- La clave reside en `FIRMA_API_KEY` como variable de entorno. Llama a Firma únicamente desde el backend, nunca desde el navegador. No confirmes nunca el valor en el repositorio.
- Usar `POST /signing-requests/create-and-send` de forma predeterminada al enviar desde una plantilla. Utilizar el flujo de dos pasos `POST /signing-requests` y luego `POST /signing-requests/{id}/send` únicamente cuando el usuario necesite revisar el borrador antes de enviarlo.
- Estructura del objeto destinatario: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- Para los controladores de webhooks, realizar una bifurcación según `payload.type` (por ejemplo, `signing_request.completed`). El objeto de solicitud de firma reside en `payload.data.signing_request`.
- Para la firma integrada, iframe `https://app.firma.dev/signing/{signing_request_user_id}` con `allow="camera;microphone;clipboard-write"`.
- Si no estás seguro de la estructura de un endpoint o de un campo, utiliza el servidor MCP `firma-docs`. No adivines de forma improvisada
## Integración de firma electrónica de Firma.dev
Al generar código que envía, recibe o integra firmas electrónicas de Firma, sigue estas convenciones:
- URL base de la API: `https://api.firma.dev/functions/v1/signing-request-api`
- Autenticación: cabecera `Authorization` establecida con la clave de API de Firma sin procesar (sin prefijo `Bearer`)
- La clave reside en `FIRMA_API_KEY` como variable de entorno. Llama a Firma únicamente desde el backend, nunca desde el navegador. No confirmes nunca el valor en el repositorio.
- Usar `POST /signing-requests/create-and-send` de forma predeterminada al enviar desde una plantilla. Utilizar el flujo de dos pasos `POST /signing-requests` y luego `POST /signing-requests/{id}/send` únicamente cuando el usuario necesite revisar el borrador antes de enviarlo.
- Estructura del objeto destinatario: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- Para los controladores de webhooks, realizar una bifurcación según `payload.type` (por ejemplo, `signing_request.completed`). El objeto de solicitud de firma reside en `payload.data.signing_request`.
- Para la firma integrada, iframe `https://app.firma.dev/signing/{signing_request_user_id}` con `allow="camera;microphone;clipboard-write"`.
- Si no estás seguro de la estructura de un endpoint o de un campo, utiliza el servidor MCP `firma-docs`. No adivines de forma improvisada
Haz un commit. 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" se iniciará con los valores predeterminados correctos integrados. Si tu repositorio tiene un límite de backend claro, puedes añadir un archivo específico de ruta en .github/instructions/firma.instructions.md con un glob de applyTo para que las reglas se carguen solo cuando Copilot edite el código de tu servidor, manteniendo el archivo global corto.
Paso 3: darle a Copilot los patrones de referencia
Copilot escribe en el lenguaje que coincida con los archivos del entorno. Las siguientes estructuras 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 se bifurca 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;
}
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 });
}Con estos patrones en el repositorio, Copilot tiene una base concreta que seguir en lugar de improvisar sobre una página en blanco.
Bonus: el agente de programación de Copilot
Si tu repositorio está configurado para el agente de programación de Copilot, se aplica el mismo archivo .github/copilot-instructions.md. Una vez implementados el MCP y las instrucciones, un ticket como "Añadir un botón de Enviar contrato que envíe una solicitud de firma de Firma.dev desde la plantilla tmpl_abc123" se convierte en un PR que conecta la variable de entorno, el controlador de backend, la ruta del webhook y el botón de la interfaz de usuario sin necesitar demasiada supervisión. Pídele que muestre la URL del webhook y el ID de la plantilla como comentarios TODO en la descripción del PR para que tu revisor pueda registrar el webhook antes de hacer el merge. Incluso con una automatización tan buena, querrás que sigan siendo personas quienes reciban y verifiquen ese PR antes de que se despliegue.
📘 Lee la guía completa de integración de GitHub Copilot
Cada archivo de configuración, regla específica de ruta y patrón de referencia se encuentra en la documentación: https://docs.firma.dev/guides/github-copilot-integration
Comenzar
Conecta el MCP, añade el archivo de instrucciones y Copilot dejará de improvisar en tu integración. Comienza a usar Firma.dev gratis, sin necesidad de tarjeta de crédito, y deja que tu asistente escriba el código de firma electrónica correctamente a la primera.
