> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goatpay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Integração com IA

> Use llms.txt, OpenAPI e a documentação GoatPay em assistentes de código e agentes

A GoatPay publica um índice otimizado para **LLMs** e assistentes de código. Com ele, Cursor, Claude, ChatGPT e agentes autônomos conseguem gerar integrações corretas sem adivinhar rotas ou formatos.

## Arquivos disponíveis

| Recurso         | URL                                                                          | Quando usar                            |
| --------------- | ---------------------------------------------------------------------------- | -------------------------------------- |
| **llms.txt**    | [docs.goatpay.com.br/llms.txt](https://docs.goatpay.com.br/llms.txt)         | Visão geral, mapa de rotas, convenções |
| **OpenAPI**     | [docs.goatpay.com.br/openapi.yaml](https://docs.goatpay.com.br/openapi.yaml) | Schemas, tipos e playground            |
| **Páginas .md** | Qualquer doc + `.md` no final da URL                                         | Detalhe de um endpoint ou guia         |

O `llms.txt` resume autenticação (`X-API-Key: gp_live_...`), envelope de resposta, módulos (PIX, cripto, conta, loja, subcontas) e o que **não** está no escopo v1.

## Cursor

### Adicionar como documentação (@Docs)

1. **Cursor Settings → Indexing & Docs → Add new doc**
2. URL: `https://docs.goatpay.com.br/llms.txt`
3. Opcional: adicione também `https://docs.goatpay.com.br/openapi.yaml`

No chat, referencie com `@Docs` ou cole o link do endpoint específico.

### Exemplo de prompt

```text theme={null}
@Docs Integre a GoatPay no meu backend Node.js:
1. Criar cobrança PIX com externalReference
2. Endpoint POST /webhook que valida x-goatpay-signature (HMAC-SHA256)
3. Marcar pedido como pago no evento payment.paid

Use X-API-Key, base https://api.goatpay.com.br/v1 e o envelope { success, data, requestId }.
```

### Regras do projeto (.cursor/rules)

Crie uma regra curta no repositório do integrador:

```markdown theme={null}
# GoatPay API
- Base: https://api.goatpay.com.br/v1
- Auth: header X-API-Key (gp_live_...)
- Respostas: envelope JSON com success, message, data, requestId
- Webhooks: validar x-goatpay-signature no raw body com whsec_
- Docs: https://docs.goatpay.com.br/llms.txt
- OpenAPI: https://docs.goatpay.com.br/openapi.yaml
```

## Claude (Projects)

1. Crie um **Project** para sua integração GoatPay
2. Em **Project knowledge**, adicione:
   * `https://docs.goatpay.com.br/llms.txt`
   * `openapi.yaml` (baixe ou use URL)
3. Nas instruções do projeto, inclua:

```text theme={null}
Sempre consulte a documentação GoatPay antes de sugerir rotas.
Trilho PADRAO vem da API key, não do body.
Não invente campos provider, accountId ou metadata — não existem na API pública.
```

## ChatGPT e outros

* **Custom instructions / GPT:** cole o conteúdo de `llms.txt` ou aponte a URL
* **API / Agents:** busque `llms.txt` no início da sessão e mantenha `openapi.yaml` para schemas
* **MCP:** se o servidor suportar fetch de URL, registre `docs.goatpay.com.br/llms.txt` como fonte

## O que pedir à IA (e o que evitar)

### Boas práticas

| Faça                                                             | Por quê                                   |
| ---------------------------------------------------------------- | ----------------------------------------- |
| Cite `externalReference` em cobranças                            | Reconciliação com seu ERP                 |
| Valide webhook no **raw body**                                   | Re-serializar JSON quebra o HMAC          |
| Use permissões mínimas na chave                                  | Segurança e princípio do menor privilégio |
| Aponte para o guia de [webhooks](/api-reference/guides/webhooks) | Eventos e retentativas oficiais           |
| Confirme verificação KYC aprovada                                | Reembolso e MED exigem conta verificada   |

### Evite

| Não faça                                    | Motivo                                   |
| ------------------------------------------- | ---------------------------------------- |
| Polling agressivo em `GET /payment-pix/get` | Use webhooks; rate limit 100/min         |
| Assumir sandbox                             | Só produção; teste com valores baixos    |
| Enviar `pixRail` no body                    | Trilho vem da API key                    |
| Documentar rotas fora do llms.txt v1        | Boleto, assinaturas, bureau = doc futura |

## Fluxo sugerido para agentes

```mermaid theme={null}
flowchart LR
  A[llms.txt] --> B{Qual módulo?}
  B -->|PIX| C[Guia PIX + endpoint create]
  B -->|Webhook| D[Guia webhooks + HMAC]
  B -->|Loja| E[Guia loja + payment-links]
  C --> F[openapi.yaml schemas]
  D --> F
  E --> F
```

1. Leia `llms.txt` para escopo e convenções
2. Abra o guia do módulo (ex. `/api-reference/guides/pix.md`)
3. Use `openapi.yaml` para tipos de request/response
4. Gere código e teste com valor baixo

## Links úteis

<CardGroup cols={2}>
  <Card title="llms.txt" icon="file-lines" href="https://docs.goatpay.com.br/llms.txt">
    Índice para LLMs
  </Card>

  <Card title="OpenAPI" icon="code" href="https://docs.goatpay.com.br/openapi.yaml">
    Contrato completo
  </Card>

  <Card title="Primeira integração" icon="rocket" href="/pages/guides/primeira-integracao">
    Tutorial hands-on
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/pages/guides/troubleshooting">
    Erros comuns
  </Card>
</CardGroup>