İçeriğe geç
Apex Settlement

Genel kurallar

Tutarlar, varlıklar, ülkeler, kimlikler, zaman damgaları, sayfalama ve her entegrasyonun kullandığı başlıklar.

İstekler ve yanıtlar

API, HTTPS üzerinden JSON ile çalışır. Gövdeli isteklerde Content-Type: application/json gönderin; yanıtlar JSON gelir. Tüm yollar, ortamınızın temel URL'si üzerinde /v1 ile başlar. Alan adları istekte de yanıtta da snake_case yazılır.

Yanıtlara zamanla yeni sürüm çıkarmadan alan ve değer ekleriz. Tanımadığınız alanları yok sayın; bir durumun ya da kodun bilinmeyen bir değerini hata olarak değil, "henüz ele almadığınız bir şey" olarak değerlendirin.

Tutarlar

Tutarlar istekte de yanıtta da JSON sayısı olarak değil, ondalık metin (string) olarak gelir. Bir para tutarı, miktar ile varlığından oluşan bir nesnedir:

{ "amount": "918.58", "asset": "EUR" }

Tutarları kayan noktalı bir sayıya değil, ondalık bir türe (BigDecimal, decimal.Decimal, shopspring/decimal) çevirin. Her varlığın bir ölçeği, yani bir tutarın taşıyabileceği en fazla ondalık hane sayısı vardır:

VarlıklarÖlçekÖrnek
USDC, USDT, EURC6"1000.123456"
İtibari para birimleri (EUR, GBP, USD, PKR, ...)2"918.58"

Varlığının ölçeğinden fazla ondalık taşıyan bir tutar amount_scale ile, pozitif bir ondalık sayı olmayan bir tutar bad_amount ile reddedilir. Sondaki sıfırlar sorun değildir: "1000.50" ile "1000.5" aynıdır. Yanıtlar tutarları ölçeğe göre doldurmaz; "1000" ve "0.5" gibi değerler normaldir.

Kurlar da ondalık metindir. Bir kur, bir adımın kaynak varlığının bir biriminin kaç hedef varlık birimi aldığını gösterir: USDC'den EUR'ya bir adımdaki "0.92", 1 USDC'nin 0.92 EUR ettiği anlamına gelir.

Varlıklar ve ülkeler

  • Varlıklar, itibari para birimleri için ISO 4217 kodları (EUR, USD, PKR), stablecoin'ler için semboller (USDC, USDT, EURC).
  • Ülkeler, ISO 3166-1 alpha-2 kodları (DE, US, PK).

İkisini de büyük harfle gönderin. Bir alıcının country ve asset alanları sizin için büyük harfe çevrilir; teklif isteğindeki source_asset gibi diğer alanlar gönderdiğiniz gibi alınır.

Kimlikler

Kaynak kimlikleri (ödemeler, alıcılar, webhook uç noktaları, gönderimler, olaylar, End Customer'lar) UUID metinleridir. Bazı değerler ise opak token'lardır: qt1. ile başlayan quote_id ve sayfalamadaki cursor. Bunları saklayın ve olduğu gibi geri gönderin; çözümlemeye ya da kendiniz üretmeye çalışmayın.

UUID olmayan bir yol kimliği çoğu uç noktada invalid_id (400) ile reddedilir. Başka bir hesaba ait bir kimlik, hiç var olmayan bir kimlik gibi 404 döner.

Zaman damgaları

Zaman damgaları UTC'de RFC 3339 metinleridir, örneğin "2026-11-12T10:00:20Z". Bazıları kesirli saniye taşır ("2026-11-12T10:00:20.123456Z"); bu yüzden tam bir RFC 3339 ayrıştırıcısı kullanın.

Teklif yanıtı, yanıtı verdiğimiz anı gösteren server_time alanını taşır. Bir teklifin kalan süresini server_time ile expires_at arasından hesaplayın; sunucunuzun saati sapmış olabilir.

Sayfalama

Liste uç noktaları üç biçimde gelir.

İmleçli sayfalar. GET /v1/payouts ve GET /v1/incoming-payouts en yeniden eskiye sıralı döner. limit (1 ile 100 arası, varsayılan 50) gönderin; sonraki sayfa için önceki sayfanın next_cursor değerini cursor olarak iletin. Son sayfada next_cursor bulunmaz.

curl
curl "$APEX_BASE_URL/v1/payouts?state=completed&limit=100&cursor=eyJjIjoiMjAyNi0xMS0xMl..." \
  -H "Authorization: Bearer $APEX_API_KEY"
Uç noktaÖğelerin alanıFiltreler
GET /v1/payoutspayoutsstate: awaiting_approval, accepted, funded, processing, completed, failed, refunded, cancelled
GET /v1/incoming-payoutsitemsyok
200 OK
{
  "payouts": [{ "id": "7d41f0b2-9c3e-4a85-b6d1-2e8f5a7c9b13", "state": "completed" }],
  "next_cursor": "eyJjIjoiMjAyNi0xMS0xMlQxMDowMDoyMFoiLCJpIjoiN2Q0MWYwYjIi..."
}

Hiçbir sayfanın üretmediği bir imleç bad_cursor, aralık dışındaki bir limit bad_limit, bilinmeyen bir state ise unknown_state ile reddedilir (hepsi 422).

Konumlu (offset) sayfalar. GET /v1/end-customers, limit (varsayılan 50, en fazla 500) ve offset alır ve en yeniden eskiye sıralı düz bir dizi döner. Ayrıca state ile filtreler, q ile ad ve e-postalarda arar.

Tam listeler. GET /v1/balances, GET /v1/beneficiaries, GET /v1/deposit-instructions ve GET /v1/webhooks tüm öğeleri düz bir dizi olarak döner. GET /v1/webhooks/{id}/deliveries en yeni gönderimlerden limit kadarını (1 ile 100 arası, varsayılan 50) döner.

Correlation id

Her yanıt bir X-Correlation-ID başlığı taşır; her hata gövdesi bu değeri correlation_id olarak tekrarlar. İsteği loglarımızda bulmamızı sağlar. Kendi istek kimliğinizle birlikte loglayın ve destekle iletişime geçtiğinizde paylaşın. Bu değeri biz atarız; sizin gönderdiğiniz bir değer kullanılmaz.

Bir End Customer adına işlem yapmak

Bir Platform, End Customer'larından biri adına işlem yapmak için sıradan bir /v1 çağrısında o End Customer'ın kimliğini Apex-End-Customer başlığıyla gönderir:

curl
curl "$APEX_BASE_URL/v1/balances" \
  -H "Authorization: Bearer $APEX_API_KEY" \
  -H "Apex-End-Customer: 8a3f5d27-c1e9-4b64-9d0a-6e2b7f4c1d93"

Çağrı bu durumda, anahtarınızın izinleri dahilinde o End Customer'ın bakiyelerini, alıcılarını ve ödemelerini okur ve onlar üzerinde işlem yapar. End Customer'larınızdan birine ait olmayan bir kimlik end_customer_not_found (404), Platform olmayan bir çağıran ise not_a_platform (403) alır. End Customer'ların tüm ayrıntıları Platformlar rehberinde.

Bu sayfada