# AI Entegrasyonu

> Claude, ChatGPT, Cursor ve GitHub Copilot gibi AI asistanlarını kullanarak 2328.io'yu uygulamanıza dakikalar içinde entegre edin.

2328.io dokümantasyonu **LLM-friendly** olarak hazırlanmıştır. Tüm API referansını herhangi bir modern AI asistanına verebilir ve seçtiğiniz dilde — PHP, Node.js, Python, Go, Rust — saatler yerine dakikalar içinde çalışan bir entegrasyon ürettirebilirsiniz.

Bu sayfa, bunu nasıl verimli şekilde yapacağınızı anlatır.

## Entegrasyon için neden AI kullanmalı

- **Daha hızlı başlangıç** — boilerplate'i atlayın, doğrudan iş mantığına geçin
- **Doğru imzalama** — AI, herhangi bir dilde HMAC-SHA256 imzalamayı güvenilir biçimde yeniden üretir
- **Webhook handler'ları** — imza doğrulaması ve idempotent handler'ları kutudan çıktığı gibi üretin
- **Güncel** — `llms-full.txt` dosyamız her doküman güncellemesinde yeniden üretilir, böylece her zaman güncel şemaları alırsınız

## Makine tarafından okunabilir dokümanlar

[llmstxt.org](https://llmstxt.org) standardına uygun üç endpoint yayınlıyoruz:

| Endpoint | Amaç |
|----------|------|
| [`/llms.txt`](https://doc.2328.io/llms.txt) | Tüm dokümanların bağlantılarla birlikte kısa indeksi |
| [`/llms-full.txt`](https://doc.2328.io/llms-full.txt) | Tek bir dosya halinde tam dokümantasyon — bunu AI sohbetinize yapıştırın |
| [`/md/{locale}/{slug}`](https://doc.2328.io/md/en/payments) | Herhangi bir sayfanın ham Markdown hali |

Her HTML sayfası ayrıca Markdown sürümüne işaret eden `<link rel="alternate" type="text/markdown">` etiketini de açığa çıkarır, böylece AI tarayıcıları bunu otomatik olarak keşfeder.

## Dokümantasyon MCP sunucusu

[Model Context Protocol](https://modelcontextprotocol.io)]'i destekleyen yapay zeka ajanları doğrudan şu adreslere bağlanabilir:

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

Uç nokta halka açıktır, sadece okunabilir ve merchant API anahtarı gerektirmez. Sadece dokümantasyon bilgisi sunar; Bakiyeleri inceleyemez, ödeme oluşturamaz veya fon hareketi yapamaz.

Genel uzaktan MCP konfigürasyonu:

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

Tam yapılandırma sözdizimi MCP istemcisine göre değişir. Streamable HTTP kullanın ve istemciyi yukarıdaki URL'ye yönlendirin.

### MCP araçları

| Araç | Bir ajanın ne zaman kullanması gerekir |
|------|------------------------------|
| `list_docs` | Tüm dokümantasyon konularını ve kaynak URI'lerini keşfedin. |
| `search_docs` | Bölüm düzeyinde cevapları sıralanmış alıntılar ve doğrudan kaynak bağlantılarıyla bulun. |
| `get_doc` | Bir sayfanın tamamı taşınabilir Markdown versiyonunu okuyun. |
| `get_integration_guide` | hosted checkout, H2H, tam kripto invoices, static wallets, auto-convert, manual convert veya ödemeler için rehberli bir plan oluşturun. |

Tüm araç sonuçları yapılandırılmış JSON ve insan tarafından okunabilir metin içerir. Arama sonuçları `resource_link` öğeleri geri döner, böylece ajanlar tüm korpusu yüklemek yerine sadece ihtiyaç duydukları sayfaları getirebilir.

### MCP kaynakları

| Kaynak | Amaç |
|----------|---------|
| `docs://2328/index` | Makine tarafından okunabilir hizmet ve belge indeksi. |
| `docs://2328/en/full` | Paylaşılan kod parçaları ile tam İngilizce entegrasyon referansı genişletildi. |
| `docs://2328/{locale}/{slug}` | Bir lokelize sayfa; eksik çeviriler İngilizceye geri dönüyor. |

Kaynak şablonu, uyumlu istemcilerin tahmin etmeden geçerli URI'leri keşfetmesini sağlayan yerel ve slug tamamlamayı destekler.

### MCP uyarıları

- `integrate-2328` bir ajana doğru rehberi okumasını ve uygulama kodu, testler, yapılandırma ve bir canlandırma kontrol listesi üretmesini söyler.
- `review-2328-integration` bir temsilciden imza, kiracı/proje kapsamı, ondalık işleme, idempotency, webhook sıralama, belirsiz zaman aşımları ve reconciliation boşluklar için mevcut kodu incelemesini ister.

### Önerilen ajan iş akışı

1. Seçilen entegrasyon deseni için `get_integration_guide` kullanın.
2. MCP kaynakları veya `get_doc` ile bağlantılı her sayfayı okuyun.
3. Framework'e özel veya uç durum soruları için `search_docs` kullanın.
4. İmza ve webhook testlerini API calls öncesinde uygulayın.
5. Sonucu `review-2328-integration` ile gözden geçirin.
6. Kontrollü bir ortamda küçük gerçek işlemleri test edin; MCP dokümantasyonuna erişim, production API bağlantısını kanıtlamaz.

> **WARNING:** Dokümantasyon MCP, entegrasyon bilgi kaynağıdır, bir cüzdan MCP değildir. API anahtarlarını, ödeme anahtarlarını, webhook gizli bilgilerini, müşteri kişisel verilerini veya production yüklerini asla araç argümanlarına veya istemlere yapıştırmayın.

## Claude veya ChatGPT ile hızlı başlangıç

### Adım 1 — Dokümanları sağlayın

Yeni bir sohbet açın ve [`llms-full.txt`](https://doc.2328.io/llms-full.txt) içeriğini ilk mesajınız olarak yapıştırın; ya da model bağlantıyı çekebiliyorsa sadece bağlantıyı paylaşın.

### Adım 2 — Stack'inizi tanımlayın

Asistana ne inşa ettiğinizi söyleyin:

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

### Adım 3 — Gözden geçirin ve test edin

Asistan bir controller, bir service sınıfı ve bir webhook handler üretecektir. Yayına almadan önce:

- `apiSign()`'ın gövdeyi HMAC-SHA256'dan **önce** Base64 ile encode ettiğini doğrulayın
- Webhook handler'larının imzaları karşılaştırırken `hash_equals()` (değil `===`) çağırdığını kontrol edin
- Handler'ın idempotent olduğundan emin olun — alacaklandırmadan önce `order_id` / `txid` kontrol edin
- Önce dev ortamda küçük bir gerçek ödeme ile test edin

> **WARNING:** İmzalama ve webhook doğrulama mantığını gözden geçirmeden AI tarafından üretilen ödeme kodunu asla yayınlamayın. Bunlar kritik güvenlik sınırlarıdır.

## IDE entegrasyonları

### Cursor

Cursor ayarlarında dokümanları özel doküman kaynağı olarak ekleyin:

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

Ardından sohbette sorunuzun başına `@2328.io` ekleyin:

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

### GitHub Copilot

Copilot Chat, `llms-full.txt`'yi doğrudan okuyabilir:

```
#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 / diğer asistanlar

URL bağlamı veya dosya eki destekleyen herhangi bir asistan aynı şekilde çalışır — `llms-full.txt`'yi ekleyin ve hedefinizi tanımlayın.

## Claude API (Agent SDK)

2328.io ile etkileşim kurması gereken kendi agent veya chatbot'unuzu inşa ediyorsanız, dokümanları system prompt'a bir kez enjekte edin:

```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:** Tam doküman dosyası ~15 KB civarındadır — herhangi bir modern modelin context limitinin çok altında. Kendi tarafınızda cache'leyebilir ve günde bir kez yenileyebilirsiniz.

## İyi sonuç veren örnek prompt'lar

`llms-full.txt`'yi paylaştıktan sonra Claude, ChatGPT veya AI IDE'nize bunları kopyalayın:

**Tam backend entegrasyonu:**
```
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.
```

**Çekim aracı:**
```
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.
```

**Kullanıcı yatırımları için statik cüzdan:**
```
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.
```

## AI destekli entegrasyon için en iyi uygulamalar

- **`llms-full.txt`'den başlayın** — LLM context için tasarlandı, boilerplate yok
- **Stack'iniz hakkında spesifik olun** — framework, dil sürümü, ORM
- **Test isteyin** — AI, imzalama mantığı için unit testler üretmede iyidir
- **Hata yönetimini iki kez kontrol edin** — AI bazen başarısızlık yollarını atlar
- **İmza kodunu manuel olarak gözden geçirin** — *kesinlikle* doğru olması gereken tek kısım budur
- **Düzenli olarak yenileyin** — API'miz değişirse, `llms-full.txt`'yi yeniden alın ve yeniden prompt edin