# Integracja z AI

> Zintegruj 2328.io ze swoją aplikacją w kilka minut, korzystając z asystentów AI takich jak Claude, ChatGPT, Cursor czy GitHub Copilot.

Dokumentacja 2328.io została zaprojektowana jako **przyjazna dla LLM**. Możesz przekazać całą referencję API dowolnemu nowoczesnemu asystentowi AI i otrzymać działającą integrację w wybranym języku — PHP, Node.js, Python, Go, Rust — w minutach zamiast godzin.

Ta strona wyjaśnia, jak zrobić to efektywnie.

## Dlaczego warto integrować przy pomocy AI

- **Szybsze wdrożenie** — pomijasz boilerplate i przechodzisz wprost do logiki biznesowej
- **Poprawne podpisywanie** — AI wiarygodnie odtwarza podpisywanie HMAC-SHA256 w dowolnym języku
- **Obsługa webhooków** — generuj weryfikację podpisu i idempotentne handlery od razu
- **Aktualne dane** — nasz `llms-full.txt` jest regenerowany przy każdej aktualizacji dokumentacji, dzięki czemu zawsze otrzymujesz bieżące schematy

## Dokumentacja czytelna dla maszyn

Publikujemy trzy endpointy zgodnie ze standardem [llmstxt.org](https://llmstxt.org):

| Endpoint | Przeznaczenie |
|----------|---------------|
| [`/llms.txt`](https://doc.2328.io/llms.txt) | Krótki indeks całej dokumentacji wraz z odnośnikami |
| [`/llms-full.txt`](https://doc.2328.io/llms-full.txt) | Pełna dokumentacja jako pojedynczy plik — wklej go do swojego czatu z AI |
| [`/md/{locale}/{slug}`](https://doc.2328.io/md/en/payments) | Dowolna strona w surowym formacie Markdown |

Każda strona HTML udostępnia również tag `<link rel="alternate" type="text/markdown">` wskazujący jej wersję Markdown, dzięki czemu crawlery AI odnajdują ją automatycznie.

## Szybki start z Claude lub ChatGPT

### Krok 1 — udostępnij dokumentację

Otwórz nowy czat i jako pierwszą wiadomość wklej zawartość pliku [`llms-full.txt`](https://doc.2328.io/llms-full.txt) lub po prostu udostępnij odnośnik, jeśli model potrafi go pobrać.

### Krok 2 — opisz swój stos technologiczny

Powiedz asystentowi, co budujesz:

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

### Krok 3 — zrecenzuj i przetestuj

Asystent wygeneruje kontroler, klasę serwisu i handler webhooka. Przed wdrożeniem:

- Zweryfikuj, że `apiSign()` koduje treść jako base64 **przed** HMAC-SHA256
- Sprawdź, czy handlery webhooków używają `hash_equals()` (a nie `===`) do porównywania podpisów
- Upewnij się, że handler jest idempotentny — przed zaksięgowaniem sprawdzaj `order_id` / `txid`
- Najpierw przetestuj na środowisku deweloperskim, używając niewielkiej, prawdziwej płatności

> **WARNING:** Nigdy nie wdrażaj kodu płatności wygenerowanego przez AI bez zrecenzowania logiki podpisywania i weryfikacji webhooków. To krytyczne granice bezpieczeństwa.

## Integracje z IDE

### Cursor

Dodaj dokumentację jako niestandardowe źródło docs w ustawieniach Cursor:

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

Następnie w czacie poprzedź pytanie prefiksem `@2328.io`:

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

### GitHub Copilot

Copilot Chat potrafi wczytać `llms-full.txt` bezpośrednio:

```
#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 / inni asystenci

Każdy asystent obsługujący kontekst URL lub załączanie plików działa w ten sam sposób — załącz `llms-full.txt` i opisz swój cel.

## Claude API (Agent SDK)

Jeśli budujesz własnego agenta lub chatbota, który ma komunikować się z 2328.io, jednorazowo wstrzyknij dokumentację do 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:** Pełny plik dokumentacji ma około 15 KB — znacznie poniżej limitu kontekstu nowoczesnych modeli. Możesz go zbuforować po swojej stronie i odświeżać raz dziennie.

## Przykładowe prompty, które działają dobrze

Skopiuj je do Claude, ChatGPT lub swojego AI IDE po udostępnieniu `llms-full.txt`:

**Pełna integracja backendu:**
```
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.
```

**Narzędzie do wypłat:**
```
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.
```

**Statyczny portfel dla depozytów użytkowników:**
```
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.
```

## Dobre praktyki integracji wspomaganej AI

- **Zaczynaj od `llms-full.txt`** — został zaprojektowany pod kontekst LLM, bez boilerplate'u
- **Bądź precyzyjny co do swojego stosu** — framework, wersja języka, ORM
- **Proś o testy** — AI dobrze radzi sobie z generowaniem testów jednostkowych dla logiki podpisywania
- **Dwukrotnie sprawdzaj obsługę błędów** — AI bywa, że pomija ścieżki niepowodzeń
- **Recenzuj kod podpisywania ręcznie** — to jedyny fragment, który *musi* być absolutnie poprawny
- **Odświeżaj okresowo** — jeśli nasze API ulegnie zmianie, ponownie pobierz `llms-full.txt` i ponów prompt