# 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](https://api.letssign.com.br/docs/partners-v1/openapi.json), [v2](https://api.letssign.com.br/docs/partners-v2/openapi.json)): 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:

| Versão | Coleção |
|---|---|
| Partners API v1 | `https://api.letssign.com.br/docs/partners/v1.postman_collection.json` |
| Partners API v2 | `https://api.letssign.com.br/docs/partners/v2.postman_collection.json` |

**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`](https://github.com/ivo-toby/mcp-openapi-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`):

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

```bash
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](https://api.letssign.com.br/docs/guides/changelog) anuncia.

## Formatos para modelos de linguagem

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

| Arquivo | Conteúdo |
|---|---|
| `https://api.letssign.com.br/llms.txt` | Índice curto, no formato [llmstxt.org](https://llmstxt.org): resumo da API e links para guias, referências e formatos. |
| `https://api.letssign.com.br/llms-full.txt` | O índice seguido de todos os guias e da referência completa das duas versões, em um único Markdown. |
| `https://api.letssign.com.br/docs/index.json` | Documentos e guias com título, versão, contagens e a URL de cada formato, para descoberta automática. |
| `https://api.letssign.com.br/docs/partners/v1.md`, `https://api.letssign.com.br/docs/partners/v2.md` | A referência de cada versão em Markdown: introdução, autenticação, índice de operações, operações por tag, eventos de webhook e schemas. |

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](https://api.letssign.com.br/docs/guides/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.