Developers

Emirler ve idempotans

Bir sipariş oluşturmak kuru kilitler ve bir yatırma adresi atar. Entegrasyon hatasının para taşıdığı tek yer burasıdır: idempotans orada bir kolaylık değildir.

Yayınlanmış sözleşme, henüz açık değil

Bu uç noktalar bugün açık değildir. Entegrasyonunuzu önceden oluşturabilmeniz için belgelenmiştir; şekilleri kesinleşmiştir ve herhangi bir kırıcı değişiklik yeni bir sürüm ve bir değişiklik günlüğü girişi gerektirecektir.

POST/api/v1/ordersPublished contract, not open

Bir emir oluştur

Kuru kilitler ve özel bir yatırma adresi döndürür. Emir, kilitli dökümü taşır: tekrar oynatılabilir, bu da aylar sonra bile uygulanan tam fiyatı yeniden oluşturmanızı sağlar. Idempotency-Key başlığı zorunludur.

Kimlik doğrulama: Authorization: Bearer … Kimlik doğrulamaya bakın

Parametreler

Parametreler
Alan	Tür	Açıklama
`quoteId`gerekli	string	Kabul edilen fiyat teklifinin tanımlayıcısı.
`beneficiary`gerekli	object	Kanal şemasının dayattığı alanlar. Ad, doğrulanmış kimlikle eşleşmelidir: üçüncü taraf ödemeleri yoktur.
`networkId`gerekli	string	Yatırmanın gönderileceği ağ. Döndürülen adresi ve bazı ağlarda zorunlu notu belirler.

İstekbash

curl -sS -X POST https://fiatside.com/api/v1/orders \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Idempotency-Key: 7f3a1c92-5d0e-4a1b-9c2f-6b8e0d4a1f33' \
  -H 'Content-Type: application/json' \
  -d '{
    "quoteId": "qt_01J9Z...",
    "networkId": "tron",
    "beneficiary": {
      "railId": "sepa_instant",
      "beneficiaryName": "Camille Dupont",
      "iban": "FR7630001007941234567890185"
    }
  }'

Yanıt — yayınlanan sözleşmejson

{
  "reference": "K7Q4-M2XB",
  "state": "AWAITING_DEPOSIT",
  "deposit": {
    "asset": "USDT",
    "network": "tron",
    "address": "T...",
    "memo": null,
    "amountBase": "1000000000",
    "expiresAt": "2026-09-02T12:41:00Z"
  },
  "payout": { "railId": "sepa_instant", "netMinor": 91228, "currency": "EUR" },
  "rateLock": { "midRate": "0.92168430", "lockedUntil": "2026-09-02T12:41:00Z" }
}

Not, çoğu ağda null'dur ve XRP, Stellar ve TON'da zorunludur. Orada atlanması fonları kaybeder: alan null olmayan her yerde zorunlu olarak ele alın.

Olası hatalar: unauthorized, invalid_request, quote_expired, idempotency_conflict, beneficiary_rejected, country_not_served. Tam katalog

GET/api/v1/orders/{reference}Published contract, not open

Bir emri oku

Geçerli durum ve zaman damgalı geçmiş. Geçmiş, gerçeğin kaynağıdır: yalnızca eklenir, asla yeniden yazılmaz ve "emirim neden o duruma o zamanda geçti" sorusuna yanıt verir.

Kimlik doğrulama: Authorization: Bearer … Kimlik doğrulamaya bakın

İstekbash

curl -sS https://fiatside.com/api/v1/orders/K7Q4-M2XB \
  -H 'Authorization: Bearer sk_live_...'

Yanıt — yayınlanan sözleşmejson

{
  "reference": "K7Q4-M2XB",
  "state": "COMPLETED",
  "transitions": [
    { "at": "2026-09-02T12:11:04Z", "from": "QUOTE_LOCKED",     "to": "AWAITING_DEPOSIT" },
    { "at": "2026-09-02T12:19:52Z", "from": "AWAITING_DEPOSIT", "to": "DEPOSIT_DETECTED" },
    { "at": "2026-09-02T12:21:10Z", "from": "CONFIRMING",       "to": "DEPOSIT_CONFIRMED" },
    { "at": "2026-09-02T12:21:44Z", "from": "PAYOUT_QUEUED",    "to": "PAYOUT_SENT" },
    { "at": "2026-09-02T12:22:03Z", "from": "PAYOUT_SENT",      "to": "COMPLETED" }
  ]
}

