# Integração assistida por IA

Se você usa Claude, Cursor, ChatGPT ou Copilot para escrever a integração, a ValidaPay oferece a documentação em formatos que a IA lê melhor que uma página web.

## Servidor MCP

```
https://docs.validapay.com.br/mcp
```

MCP (Model Context Protocol) é o padrão que permite à IA **consultar a documentação sob demanda**, em vez de depender do que memorizou no treinamento. Ela busca a rota, lê o contrato exato e valida o payload antes de te entregar o código.

Não é preciso credencial: o servidor só lê a documentação, não acessa sua conta nem cria cobranças.

### Instalação

**Claude Code**

```bash
claude mcp add --transport http validapay-docs https://docs.validapay.com.br/mcp
```

**Cursor** — em `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "validapay-docs": { "url": "https://docs.validapay.com.br/mcp" }
  }
}
```

**VS Code** — em `.vscode/mcp.json`:

```json
{
  "servers": {
    "validapay-docs": { "type": "http", "url": "https://docs.validapay.com.br/mcp" }
  }
}
```

**Claude Desktop e ChatGPT** — adicione a URL acima em Configurações › Conectores.

Depois de instalar, reinicie a sessão. A IA descobre as ferramentas ao iniciar; se o servidor for adicionado no meio de uma conversa, só aparece na próxima.

### O que a IA passa a poder fazer

| Ferramenta | Para quê |
|---|---|
| `search_docs` | Localizar rota, campo ou código de erro por assunto |
| `list_endpoints` | Ver o mapa da API, com scopes por rota |
| `get_endpoint` | Contrato exato: campos obrigatórios, valores aceitos, erros |
| `get_guide` | Fluxo completo — assinatura, split, webhooks, subconta |
| `validate_request` | Conferir o payload antes de você rodar o código |

O `validate_request` é o que mais evita retrabalho: ele aponta campo por campo o que está errado, incluindo regras que não aparecem no schema, como o trio obrigatório em cobranças com vencimento.

### Como pedir

Não precisa mencionar as ferramentas. Descreva o que quer:

> Crie um endpoint Node.js que gere uma cobrança Pix da ValidaPay com vencimento em 3 dias, vinculada ao pedido do meu sistema, e valide o payload antes de me entregar.

## Sem MCP

Se sua ferramenta não suporta MCP, cole a URL abaixo no chat — ela dá o índice da API inteira em texto:

```
https://docs.validapay.com.br/llms.txt
```

Outros recursos, todos públicos:

| Recurso | URL |
|---|---|
| Contrato OpenAPI 3.1 | `/openapi.json` |
| Documentação completa em texto | `/llms-full.txt` |
| Markdown de qualquer página | acrescente `.md` à URL |
| Collection Postman | `/collection.json` |
| Guia de integração para IA | `/api/ai-skill` |

## Gerando um SDK tipado

O `/openapi.json` alimenta geradores de cliente. Com um SDK tipado, o compilador barra o payload errado antes de a requisição sair:

```bash
npx @hey-api/openapi-ts -i https://docs.validapay.com.br/openapi.json -o src/validapay
```

## Limites

A IA acerta muito mais com essas ferramentas, mas continua sendo IA: **confira o código antes de subir para produção**, e teste em sandbox. Valores são sempre em reais, nunca em centavos — esse é o erro mais caro quando passa despercebido.