# 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.

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