Olası hatalar: unauthorized, not_found. Tam katalog

Idempotans

Ağda zaman aşımına uğrayan bir oluşturma isteği, siparişin oluşturulup oluşturulmadığını söylemez. Bir idempotans anahtarı olmadan yalnızca iki kötü seçeneğiniz vardır: yeniden deneyip iki sipariş riski almak veya yeniden denemeyip hiç sipariş riski almak.

Başlıkhttp

Idempotency-Key: 7f3a1c92-5d0e-4a1b-9c2f-6b8e0d4a1f33

Her niyet için bir anahtar

Anahtar, HTTP isteğini değil, “bu siparişi oluştur” niyetini tanımlar. Sizin tarafınızda benzersiz bir kimlik: bir sepet kimliği, çağrıdan önce oluşturulmuş bir UUID, asla bir sayaç değil.

Tekrar oynatma orijinal yanıtı döndürür

Aynı anahtarı aynı gövdeyle tekrar oynatmak, ilk isteğin yanıtını aynı HTTP durumuyla döndürür. Bir zaman aşımından sonra bile yeniden denemeyi güvenli yapan şey budur.

Aynı anahtar, farklı gövde: çakışma

Yanıt açık bir çakışmadır. İçerik değişirse, anahtar değişmelidir: aksi takdirde kimse iki siparişten hangisinin tekrar oynatılacağını söyleyemez.

24 saat saklama

Bundan sonra anahtar unutulur ve tekrar oynatma yeni bir sipariş oluşturur. Pencere içinde yeniden deneyin veya durumu okuma uç noktasıyla kontrol edin.

Bazı ağlarda gereken not

XRP, Stellar ve TON'da yatırma adresi yeterli değildir: ek bir tanımlayıcı nihai alıcıyı belirtir. Bir off-ramp entegrasyonundaki en maliyetli olay nedenidir.

Notu olmayan bir yatırma, kayıp bir yatırmadır

Not alanı çoğu ağda null'dur ve gerektirenlerde null değildir. Null olmadığı anda zorunlu olarak ele alın ve adresle aynı ağırlıkta görüntüleyin. Paylaşılan bir adrese notu olmadan ulaşan bir yatırma, her zaman başarılı olmayan manuel kurtarma gerektirir.

Sipariş durumları

Aşağıdaki durumlar, entegrasyonunuzun gözlemleyebilecekleridir. Geçişler zaman damgalıdır ve eklenir, asla yeniden yazılmaz: geçmiş, “siparişim neden o anda o duruma geçti” sorusunu yanıtlar.

Sipariş durumları
Durum	Anlamı
`QUOTE_LOCKED`	Kur donduruldu. Sipariş, alıcı ayrıntılarını veya kimlik doğrulamasını bekliyor.
`AWAITING_DEPOSIT`	Yatırma adresi atandı ve yatırma penceresi çalışıyor. Fon göndermek için tek an budur.
`DEPOSIT_DETECTED`	Ağda gelen bir işlem görüldü, henüz onaylanmadı. Kullanıcıyı rahatlatın, hiçbir şey teslim etmeyin.
`CONFIRMING`	Onaylar birikiyor. Gerekli sayı ağa bağlıdır, tutara değil.
`DEPOSIT_CONFIRMED`	Yatırma güvence altına alındı. Uyumluluk ve yeniden fiyatlandırma kuralları buradan itibaren değerlendirilir.
`UNDERPAID`	Alınan tutar toleransın ötesinde beklenenin altında. Üç sonuç: tamamlama, alınan tutarla devam etme veya geri ödeme.
`OVERPAID`	Alınan tutar bekleneni aşıyor. İlk tutar sabitlenen kurdan kalır, fazla kısım ayrıca işlenir.
`PAYOUT_QUEUED`	Transfer kuyruğa alındı. Kuyruk, birden fazla işçi paralel çalışsa bile ödemenin yalnızca bir kez gönderilmesini garanti eder.
`PAYOUT_SENT`	Transfer kanala çıktı. Gönderildi, alındı anlamına gelmez: son gecikme, alıcının bankasına bağlıdır.
`COMPLETED`	Mutabakat kanal tarafından onaylandı. Terminal durum.
`PAYOUT_FAILED`	Kanal transferi reddetti veya iade etti. Otomatik yeniden deneme yoktur: neden neredeyse her zaman ayrıntılardadır.
`REFUNDED`	Fonlar, ağ ücretleri düşüldükten sonra kaynak adrese iade edildi. Terminal durum.