Ferramentas e agentes de IA

In English. Everything on this page is generated from the same OpenAPI documents that power the reference: a Postman collection per version (also importable in Bruno, Insomnia and Hoppscotch), a Model Context Protocol (MCP) server that turns each operation into a tool, the llms.txt index for language models and the sandbox environment. The last section is the checklist an agent should follow when operating the API. Text in Brazilian Portuguese.

Tudo nesta página nasce dos mesmos documentos OpenAPI que alimentam a referência (v1, v2): nenhum formato é mantido à mão, então nenhum fica atrás do contrato. As URLs abaixo são as do ambiente que serviu esta página (https://api.letssign.com.br); o sandbox tem as mesmas rotas no host dele.

Coleção Postman

Cada versão tem uma coleção no formato Postman v2.1, gerada pela própria API:

Importar. No Postman: Import, cole a URL da coleção. No Bruno: Import Collection e escolha Postman Collection com o arquivo baixado, ou OpenAPI V3 apontando para o documento OpenAPI. Insomnia e Hoppscotch importam tanto a coleção Postman quanto o documento OpenAPI.

O que vem pronto.

• Uma pasta por recurso (as tags do documento), com a descrição da tag. Cada requisição leva o operationId e a descrição completa da operação.
• Autenticação no nível da coleção: header Authorization com o valor da variável apiKey, sem prefixo. Nenhuma requisição precisa de configuração própria.
• Variáveis da coleção: baseUrl (já preenchida com https://api.letssign.com.br), apiKey, accountId e webhookUrl. O accountId substitui o segmento {accountId} de todas as rotas; os demais parâmetros de rota (:id, :documentId) ficam como variáveis da URL, com descrição.
• Parâmetros de consulta declarados, com o valor padrão preenchido; os opcionais sem padrão entram desmarcados.
• Corpo de exemplo em cada POST e PUT e exemplos de resposta salvos, os mesmos da referência.
• Pasta Webhooks: um POST por evento, com o payload de exemplo, enviado a webhookUrl sem autenticação. Serve para testar o seu receptor antes de cadastrar a URL na conta.

Para começar. Preencha apiKey e accountId (obtenha o segundo com a requisição Lista as contas do parceiro, partners_v1_accounts_list, na coleção da v1) e execute as consultas da pasta de contas. Faça isso primeiro no sandbox.

Servidor MCP a partir do OpenAPI

O Model Context Protocol (MCP) é o padrão com que assistentes (Claude, Cursor, VS Code e outros) recebem ferramentas. A API não expõe um servidor MCP próprio. Em vez disso, o documento OpenAPI tem o que um servidor genérico precisa para gerar uma ferramenta por operação: operationId estável, descrição, schemas e exemplos. A configuração abaixo usa o @ivotoby/openapi-mcp-server, um servidor MCP de código aberto que lê o documento na inicialização e cria uma ferramenta por operação; foi verificada com este contrato na versão indicada (49 ferramentas para a v1, chamadas chegando à API), e qualquer servidor equivalente que aceite uma URL de OpenAPI 3.1 e um header fixo funciona do mesmo jeito.

Claude Desktop, Cursor e outros clientes com mcpServers

Adicione ao arquivo de configuração do cliente (claude_desktop_config.json, .cursor/mcp.json):

{
  "mcpServers": {
    "partners-api-v1": {
      "command": "npx",
      "args": [
        "-y", "@ivotoby/openapi-mcp-server@1.16.1",
        "--api-base-url", "https://api.letssign.com.br",
        "--openapi-spec", "https://api.letssign.com.br/docs/partners-v1/openapi.json",
        "--headers", "Authorization:SUA_CHAVE",
        "--disable-abbreviation", "true",
        "--name", "partners-api-v1"
      ]
    }
  }
}

Claude Code

claude mcp add partners-api-v1 -- npx -y @ivotoby/openapi-mcp-server@1.16.1 \
  --api-base-url https://api.letssign.com.br \
  --openapi-spec https://api.letssign.com.br/docs/partners-v1/openapi.json \
  --headers "Authorization:SUA_CHAVE" \
  --disable-abbreviation true \
  --name partners-api-v1

O que observar

• Uma versão por servidor. Cada documento vira um servidor; para a v2, repita a configuração com https://api.letssign.com.br/docs/partners-v2/openapi.json e outro nome. A v1 concentra a maior parte das operações; a v2 tem as listagens paginadas e o download com anexos.
• Nome das ferramentas. Com --disable-abbreviation true, cada ferramenta recebe o operationId da operação com hifens no lugar dos sublinhados (partners-v1-accounts-list, partners-v2-documents-list), então os nomes citados nos guias e na referência são reconhecíveis para o agente. Sem a opção, o servidor abrevia os nomes (partners-v-1-accounts-lst). O nome mais longo do contrato tem 62 caracteres, abaixo do limite de 64 que a abreviação existe para contornar. A descrição de cada ferramenta é a descrição da operação, e os parâmetros de rota e de consulta viram o schema de entrada, com as descrições da referência.
• Reduza a superfície. A v1 tem dezenas de operações; um agente trabalha melhor com menos ferramentas. --tag Documentos (repetível) limita a um recurso; --operation get deixa só consultas, útil para exploração sem risco; --tools dynamic troca as ferramentas individuais por três meta-ferramentas (listar operações, ler o schema de uma, invocá-la), que consomem pouco contexto. As tags são as da referência (Contas, Documentos, Webhooks etc.).
• A chave fica no arquivo de configuração e dá acesso a todas as contas vinculadas ao parceiro. Use uma chave do sandbox enquanto experimenta, e a de produção só em máquina e cliente de confiança. O agente age como o parceiro: criar um documento consome a cota do plano e envia e-mail, SMS ou WhatsApp aos signatários.
• Sem servidor MCP hospedado. Não há endpoint MCP remoto nem OAuth; o servidor roda na máquina do cliente, com a chave do parceiro. Se isso mudar, o changelog anuncia.

Formatos para modelos de linguagem

Um modelo não precisa executar JavaScript para ler esta documentação:

As páginas HTML também negociam conteúdo: uma requisição com Accept: text/markdown para https://api.letssign.com.br/docs, para a página de uma versão ou para um guia recebe o Markdown na mesma URL. Um agente que vai integrar a API deve começar por llms.txt, ler o Quickstart e a referência da versão que vai usar, e consultar o documento OpenAPI para schemas exatos.

Sandbox

Sandbox e produção são ambientes separados, com hosts, contas, parceiros e chaves distintos: uma chave do sandbox não funciona em produção, e vice-versa. Documentos, signatários e webhooks criados no sandbox ficam lá.

• Endereços. No LetsSign, a API do sandbox está em https://sandbox.api.letssign.com.br/, com a documentação em https://sandbox.api.letssign.com.br/docs, e o aplicativo em https://sandbox.app.letssign.com.br/. Em outros labels, peça os endereços ao suporte.
• Chave. A chave do sandbox é obtida como a de produção: emitida no cadastro do parceiro pela equipe LetsSign ou gerada pela própria conta na área de integrações do aplicativo do sandbox (a conta precisa da feature integrations). Não há chave pública compartilhada: cada parceiro usa a própria. Para conseguir uma conta no sandbox, escreva para atendimento@letssign.com.br.
• Formatos. Cada host gera a própria documentação, então a coleção Postman e o documento OpenAPI servidos pelo sandbox já apontam para o sandbox; use-os como baseUrl e --api-base-url ao configurar ferramentas contra ele.
• Comportamento. O sandbox roda a mesma versão da API, com as mesmas regras de plano, cotas e features. Use signatários com e-mails que você controla: as notificações são enviadas de verdade.

Como um agente deve operar a API

Orientações para um agente (ou para quem escreve o prompt de um) que vai chamar a API:

1. Descubra antes de agir. Liste as contas do parceiro (partners_v1_accounts_list) e use o id devolvido como accountId; nunca invente ou reutilize identificadores de outro ambiente. Confira as features da conta (partners_v1_features_list) antes de operações que exigem documents_signatures, integrations ou outras.
2. Chame pelo operationId. É o nome estável de cada operação em ferramentas, coleção e referência. Quando um endpoint existir na v2, prefira a v2; os obsoletos indicam o substituto na descrição.
3. Trate 400 e 422 como definitivos. Repetir a mesma requisição produz o mesmo erro; leia errors e problems do Problem Details e corrija o payload. 401 é configuração (chave, ambiente, vínculo da conta); 403 é feature ausente no plano.
4. Criar documento não é idempotente. Cada POST de envio para assinatura cria um documento novo, consome cota e notifica os signatários. Se a resposta se perder, procure o documento (partners_v2_documents_list, filtrando por nome e data) antes de repetir. Confirme com quem opera antes de criar, cancelar ou remover algo em produção.
5. Arquivos vão em base64 dentro do JSON, com o contentType; downloads devolvem uma URL temporária, válida por poucos minutos, e não o binário.
6. Acompanhe por webhook, não por consulta em laço. Cadastre a URL uma vez (partners_v1_webhooks_create) e reaja aos eventos; use a consulta de status só para conferir.
7. Datas em ISO 8601 com fuso explícito, identificadores em UUID, enums pelos nomes exatos do schema ("Email", "WhatsApp").
8. Comece no sandbox. Só aponte para produção quando o fluxo estiver validado.