# Genel Bilgiler

> 2328.io ile kripto para ödeme işleme ve çekim entegrasyonu için teknik şartname.

2328.io API dokümantasyonuna hoş geldiniz. Bu referans, kripto para ödeme işleme ve çekimleri uygulamanıza nasıl entegre edeceğinizi anlatır.

## Başlarken

Entegrasyona başlamak için:

1. [2328.io](https://2328.io) üzerinde bir merchant hesabı ve proje oluşturun
2. Proje ayarlarından **project UUID** ve **API key** değerlerini alın
3. Çekim özelliğini kullanmayı planlıyorsanız ayrı bir **Payout API key** oluşturun
4. İsteklerin nasıl imzalanacağını öğrenmek için [Authentication](/docs/authentication) bölümünü okuyun
5. İlk [Create Payment](/docs/payments) çağrınızı yapın

## Base URL

Tüm production API istekleri aşağıdaki base URL'i kullanır:

```
https://api.2328.io/api
```

> **WARNING:** Tüm istekler **HTTPS** üzerinden yapılmalıdır. HTTPS kullanmayan istekler engellenir.

## Neler yapabilirsiniz

2328.io API ile şunları yapabilirsiniz:

- **Kripto ödemeleri kabul edin** — ödeme oturumları oluşturun ve müşterileri hosted checkout veya Telegram MiniApp'e yönlendirin
- **Para çekin** — merchant bakiyenizden herhangi bir blockchain adresine programatik olarak çekim yapın
- **Bakiye sorgulama** — para birimi başına satıcı hesap bakiyelerini, USD karşılıklarını ve AML tarafından kilitlenen tutarları görün
- **Statik cüzdanlar kullanın** — bir kullanıcıya veya siparişe bağlı kalıcı yatırma adresleri oluşturun
- **Döviz kurlarını alın** — fiat ve kripto çiftleri için gerçek zamanlı kurları alın
- **Webhook alın** — ödeme durumu değiştiğinde anında bildirim alın
## Hız limitleri

API, **proje başına saniyede 10 isteğe** kadar izin verir. Limiti aşan istekler HTTP `429 Too Many Requests` yanıtı alır — geri çekilin ve yeniden deneyin.

## Doğru entegrasyon desenini seçin

| Gereksinim | Önerilen desen | Neden |
|-------------|---------------------|-----|
| Müşterinin nasıl ödeyeceğini seçmesine izin verin | Hosted checkout | Bir ödeme oluşturun ve `result.url`'ya yönlendirin; 2328.io şu anda mevcut yönleri gösterir. |
| Müşteriyi kendi ödeme sayfanız içinde tutun | Doğrudan adres **H2H** invoice | Ödeme oluştururken `to_currency` ve `network` gönderin; döndürülen `address`, `payer_amount` ve `qr`'yi görüntüleyin. |
| Tam olarak `25 USDT` veya `0.001 BTC` tahsil edin | Kripto para birimi cinsinden invoice | Kripto para birimini `currency`'ya koyun ve tam ondalık miktarı `amount`'ye girin. |
| Her kullanıcıya tekrar kullanılabilir bir depozito adresi verin | Static wallet | Adres kalıcıdır ve birçok bağımsız depozitoyu alabilir. |
| Gelen varlıkları tek bir bakiye para birimine normalleştirin | Auto-convert | Proje kurallarını kontrol panelinde yapılandırın ve dönüşüm tamamlandığında `convert` sonucunu kullanın. |
| Mevcut bir merchant bakiyesini değiştirin | Manual convert | `/v1/convert/price` ile önizleyin, sonra `/v1/convert` ile yürütün. |
| Fonları bir blok zinciri adresine gönderin | Ödeme | Ayrı Payout API anahtarını kullanın, önce hesaplayın ve ödeme durumunu mutabakata bağlayın. |

> **INFO:** Hosted checkout ve H2H aynı Payment API’nin iki sunumudur. H2H daha zayıf veya imzasız bir ödeme oluşturmaz: backend yine invoice oluşturur, 2328.io yine adres ve durumu elinde tutar ve imzalı webhooks settlement için otoriter kalır.

## Entegrasyon sabitleri

Bu kurallar her production entegrasyonu için geçerlidir:

- **Yalnızca Backend** — API anahtarlarını tarayıcılar, mobil uygulamalar, günlükler, analizler ve destek ekran görüntülerinden uzak tutun.
- **Ondalık dizgiler** — parayı dizge olarak gönderin ve saklayın. Kripto para birimi veya döviz kurları ile ikili kayan nokta aritmetiği kullanarak asla yuvarlama yapmayın.
- **Değiştirilemez idempotency anahtarları** — ilk isteğin öncesinde `order_id` oluşturun ve istekle birlikte tüm isteği saklayın. Aynı `order_id` ile bir retry, değiştirilen alanları uygulamak yerine orijinal nesneyi döndürebilir.
- **Webhook-öncelikli settlement** — yönlendirmeler, istemci yoklamaları, kullanıcı tarafından sağlanan işlem karmaları ve HTTP zaman aşımı ödeme kanıtı değildir.
- **Doğrula, yineleneni kaldır, sonra değiştir** — HMAC’i doğrulayın, bir idempotency kaydını atomik olarak talep edin, siparişi/bakiye güncelleyin ve HTTP 200’ü hızlıca döndürün.
- **Reconciliation** — kaybolan webhook kalıcı anlaşmazlığa yol açmasın diye ödeme, statik cüzdan ve ödeme durumunu periyodik olarak sorgulayın.
- **Dinamik kullanılabilirlik** — para birimi/ağ çiftlerini `/v1/directions` ile doğrulayın; desteklenen bir varlık yine de tek yönlü bir yatırma veya çekme işlemi geçici olarak devre dışı olabilir.
- **Açık durum politikası** — ürününüzün kısmi ödeme, fazla ödeme, süresi dolmuş işlem, AML kilidi, dönüştürme fallback ve belirsiz üst akış zaman aşımı durumlarını canlıya geçmeden önce nasıl yöneteceğine karar verin.

## Saklanması önerilen veriler

Ödemeler için en az `uuid`, `order_id`, orijinal istek gövdesi, `amount`, `currency`, `payer_currency`, `payer_amount`, `network`, `address`, `expires_at`, en son `payment_status`, `txid`, `payment_amount`, `merchant_amount`, isteğe bağlı `convert` bloğu ve doğrulanmış ham webhook payload saklayın.

static wallets için cüzdanı `uuid`, adresi, para birimini, ağı, müşteri/hesap referansını, durumu ve geri arama URL'sini mevduat kayıtlarından ayrı tutun. Her mevduat kendi işlem `uuid`, `txid`, durumu, alınan miktarı, merchant miktarı ve dönüşüm sonucuna sahip olmalıdır.