# Integração com IA

> Integre a 2328.io à sua aplicação em minutos usando assistentes de IA como Claude, ChatGPT, Cursor e GitHub Copilot.

A documentação da 2328.io foi feita para ser **amigável a LLMs**. Você pode entregar toda a referência da API a qualquer assistente de IA moderno e fazer com que ele gere uma integração funcional na linguagem de sua preferência — PHP, Node.js, Python, Go, Rust — em minutos, em vez de horas.

Esta página explica como fazer isso com eficiência.

## Por que usar IA para integrar

- **Onboarding mais rápido** — pule o boilerplate e vá direto para a lógica de negócio
- **Assinatura correta** — a IA reproduz HMAC-SHA256 de forma confiável em qualquer linguagem
- **Handlers de webhook** — gere verificação de assinatura e handlers idempotentes prontos para uso
- **Sempre atualizada** — nosso `llms-full.txt` é regenerado a cada atualização da documentação, então você sempre obtém os esquemas atuais

## Documentação legível por máquina

Publicamos três endpoints seguindo o padrão [llmstxt.org](https://llmstxt.org):

| Endpoint | Finalidade |
|----------|------------|
| [`/llms.txt`](https://doc.2328.io/llms.txt) | Índice curto de toda a documentação com links |
| [`/llms-full.txt`](https://doc.2328.io/llms-full.txt) | Documentação completa em um único arquivo — cole isso no seu chat de IA |
| [`/md/{locale}/{slug}`](https://doc.2328.io/md/en/payments) | Qualquer página em Markdown bruto |

Toda página HTML também expõe `<link rel="alternate" type="text/markdown">` apontando para sua versão Markdown, para que crawlers de IA a descubram automaticamente.

## Documentação do servidor MCP

Agentes de IA que suportam o [Model Context Protocol](https://modelcontextprotocol.io) podem se conectar diretamente a:

```
https://doc.2328.io/mcp
```

O endpoint é público, somente leitura e não exige chave de API de comerciante. Ele serve apenas para conhecimento de documentação; não pode inspecionar saldos, criar pagamentos ou transferir fundos.

Configuração genérica remota do MCP:

```json
{
  "mcpServers": {
    "2328-docs": {
      "url": "https://doc.2328.io/mcp"
    }
  }
}
```

A sintaxe exata da configuração varia conforme o cliente MCP. Use HTTP Streamable e aponte o cliente para o URL acima.

### Ferramentas MCP

| Ferramenta | Quando um agente deve usá-la |
|------|------------------------------|
| `list_docs` | Descobrir todos os tópicos de documentação e URIs de recursos. |
| `search_docs` | Encontre respostas no nível de seção com trechos ranqueados e links diretos para recursos. |
| `get_doc` | Leia a versão completa em Markdown portátil de uma página. |
| `get_integration_guide` | Crie um plano guiado para checkout hospedado, H2H, faturas cripto exatas, carteiras estáticas, conversão automática, conversão manual ou pagamentos. |

Todos os resultados da ferramenta incluem JSON estruturado, bem como texto legível por humanos. Resultados de pesquisa retornam `resource_link` itens para que os agentes possam buscar apenas as páginas de que precisam, em vez de carregar todo o corpus.

### Recursos MCP

| Recurso | Propósito |
|----------|---------|
| `docs://2328/index` | Índice de serviço e documentos legível por máquina. |
| `docs://2328/en/full` | Referência completa de integração em inglês com trechos de código compartilhados ampliados. |
| `docs://2328/{locale}/{slug}` | Uma página localizada; traduções ausentes retornam ao inglês. |

O modelo de recurso suporta conclusão de locale e slug, o que permite que clientes compatíveis descubram URIs válidas sem adivinhar.

### MCP solicita

- `integrate-2328` instrui um agente a ler o guia correto e produzir código de implementação, testes, configuração e uma checklist de lançamento.
- `review-2328-integration` pede a um agente para revisar o código existente quanto a assinatura, escopo de tenant/projeto, tratamento de decimais, idempotência, ordenação de webhooks, timeouts ambíguos e lacunas de reconciliação.

### Fluxo de trabalho recomendado para agente

1. Use `get_integration_guide` para o padrão de integração selecionado.
2. Leia todas as páginas vinculadas com recursos MCP ou `get_doc`.
3. Use `search_docs` para perguntas específicas de framework ou casos de borda.
4. Implemente testes de assinatura e webhook antes das chamadas de API.
5. Revise o resultado com `review-2328-integration`.
6. Teste pequenas transações reais em um ambiente controlado; o acesso à documentação MCP não prova conectividade da API em produção.

> **WARNING:** A documentação MCP é uma fonte de conhecimento de integração, não uma carteira MCP. Nunca cole chaves de API, chaves de pagamento, segredos de webhook, dados pessoais de clientes ou payloads de produção em argumentos de ferramentas ou prompts.

## Início rápido com Claude ou ChatGPT

### Passo 1 — Forneça a documentação

Abra um chat novo e cole o conteúdo de [`llms-full.txt`](https://doc.2328.io/llms-full.txt) como sua primeira mensagem, ou apenas compartilhe o link se o modelo conseguir fazer o fetch.

### Passo 2 — Descreva sua stack

Diga ao assistente o que você está construindo:

```
I'm building a Laravel 11 application. I need to:
1. Create a payment for an order (amount in USD, user pays in USDT TRC20)
2. Handle the webhook and credit the user's balance
3. Store payment records in a `payments` table

Use the 2328.io API above. Include HMAC signing, webhook signature
verification, and idempotency.
```

### Passo 3 — Revise e teste

O assistente vai produzir um controller, uma classe de service e um handler de webhook. Antes de subir para produção:

- Verifique se `apiSign()` codifica o corpo em base64 **antes** do HMAC-SHA256
- Confira se os handlers de webhook chamam `hash_equals()` (e não `===`) para comparar assinaturas
- Garanta que o handler é idempotente — verifique `order_id` / `txid` antes de creditar
- Teste primeiro com um pagamento real pequeno em ambiente de desenvolvimento

> **WARNING:** Nunca coloque em produção código de pagamento gerado por IA sem revisar a lógica de assinatura e verificação de webhooks. Esses são os limites críticos de segurança.

## Integrações com IDEs

### Cursor

Adicione a documentação como uma fonte personalizada nas configurações do Cursor:

```
Settings → Features → Docs → Add new doc
URL: https://doc.2328.io
```

Depois, no chat, prefixe sua pergunta com `@2328.io`:

```
@2328.io generate a webhook handler in Next.js App Router
with signature verification and idempotent credit logic
```

### GitHub Copilot

O Copilot Chat consegue ler `llms-full.txt` diretamente:

```
#fetch https://doc.2328.io/llms-full.txt

Using the 2328.io API docs above, implement a payout endpoint
in Express that withdraws USDT BEP20 to a user-supplied address.
```

### Windsurf / Continue / outros assistentes

Qualquer assistente que aceite contexto via URL ou anexo de arquivo funciona da mesma forma — anexe `llms-full.txt` e descreva seu objetivo.

## Claude API (Agent SDK)

Se você está construindo seu próprio agente ou chatbot que precisa interagir com a 2328.io, injete a documentação uma única vez no system prompt:

```python
from anthropic import Anthropic
import urllib.request

docs = urllib.request.urlopen(
    "https://doc.2328.io/llms-full.txt"
).read().decode()

client = Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    system=f"""You are an integration assistant for 2328.io.
Use the API reference below to answer questions and generate code.

<docs>
{docs}
</docs>""",
    messages=[
        {"role": "user", "content": "Write a Python function that creates a USDT payment"}
    ],
)

print(response.content[0].text)
```

> **INFO:** O arquivo completo da documentação tem cerca de 15 KB — bem dentro do limite de contexto de qualquer modelo moderno. Você pode cacheá-lo do seu lado e atualizá-lo uma vez por dia.

## Exemplos de prompts que funcionam bem

Cole estes prompts no Claude, ChatGPT ou na sua IDE de IA depois de compartilhar o `llms-full.txt`:

**Integração completa de backend:**
```
Build a Node.js + Express service that exposes two routes:
- POST /checkout → creates a 2328.io payment and returns the payment URL
- POST /webhook/2328 → verifies the signature and marks the order as paid
Use TypeScript, Zod for validation, and a simple in-memory store.
```

**Ferramenta de saque:**
```
Write a CLI in Go that takes a currency, network, amount, and address
and creates a payout via the 2328.io Payout API. Use a separate payout
API key from env. Poll the status endpoint until the payout is completed.
```

**Carteira estática para depósitos de usuários:**
```
I have a Django app where users deposit USDT TRC20 to top up their balance.
Each user should have a permanent deposit address. Implement this using
2328.io static wallets, including the webhook handler that credits their
balance when a deposit arrives.
```

## Boas práticas para integração assistida por IA

- **Comece pelo `llms-full.txt`** — ele foi pensado para o contexto de LLMs, sem boilerplate
- **Seja específico sobre sua stack** — framework, versão da linguagem, ORM
- **Peça testes** — a IA é boa em gerar testes unitários para a lógica de assinatura
- **Confira o tratamento de erros** — a IA às vezes pula caminhos de falha
- **Revise o código de assinatura manualmente** — esta é a única parte que *precisa* estar exatamente correta
- **Atualize periodicamente** — se nossa API mudar, refaça o fetch do `llms-full.txt` e reaplique o prompt