# Integrazione con l'AI

> Integra 2328.io nella tua applicazione in pochi minuti utilizzando assistenti AI come Claude, ChatGPT, Cursor e GitHub Copilot.

La documentazione di 2328.io è progettata per essere **LLM-friendly**. Puoi fornire l'intero riferimento API a qualsiasi assistente AI moderno e farti generare un'integrazione funzionante nel linguaggio che preferisci — PHP, Node.js, Python, Go, Rust — in minuti invece che ore.

Questa pagina spiega come farlo in modo efficiente.

## Perché usare l'AI per integrare

- **Onboarding più rapido** — salta il boilerplate, vai direttamente alla logica di business
- **Firma corretta** — l'AI riproduce in modo affidabile la firma HMAC-SHA256 in qualsiasi linguaggio
- **Handler webhook** — genera la verifica della firma e handler idempotenti pronti all'uso
- **Sempre aggiornato** — il nostro `llms-full.txt` viene rigenerato a ogni aggiornamento della documentazione, quindi ottieni sempre schemi attuali

## Documentazione leggibile dalle macchine

Pubblichiamo tre endpoint conformi allo standard [llmstxt.org](https://llmstxt.org):

| Endpoint | Scopo |
|----------|---------|
| [`/llms.txt`](https://doc.2328.io/llms.txt) | Indice sintetico di tutta la documentazione con i collegamenti |
| [`/llms-full.txt`](https://doc.2328.io/llms-full.txt) | Documentazione completa in un unico file — incollalo nella tua chat AI |
| [`/md/{locale}/{slug}`](https://doc.2328.io/md/en/payments) | Qualsiasi pagina come Markdown raw |

Ogni pagina HTML espone inoltre `<link rel="alternate" type="text/markdown">` che punta alla versione Markdown, in modo che i crawler AI la individuino automaticamente.

## Documentazione del server MCP

Gli agenti AI che supportano il [Model Context Protocol](https://modelcontextprotocol.io) possono connettersi direttamente a:

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

Il punto di accesso è pubblico, solo in lettura e non richiede la chiave API del commerciante. Serve solo per la conoscenza della documentazione; non può controllare saldi, creare pagamenti o trasferire fondi.

Configurazione generica del MCP remoto:

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

La sintassi esatta della configurazione varia a seconda del client MCP. Utilizzare HTTP streamable e indicare al client l'URL sopra.

### Strumenti MCP

| Strumento | Quando un agente dovrebbe usarlo |
|------|------------------------------|
| `list_docs` | Scoprire tutti gli argomenti della documentazione e le URI delle risorse. |
| `search_docs` | Trova risposte a livello di sezione con estratti classificati e collegamenti diretti alle risorse. |
| `get_doc` | Leggi la versione completa portatile-Markdown di una pagina. |
| `get_integration_guide` | Crea un piano guidato per il checkout ospitato, H2H, fatture crypto esatte, portafogli statici, auto-conversione, conversione manuale o pagamenti. |

Tutti i risultati degli strumenti includono JSON strutturato oltre al testo leggibile dall'uomo. I risultati della ricerca restituiscono `resource_link` elementi in modo che gli agenti possano recuperare solo le pagine necessarie invece di caricare l'intero corpus.

### Risorse MCP

| Risorsa | Scopo |
|----------|---------|
| `docs://2328/index` | Indice dei servizi e dei documenti leggibile dalla macchina. |
| `docs://2328/en/full` | Riferimento completo all'integrazione in inglese con frammenti di codice condivisi ampliati. |
| `docs://2328/{locale}/{slug}` | Una pagina localizzata; le traduzioni mancanti ricadono sull'inglese. |

Il modello di risorsa supporta il completamento di locale e slug, il che consente ai client compatibili di scoprire URI validi senza indovinare.

### Prompt MCP

- `integrate-2328` indica a un agente di leggere la guida corretta e produrre codice di implementazione, test, configurazione e una checklist per il go-live.
- `review-2328-integration` chiede a un agente di rivedere il codice esistente per firma, ambito tenant/progetto, gestione dei decimali, idempotenza, ordinamento webhook, timeout ambigui e lacune di riconciliazione.

### Flusso di lavoro agente consigliato

1. Usa `get_integration_guide` per il modello di integrazione selezionato.
2. Leggi ogni pagina collegata con risorse MCP o `get_doc`.
3. Usa `search_docs` per domande specifiche del framework o casi particolari.
4. Implementa test di firma e webhook prima delle chiamate API.
5. Rivedi il risultato con `review-2328-integration`.
6. Testa piccole transazioni reali in un ambiente controllato; l'accesso alla documentazione MCP non dimostra la connettività API di produzione.

> **WARNING:** La documentazione MCP è una fonte di conoscenza sull'integrazione, non un MCP wallet. Non incollare mai chiavi API, chiavi di pagamento, segreti webhook, dati personali dei clienti o payload di produzione negli argomenti o nei prompt dello strumento.

## Avvio rapido con Claude o ChatGPT

### Passo 1 — Fornisci la documentazione

Apri una nuova chat e incolla il contenuto di [`llms-full.txt`](https://doc.2328.io/llms-full.txt) come primo messaggio, oppure condividi semplicemente il link se il modello è in grado di recuperarlo.

### Passo 2 — Descrivi il tuo stack

Indica all'assistente cosa stai costruendo:

```
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 — Revisiona e testa

L'assistente produrrà un controller, una classe service e un handler webhook. Prima di rilasciare in produzione:

- Verifica che `apiSign()` codifichi il body in Base64 **prima** di HMAC-SHA256
- Controlla che gli handler webhook chiamino `hash_equals()` (non `===`) per confrontare le firme
- Assicurati che l'handler sia idempotente — verifica `order_id` / `txid` prima di accreditare
- Testa prima con un piccolo pagamento reale in un ambiente di sviluppo

> **WARNING:** Non rilasciare mai codice di pagamento generato dall'AI senza revisionare la logica di firma e di verifica del webhook. Questi sono i confini di sicurezza critici.

## Integrazioni IDE

### Cursor

Aggiungi la documentazione come fonte di documentazione personalizzata nelle impostazioni di Cursor:

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

Quindi nella chat anteponi alla tua domanda il prefisso `@2328.io`:

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

### GitHub Copilot

Copilot Chat è in grado di leggere direttamente `llms-full.txt`:

```
#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 / altri assistenti

Qualsiasi assistente che supporti un contesto URL o un allegato di file funziona allo stesso modo — allega `llms-full.txt` e descrivi il tuo obiettivo.

## Claude API (Agent SDK)

Se stai costruendo un tuo agente o chatbot che deve interagire con 2328.io, inietta la documentazione una sola volta nel 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:** Il file completo della documentazione pesa circa 15 KB — ben al di sotto del limite di contesto di qualsiasi modello moderno. Puoi memorizzarlo in cache lato tuo e aggiornarlo una volta al giorno.

## Esempi di prompt che funzionano bene

Copia questi prompt in Claude, ChatGPT o nel tuo IDE AI dopo aver condiviso `llms-full.txt`:

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

**Strumento per i prelievi:**
```
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.
```

**Wallet statico per i depositi degli utenti:**
```
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.
```

## Best practice per l'integrazione assistita dall'AI

- **Parti da `llms-full.txt`** — è progettato per il contesto degli LLM, senza boilerplate
- **Sii specifico sul tuo stack** — framework, versione del linguaggio, ORM
- **Chiedi i test** — l'AI è brava a generare unit test per la logica di firma
- **Verifica la gestione degli errori** — a volte l'AI salta i percorsi di errore
- **Revisiona manualmente il codice di firma** — è l'unica parte che *deve* essere esattamente corretta
- **Aggiorna periodicamente** — se la nostra API cambia, riscarica `llms-full.txt` e riproponi il prompt