O GitHub Copilot é bom a escrever código que parece correto. O código de integração é onde isso se torna um problema. Peça-lhe para ligar uma API de assinatura eletrónica e ele irá inventar confiantemente um endpoint, adivinhar o formato de um payload ou recorrer a um prefixo Bearer que o seu fornecedor não utiliza. Acaba a depurar o assistente em vez de lançar a funcionalidade.
A solução é fornecer ao Copilot o contrato real da API enquanto ele trabalha. O Firma.dev disponibiliza um servidor MCP de Docs e um conjunto de convenções de repositório que, em conjunto, fazem com que o Copilot gere código de integração correto à primeira tentativa. Como o Firma.dev é uma plataforma de assinatura eletrónica API-first faturada a 0,049 € por envelope (~5¢ USD) sem lugares de utilizador ou consumos mínimos, a integração em si é pequena. O objetivo é permitir que o Copilot escreva essa pequena integração de forma correta e não apenas plausível.
Isto abrange três passos de configuração: ligar o MCP de Docs, adicionar um ficheiro de instruções a nível do repositório e fornecer ao Copilot os padrões de referência correspondentes.
Passo 1: ligar o MCP de Docs do Firma.dev
O servidor MCP de Docs expõe toda a documentação do Firma.dev como ferramentas pesquisáveis. Com ele ligado, o Copilot consulta endpoints reais, formatos de pedido atuais e esquemas de payload de webhooks em vez de adivinhar. É apenas de leitura e não autenticado, pelo que nunca lhe passa uma chave de API.
No VS Code, adicione-o ao nível do workspace em .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"
}
}
}Recarregue a janela e confirme que firma-docs aparece no seletor de ferramentas do Copilot Chat. Para a CLI do Copilot, adicione o mesmo servidor a ~/.copilot/mcp-config.json e reinicie. No JetBrains ou Visual Studio, abra Definições → Copilot → Servidores MCP e adicione um servidor HTTP chamado firma-docs com o URL https://docs.firma.dev/mcp.
Passo 2: adicionar um ficheiro de instruções do Copilot a nível do repositório
O ficheiro .github/copilot-instructions.md é carregado automaticamente pelo Copilot Chat, pelo agente de programação e pela revisão de código em todos os ambientes suportados. É aqui que fixa as convenções que mantêm o código gerado em conformidade com o contrato. Crie ou acrescente ao ficheiro:
## Integração de assinatura eletrónica Firma.dev
Ao gerar código que envia, recebe ou incorpora assinaturas eletrónicas Firma, siga estas convenções:
- URL base da API: `https://api.firma.dev/functions/v1/signing-request-api`
- Autenticação: cabeçalho `Authorization` definido para a chave de API crua da Firma (sem prefixo `Bearer`)
- A chave reside em `FIRMA_API_KEY` como uma variável de ambiente. Chame a Firma apenas a partir do backend, nunca do navegador. Nunca faça commit do valor.
- Utilize por predefinição `POST /signing-requests/create-and-send` ao enviar a partir de um modelo. Utilize apenas o fluxo em dois passos `POST /signing-requests` seguido de `POST /signing-requests/{id}/send` quando o utilizador precisar de rever o rascunho antes de enviar.
- Formato do objeto de destinatário: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- Para processadores de webhooks, ramifique com base em `payload.type` (ex.: `signing_request.completed`). O objeto de pedido de assinatura reside em `payload.data.signing_request`.
- Para assinatura incorporada, use iframe `https://app.firma.dev/signing/{signing_request_user_id}` com `allow="camera;microphone;clipboard-write"`.
- Quando tiver dúvidas sobre um endpoint ou formato de campo, utilize o servidor MCP `firma-docs`. Não adivinhe
## Integração de assinatura eletrónica Firma.dev
Ao gerar código que envia, recebe ou incorpora assinaturas eletrónicas Firma, siga estas convenções:
- URL base da API: `https://api.firma.dev/functions/v1/signing-request-api`
- Autenticação: cabeçalho `Authorization` definido para a chave de API crua da Firma (sem prefixo `Bearer`)
- A chave reside em `FIRMA_API_KEY` como uma variável de ambiente. Chame a Firma apenas a partir do backend, nunca do navegador. Nunca faça commit do valor.
- Utilize por predefinição `POST /signing-requests/create-and-send` ao enviar a partir de um modelo. Utilize apenas o fluxo em dois passos `POST /signing-requests` seguido de `POST /signing-requests/{id}/send` quando o utilizador precisar de rever o rascunho antes de enviar.
- Formato do objeto de destinatário: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- Para processadores de webhooks, ramifique com base em `payload.type` (ex.: `signing_request.completed`). O objeto de pedido de assinatura reside em `payload.data.signing_request`.
- Para assinatura incorporada, use iframe `https://app.firma.dev/signing/{signing_request_user_id}` com `allow="camera;microphone;clipboard-write"`.
- Quando tiver dúvidas sobre um endpoint ou formato de campo, utilize o servidor MCP `firma-docs`. Não adivinhe
## Integração de assinatura eletrónica Firma.dev
Ao gerar código que envia, recebe ou incorpora assinaturas eletrónicas Firma, siga estas convenções:
- URL base da API: `https://api.firma.dev/functions/v1/signing-request-api`
- Autenticação: cabeçalho `Authorization` definido para a chave de API crua da Firma (sem prefixo `Bearer`)
- A chave reside em `FIRMA_API_KEY` como uma variável de ambiente. Chame a Firma apenas a partir do backend, nunca do navegador. Nunca faça commit do valor.
- Utilize por predefinição `POST /signing-requests/create-and-send` ao enviar a partir de um modelo. Utilize apenas o fluxo em dois passos `POST /signing-requests` seguido de `POST /signing-requests/{id}/send` quando o utilizador precisar de rever o rascunho antes de enviar.
- Formato do objeto de destinatário: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- Para processadores de webhooks, ramifique com base em `payload.type` (ex.: `signing_request.completed`). O objeto de pedido de assinatura reside em `payload.data.signing_request`.
- Para assinatura incorporada, use iframe `https://app.firma.dev/signing/{signing_request_user_id}` com `allow="camera;microphone;clipboard-write"`.
- Quando tiver dúvidas sobre um endpoint ou formato de campo, utilize o servidor MCP `firma-docs`. Não adivinhe
Faça commit do ficheiro. A partir daí, um comando como "adicionar um pedido de assinatura Firma.dev quando o utilizador clicar em Enviar Contrato" começa logo com as predefinições corretas incorporadas. Se o seu repositório tiver uma separação clara de backend, pode adicionar um ficheiro específico por caminho em .github/instructions/firma.instructions.md com um glob applyTo para que as regras sejam carregadas apenas quando o Copilot editar o seu código de servidor, mantendo o ficheiro global reduzido.
Passo 3: fornecer ao Copilot os padrões de referência
O Copilot escreve na linguagem que corresponder aos ficheiros circundantes. Os formatos abaixo são as chamadas canónicas do Firma.dev. O ficheiro de instruções orienta o Copilot para eles e o MCP preenche os detalhes atuais.
Criar e enviar em 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();
}Um processador de webhook ramifica pelo tipo de evento e lê o pedido de assinatura 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 });
}Com estes padrões no repositório, o Copilot tem algo concreto a que se alinhar em vez de uma página em branco para improvisar.
Bónus: o agente de programação do Copilot
Se o seu repositório estiver configurado para o agente de programação do Copilot, aplica-se o mesmo .github/copilot-instructions.md. Assim que o MCP e as instruções estiverem implementados, um issue como "Adicionar um botão Enviar Contrato que envie um pedido de assinatura Firma.dev a partir do modelo tmpl_abc123" transforma-se num PR que configura a variável de ambiente, o processador de backend, a rota de webhook e o botão da interface de utilizador sem grande intervenção manual. Peça-lhe para indicar o URL do webhook e o ID do modelo como TODOs na descrição do PR, para que o revisor possa registar o webhook antes de integrar as alterações. Mesmo com uma automação tão avançada, continuará a querer que um humano receba e verifique esse PR antes de o colocar em produção.
📘 Leia o guia completo de integração do GitHub Copilot
Todos os ficheiros de configuração, regras específicas por caminho e padrões de referência estão na documentação: https://docs.firma.dev/guides/github-copilot-integration
Começar
Ligue o MCP, adicione o ficheiro de instruções e o Copilot deixará de adivinhar na sua integração. Comece a usar o Firma.dev gratuitamente, sem necessidade de cartão de crédito, e permita que o seu assistente escreva o código de assinatura eletrónica de forma correta logo à primeira.
