# Integración con IA

> Integra 2328.io en tu aplicación en minutos usando asistentes de IA como Claude, ChatGPT, Cursor y GitHub Copilot.

La documentación de 2328.io está pensada para ser **LLM-friendly**. Puedes pasarle la referencia completa de la API a cualquier asistente de IA moderno y hacer que genere una integración funcional en el lenguaje que prefieras — PHP, Node.js, Python, Go, Rust — en minutos en lugar de horas.

Esta página explica cómo hacerlo de forma eficiente.

## Por qué usar IA para integrar

- **Onboarding más rápido** — sáltate el boilerplate y ve directo a la lógica de negocio
- **Firma correcta** — la IA reproduce de forma fiable la firma HMAC-SHA256 en cualquier lenguaje
- **Manejadores de webhook** — genera verificación de firma y manejadores idempotentes listos para usar
- **Siempre al día** — nuestro `llms-full.txt` se regenera con cada actualización de la documentación, así siempre obtienes los esquemas vigentes

## Documentación legible por máquina

Publicamos tres endpoints siguiendo el estándar [llmstxt.org](https://llmstxt.org):

| Endpoint | Propósito |
|----------|-----------|
| [`/llms.txt`](https://doc.2328.io/llms.txt) | Índice corto de toda la documentación con enlaces |
| [`/llms-full.txt`](https://doc.2328.io/llms-full.txt) | Documentación completa en un solo archivo — pégalo en tu chat con la IA |
| [`/md/{locale}/{slug}`](https://doc.2328.io/md/en/payments) | Cualquier página como Markdown sin procesar |

Cada página HTML también expone `<link rel="alternate" type="text/markdown">` apuntando a su versión en Markdown, para que los crawlers de IA la descubran automáticamente.

## Inicio rápido con Claude o ChatGPT

### Paso 1 — Proporciona la documentación

Abre un chat nuevo y pega el contenido de [`llms-full.txt`](https://doc.2328.io/llms-full.txt) como tu primer mensaje, o simplemente comparte el enlace si el modelo puede descargarlo.

### Paso 2 — Describe tu stack

Dile al asistente qué estás construyendo:

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

### Paso 3 — Revisa y prueba

El asistente generará un controlador, una clase de servicio y un manejador de webhook. Antes de desplegar:

- Verifica que `apiSign()` codifica el cuerpo en Base64 **antes** de HMAC-SHA256
- Comprueba que los manejadores de webhook usan `hash_equals()` (no `===`) para comparar firmas
- Asegúrate de que el manejador es idempotente — verifica `order_id` / `txid` antes de acreditar
- Prueba primero con un pago real pequeño en un entorno de desarrollo

> **WARNING:** Nunca despliegues código de pagos generado por IA sin revisar la lógica de firma y verificación de webhooks. Esos son los límites de seguridad críticos.

## Integraciones con IDE

### Cursor

Añade la documentación como una fuente de docs personalizada en la configuración de Cursor:

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

Después, en el chat, antepón `@2328.io` a tu pregunta:

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

### GitHub Copilot

Copilot Chat puede leer `llms-full.txt` directamente:

```
#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 / otros asistentes

Cualquier asistente que admita contexto por URL o adjuntos de archivos funciona igual — adjunta `llms-full.txt` y describe tu objetivo.

## Claude API (Agent SDK)

Si estás construyendo tu propio agente o chatbot que necesita interactuar con 2328.io, inyecta la documentación una vez en el 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:** El archivo de documentación completo pesa ~15 KB — muy por debajo del límite de contexto de cualquier modelo moderno. Puedes cachearlo de tu lado y refrescarlo una vez al día.

## Ejemplos de prompts que funcionan bien

Cópialos en Claude, ChatGPT o tu IDE con IA tras compartir `llms-full.txt`:

**Integración backend completa:**
```
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.
```

**Herramienta de retiros:**
```
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.
```

**Monedero estático para depósitos de usuarios:**
```
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.
```

## Buenas prácticas para integraciones asistidas por IA

- **Empieza por `llms-full.txt`** — está diseñado como contexto para LLMs, sin boilerplate
- **Sé específico sobre tu stack** — framework, versión del lenguaje, ORM
- **Pide tests** — la IA es buena generando tests unitarios para la lógica de firma
- **Revisa el manejo de errores** — la IA a veces omite las rutas de error
- **Revisa manualmente el código de firma** — esa es la única parte que *debe* ser exactamente correcta
- **Refresca periódicamente** — si cambia nuestra API, vuelve a descargar `llms-full.txt` y re-prompt