# AI-integratie

> Integreer 2328.io binnen enkele minuten in je applicatie met behulp van AI-assistenten zoals Claude, ChatGPT, Cursor en GitHub Copilot.

De 2328.io-documentatie is gebouwd om **LLM-vriendelijk** te zijn. Je kunt de volledige API-referentie aan elke moderne AI-assistent geven en deze laten genereren een werkende integratie in de taal van jouw keuze — PHP, Node.js, Python, Go, Rust — in minuten in plaats van uren.

Op deze pagina lees je hoe je dat efficiënt doet.

## Waarom AI gebruiken om te integreren

- **Sneller onboarden** — sla boilerplate over, ga direct naar de business logic
- **Correct ondertekenen** — AI reproduceert HMAC-SHA256-ondertekening betrouwbaar in elke taal
- **Webhook-handlers** — genereer kant-en-klaar handtekeningverificatie en idempotente handlers
- **Up-to-date** — onze `llms-full.txt` wordt bij elke documentatie-update opnieuw gegenereerd, zodat je altijd actuele schema's krijgt

## Machine-leesbare documentatie

We publiceren drie endpoints volgens de [llmstxt.org](https://llmstxt.org)-standaard:

| Endpoint | Doel |
|----------|------|
| [`/llms.txt`](https://doc.2328.io/llms.txt) | Korte index van alle docs met links |
| [`/llms-full.txt`](https://doc.2328.io/llms-full.txt) | Volledige documentatie als één bestand — plak dit in je AI-chat |
| [`/md/{locale}/{slug}`](https://doc.2328.io/md/en/payments) | Elke pagina als ruwe Markdown |

Elke HTML-pagina toont ook een `<link rel="alternate" type="text/markdown">` die naar de Markdown-versie wijst, zodat AI-crawlers deze automatisch ontdekken.

## Documentatie MCP-server

AI-agents die de [Model Context Protocol](https://modelcontextprotocol.io) ondersteunen, kunnen rechtstreeks verbinding maken met:

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

Het eindpunt is openbaar, alleen-lezen en vereist geen merchant API-sleutel. Het dient alleen voor documentatiekennis; het kan geen saldi bekijken, betalingen aanmaken of geld verplaatsen.

Generieke remote-MCP-configuratie:

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

De exacte configuratiesyntaxis varieert per MCP-client. Gebruik Streamable HTTP en wijs de client naar de bovenstaande URL.

### MCP-tools

| Tool | Wanneer een agent deze moet gebruiken |
|------|------------------------------|
| `list_docs` | Ontdek alle documentatietopics en resource-URI's. |
| `search_docs` | Vind sectieniveau-antwoorden met gerangschikte uittreksels en directe resourcelinks. |
| `get_doc` | Lees de volledige draagbare-Markdown versie van één pagina. |
| `get_integration_guide` | Bouw een begeleid plan voor gehoste checkout, H2H, exacte crypto-facturen, statische wallets, automatische conversie, handmatige conversie of uitbetalingen. |

Alle toolresultaten bevatten gestructureerde JSON evenals voor mensen leesbare tekst. Zoekresultaten geven `resource_link` items terug zodat agents alleen de pagina's kunnen ophalen die ze nodig hebben in plaats van de hele corpus te laden.

### MCP bronnen

| Bron | Doel |
|----------|---------|
| `docs://2328/index` | Machine-leesbare service- en documentindex. |
| `docs://2328/en/full` | Volledige Engelstalige integratiereferentie met gedeelde codefragmenten uitgebreid. |
| `docs://2328/{locale}/{slug}` | Eén gelokaliseerde pagina; ontbrekende vertalingen vallen terug op Engels. |

De resourcetemplate ondersteunt locale en slug-completie, waardoor compatibele clients geldige URI's kunnen ontdekken zonder te raden.

### MCP prompts

- `integrate-2328` vertelt een agent om de juiste handleiding te lezen en implementatiecode, tests, configuratie en een checklist voor livegang te produceren.
- `review-2328-integration` vraagt een agent om bestaande code te beoordelen op ondertekening, tenant-/projectscope, decimale verwerking, idempotentie, webhook-volgorde, dubbelzinnige time-outs en reconciliatiehiaten.

### Aanbevolen agentworkflow

1. Gebruik `get_integration_guide` voor het geselecteerde integratiepatroon.
2. Lees elke gekoppelde pagina met MCP-middelen of `get_doc`.
3. Gebruik `search_docs` voor framework-specifieke vragen of randgevalsvragen.
4. Implementeer ondertekening en webhook-tests vóór API-aanroepen.
5. Beoordeel het resultaat met `review-2328-integration`.
6. Test kleine echte transacties in een gecontroleerde omgeving; toegang tot MCP-documentatie bewijst geen productie-API-connectiviteit.

> **WARNING:** De MCP-documentatie is een bron voor integratiekennis, geen wallet MCP. Plak nooit API-sleutels, payout-sleutels, webhook-geheimen, persoonlijke gegevens van klanten of productielast in toolargumenten of prompts.

## Snelle start met Claude of ChatGPT

### Stap 1 — Lever de docs aan

Open een nieuwe chat en plak de inhoud van [`llms-full.txt`](https://doc.2328.io/llms-full.txt) als je eerste bericht, of deel gewoon de link als het model deze kan ophalen.

### Stap 2 — Beschrijf je stack

Vertel de assistent wat je aan het bouwen bent:

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

### Stap 3 — Beoordeel en test

De assistent produceert een controller, een serviceklasse en een webhook-handler. Vóór je live gaat:

- Verifieer dat `apiSign()` de body als base64 codeert **vóór** HMAC-SHA256
- Controleer of webhook-handlers `hash_equals()` aanroepen (niet `===`) om handtekeningen te vergelijken
- Zorg dat de handler idempotent is — controleer `order_id` / `txid` voordat je bijboekt
- Test eerst met een kleine echte betaling op een dev-omgeving

> **WARNING:** Stuur AI-gegenereerde betalingscode nooit live zonder de logica voor ondertekening en webhook-verificatie te beoordelen. Dat zijn de kritieke beveiligingsgrenzen.

## IDE-integraties

### Cursor

Voeg de docs toe als aangepaste docs-bron in de Cursor-instellingen:

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

Voeg vervolgens in chat `@2328.io` als prefix aan je vraag toe:

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

### GitHub Copilot

Copilot Chat kan `llms-full.txt` direct lezen:

```
#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 / andere assistenten

Elke assistent die een URL-context of bestandsbijlage ondersteunt, werkt op dezelfde manier — voeg `llms-full.txt` toe en beschrijf je doel.

## Claude API (Agent SDK)

Als je je eigen agent of chatbot bouwt die met 2328.io moet werken, injecteer je de docs één keer in de 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:** Het volledige documentatiebestand is ~15 KB — ruim onder de contextlimiet van elk modern model. Je kunt het aan jouw kant cachen en eens per dag verversen.

## Voorbeelden van prompts die goed werken

Kopieer deze in Claude, ChatGPT of je AI-IDE nadat je `llms-full.txt` hebt gedeeld:

**Volledige backend-integratie:**
```
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.
```

**Uitbetalingstool:**
```
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.
```

**Statische wallet voor stortingen door gebruikers:**
```
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 practices voor AI-ondersteunde integratie

- **Begin met `llms-full.txt`** — ontworpen voor LLM-context, geen boilerplate
- **Wees specifiek over je stack** — framework, taalversie, ORM
- **Vraag om tests** — AI is goed in het genereren van unit tests voor ondertekeningslogica
- **Controleer de foutafhandeling extra** — AI slaat soms foutpaden over
- **Beoordeel ondertekeningscode handmatig** — dit is het enige deel dat *exact* goed *moet* zijn
- **Ververs periodiek** — als onze API verandert, haal `llms-full.txt` opnieuw op en voer een nieuwe prompt uit