Convert API

Convert API, mağaza bakiyenizde tuttuğunuz para birimleri arasında güncel piyasa fiyatından dönüşüm yapmanızı sağlar — mağaza panelindeki Swap sekmesini çalıştıran aynı motor, artık backend'inizden çağrılabilir.

Dönüşüm fiyatı alma

{
  "state": 0,
  "result": {
    "success": true,
    "from_currency": "BTC",
    "to_currency": "USDT",
    "amount_type": "from",
    "from_amount": "0.01000000",
    "to_amount": "947.86690000",
    "effective_rate": "94786.69000000",
    "from_amount_usd": "947.87",
    "to_amount_usd": "947.87"
  }
}

curl -X POST https://api.2328.io/api/v1/convert/price \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Dönüşümü gerçekleştirme

{
  "state": 0,
  "result": {
    "id": 12345,
    "type": "manual",
    "status": "completed",
    "from_currency": "BTC",
    "to_currency": "USDT",
    "from_amount": "0.01000000",
    "requested_from_amount": "0.01000000",
    "refund_amount": null,
    "to_amount": "947.86690000",
    "exchange_rate": "94786.69000000",
    "fee_amount": "0.00000000",
    "from_amount_usd": "947.87",
    "to_amount_usd": "947.87",
    "processed_at": "2026-01-20T15:30:24Z",
    "created_at": "2026-01-20T15:30:22Z"
  }
}

curl -X POST https://api.2328.io/api/v1/convert \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Hatalar

Başarısızlık durumunda yanıt state: 1 ve bir error_code içerir — /v1/convert/price ve /v1/convert için ortak:

🔴 422 / 400 · application/json

{
  "state": 1,
  "error_code": "amount_too_small",
  "errors": {
    "amount": "Amount is too small for this conversion. Please increase the amount and try again."
  }
}

Gelen ödemelerin otomatik dönüştürülmesi

Auto-convert gelen invoice ve statik cüzdan kredileri için bir proje ayarıdır. Bu, /v1/payment alanları ekleyerek değil, merchant kontrol panelinde yapılandırılır. Her kural bir veya daha fazla kaynak para birimi ve bir hedef para birimi seçer.

Dönüşüm tamamlandığında, ödeme bilgileri ve merchant webhooks şunları içerebilir:

{
  "payment_amount": "0.14800000",
  "merchant_amount": "0.146520000000000000",
  "payer_currency": "XMR",
  "convert": {
    "to_currency": "USDT",
    "commission": "0.09000000",
    "rate": "323.21000000",
    "amount": "47.262015740000000000"
  }
}

Tutar alanları bilerek ayrı tutulmuştur:

• payment_amount — kaynak ödeme para biriminde zincirde tespit edilen;
• merchant_amount — dönüşüm öncesinde merchant'ye ait net kaynak tutarı;
• convert.amount — convert.to_currency'ye kredilenen tutar;
• convert.rate ve convert.commission — gerçekleştirilmiş dönüşüm sonucu, yerel olarak tekrar hesaplamanız gereken bir fiyat değildir.

Auto-convert hatası ve fallback

Dönüşüm, blok zinciri ödemesinin alınmasından sonradır. Piyasa uygunluğu, minimum sipariş boyutları, hassasiyet sınırları, değişim zaman aşımları ve yetersiz uygulanabilir likidite dönüşümü geciktirebilir veya engelleyebilir.

• Küresel/proje minimumunun altındaki mevduatlar dönüşüm hattını atlayarak kaynak para biriminde kredilenir.
• Geçici hatalar eşzamanlı olarak yeniden denenebilir.
• Büyük veya ticarete uygun olmayan mevduatlar, retry politikası tükendiğinde kaynak para birimi kredisine geri dönebilir.
• Bir ödeme, hedef para birimi dönüşümü gerçekleşmese bile geçerli olabilir.

Entegrasyonunuz önce doğrulanmış ödemeyi saklamalı ve ardından ödeme bilgileri, isteğe bağlı convert bloğu ve merchant bakiyelerinden gerçek kredilenen para birimini uzlaştırmalıdır. Kendi analiz veya bildirim sistemlerinizi beklerken ödemenin webhook kabulünü engellemeyin.

Auto-convert kabul testleri

En azından test edin: başarılı doğrudan dönüştürme, köprü/çok adımlı dönüştürme, minimumun altındaki dust, geçici retry, fallback kaynağa çevrim, eksik ödeme, fazla ödeme, yinelenen webhook, eksik convert ve belirsiz bir timeout sonrası reconciliation.

Manuel dönüştürme uç durumları

• /v1/convert/price bir göstergelik önizlemedir; piyasa hareketi uygulama sonucunu değiştirebilir.
• amount_type: from kaynak taraf talebini düzeltir, amount_type: to ise hedef taraf tutarını talep eder. Onay kullanıcı arayüzünü sunarken anlamını değiştirmeyin.
• Doğrudan piyasası olmayan bir çift, ara bir para birimi üzerinden yönlendirilebilir. Sadece bir adım tamamlanırsa, partially_completed ara krediyi raporlar.
• Eğer bir yürütme çağrısı zaman aşımına uğrarsa, yeniden denemeden önce uzlaştırma yapın. Bir piyasa emri, HTTP yanıtı kaybolsa bile gerçekleştirilebilir.
• failed’yi, yerel telafi bakiyesi girişi uygulama izni olarak değil, uzlaştırılacak bir durum olarak ele alın; platform borç/iade muhasebesine sahiptir.