API Dokümantasyonu & Geliştirici Rehberi

Hızlı Başlangıç

Coinzen ile sitenizde kripto ödeme almaya başlamak yalnızca 3 adımdır: API anahtarı oluşturun, tahsilat cüzdan adreslerinizi tanımlayın ve ilk ödeme faturanızı açın. Aracısız mimarimiz sayesinde tahsilatlar doğrudan sizin kontrolünüzdeki cüzdana aktarılır.

• Panel → API Anahtarları — Hesabınıza girip anahtar çiftinizi (KeyId ve Secret) buradan üretirsiniz. Secret yalnız üretildiği an bir kez gösterilir.
• Panel → Ayarlar ya da POST /v1/static-addresses — USDT gibi token tahsilatları için statik cüzdan adresinizi tanımlar (her ağ ve varlık için bir adet).
• Panel → Ayarlar ya da POST /v1/sweep-addresses — TRX, BNB, GRAM gibi native coin tahsilatlarının toplanacağı ana cüzdanınızı (süpürme adresi) tanımlar.
• POST /v1/webhooks — Ödeme tamamlandığında sisteminize anında bildirim gönderecek URL uç noktanızı kaydeder.

İstek İmzalama (HMAC Güvenliği)

API güvenliğiniz için tüm HTTP istekleri HMAC-SHA256 standardı ile imzalanır. İmza, isteğin ham gövdesi (raw bytes) üzerinden hesaplanır; böylece JSON formatındaki anahtar sıralaması değişse dahi imza geçerliliğini korur.

METHOD \n PATH \n TIMESTAMP \n NONCE \n SHA256(raw_body)

X-Api-Key

API Anahtar Kimliği (pk_…)

X-Timestamp

Unix zaman damgası (saniye bazında sunucu saati toleranslı)

X-Nonce

Benzersiz rastgele dize (en fazla 128 karakter, tek kullanımlık)

X-Signature

hex(hmac_sha256(secret, canonical)) imza değeri

İstek güvenliği iki katmanda korunur: Zaman damgası belirlenen tolerans aralığında olmalı ve nonce değeri yalnızca bir kez kullanılmalıdır. Aynı isteğin mükerrer olarak tekrar gönderilmesi otomatik olarak engellenir (HTTP 401).

X-Timestamp Unix epoch saniyedir ve sunucu saatinden en çok 300 saniye sapabilir. X-Nonce istek başına benzersizdir; kullanılmış bir nonce 600 saniye boyunca reddedilir.

1import hashlib, hmac, os, time, json, urllib.request
2 
3KEY_ID  = os.environ["COINZEN_KEY_ID"]
4SECRET  = os.environ["COINZEN_SECRET"]
5BASE    = "https://coinzen.cerceyn.com"
6 
7def request(method: str, path: str, payload: dict | None = None) -> bytes:
8    body = json.dumps(payload).encode() if payload is not None else b""
9    ts = str(int(time.time()))
10    nonce = os.urandom(16).hex()
11    canonical = "\n".join(
12        [method.upper(), path, ts, nonce, hashlib.sha256(body).hexdigest()]
13    )
14    signature = hmac.new(SECRET.encode(), canonical.encode(), hashlib.sha256).hexdigest()
15 
16    req = urllib.request.Request(
17        BASE + path,
18        data=body or None,
19        method=method.upper(),
20        headers={
21            "X-Api-Key": KEY_ID,
22            "X-Timestamp": ts,
23            "X-Nonce": nonce,
24            "X-Signature": signature,
25            "Content-Type": "application/json",
26        },
27    )
28    with urllib.request.urlopen(req) as resp:
29        return resp.read()

Kapsamlar

Her anahtar yalnız kendisine verilen kapsamların uçlarını çağırabilir; eksik kapsam 403 döner. Kapsamları panelden anahtar üretirken seçersiniz.

Hız Sınırları

Sınır mağaza başına ve dakikalık kayan pencerede uygulanır. Aşıldığında 429 ile birlikte Retry-After başlığı döner.

• Genel uçlar — 120 istek / dakika
• Fatura oluşturma — 30 istek / dakika

Tekrar Güvenliği (Idempotency)

POST /v1/invoices çağrısında Idempotency-Key başlığı zorunludur. Başlık yoksa istek 422 ile reddedilir. Her istek için yeni ve benzersiz bir değer üretin.

Idempotency-Key: 7f3c1e9a4b8d42f0a1c6e5b3d9074a2e

Aynı anahtarla aynı gövde tekrar gönderilirse yeni fatura açılmaz: ilk yanıt, ilk durum koduyla birlikte aynen döner. Ağ kopması sonrası isteği güvenle yineleyebilirsiniz.

Fatura Yaşam Döngüsü

Bir ödeme faturası oluşturulduğunda akıllı durum makinesi devreye girer. Ağ ve varlık belirtilmemişse fatura selecting (Seçim Bekleniyor) durumunda başlar. Müşteri ödeme sayfasında dilediği ağı ve kripto parayı seçtiğinde fatura pending (Ödeme Bekleniyor) aşamasına geçer ve ödeme adresi tahsis edilir.

• selecting → pending, expired, cancelled
• pending → confirming, partially_paid, expired, cancelled
• confirming → paid, overpaid, failed
• paid ⇄ overpaid — Ödenmiş faturaya müşteri ek bir transfer daha gönderirse tutar otomatik olarak güncellenir.

paid, overpaid, expired, cancelled ve failed durumları nihai durumlardır. Olası blokzincir reorg (düzeltme) veya gecikmeli ödeme senaryolarında sistem durumu otomatik günceller ve webhook ile sisteminize bilgi iletir.

Bakiye Ödemesi

Bakiye ya da kontör satıyorsanız sabit tutar yanlış modeldir: müşteri 5.188 yerine yuvarlayıp 5 gönderir ve fatura eksik kalır. Faturayı balance_payment: true ile açtığınızda inen tutar faturayı kapatır — gösterilen tutar yalnız öneridir ve ödeme sayfası da bunu ödeyene açıkça söyler.

Alacağı fiat_amount üzerinden değil, webhook'taki received_amount ve kilitli kurdan hesaplanmış received_fiat_amount üzerinden yazın. Fatura 250 TRY istese de 5 USDT indiyse yüklenecek olan 5 USDT'nin karşılığıdır. Komisyon da inen tutar üzerinden tahakkuk eder.

Token tahsilatında adres paylaşımlıdır ve faturayı ödemeye bağlayan şey tutardır. Aynı ağ/varlıkta aynı anda birden çok bakiye faturası açıksa yuvarlanmış bir ödemenin hangisine ait olduğu bilinemez; sistem tahmin etmez, ödeme eşleşmeyenlere iner ve deposit.unmatched webhook'u gider. Panelden doğru faturaya bağlarsınız. Kontör faturasıyla birlikte kullanılamaz.

Webhook Bildirimleri

Ödeme durumundaki tüm değişiklikler kayıtlı webhook uç noktanıza anlık olarak iletilir. Gönderilen her paket HMAC-SHA256 ile imzalanır; böylece gelen verinin orijinalliğini ve Coinzen tarafından gönderildiğini güvenle doğrulayabilirsiniz.

İmza doğrulamada kullanılan Webhook Secret (whsec_…) uç noktayı kaydettiğiniz anda bir kez verilir: panelin Webhook sayfasında ya da POST /v1/webhooks yanıtının secret alanında. API anahtarınızın Secret'ı değildir; o yalnız sizin gönderdiğiniz istekleri imzalar. Aynı adresi yeniden kaydederseniz yeni bir Webhook Secret verilir ve eski kayıt kapanır.

X-Coinzen-Signature

t=<unix>,v1=<hex hmac_sha256(secret, "<t>.<raw_body>")>

X-Coinzen-Delivery

Benzersiz bildirim teslimat kimliği (UUID)

X-Coinzen-Event

Tetiklenen olay adı (örn: invoice.paid)

1import hashlib, hmac, time
2 
3def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
4    """X-Coinzen-Signature: t=<unix>,v1=<hex>"""
5    parts = dict(p.split("=", 1) for p in header.split(","))
6    t, v1 = parts["t"], parts["v1"]
7    if abs(time.time() - int(t)) > tolerance:
8        return False
9    expected = hmac.new(
10        secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256
11    ).hexdigest()
12    return hmac.compare_digest(expected, v1)

Desteklenen Webhook Olayları

• invoice.pending
• invoice.confirming
• invoice.partially_paid
• invoice.paid
• invoice.overpaid
• invoice.expired
• invoice.cancelled
• payment.reverted
• deposit.unmatched
• credit.low
• credit.exhausted

Akıllı Yeniden Deneme Mekanizması

İlk deneme ödeme gerçekleştikten hemen sonra anlık olarak yapılır. Sunucunuzdan 200 OK yanıtı alınamazsa bildirimler 30 · 120 · 600 · 3600 · 21600 · 86400 saniye aralıklarla 7 kademede otomatik tekrar denenir. Tüm denemeler sonuçsuz kalırsa kayıt dead_letter durumuna alınır ve yönetim panelinden tek tıkla tekrar kuyruğa gönderilebilir.

Hata Sözleşmesi

Tüm hatalar aynı zarfla döner. code alanı sabittir ve programla eşlenmek içindir; message insan içindir ve değişebilir.

1{
2  "error": {
3    "code": "conflict",
4    "subcode": "order_id_exists",
5    "message": "bu order_id zaten kullanılmış",
6    "details": { "order_id": "A-1042" }
7  }
8}

subcode alanı sınıf kodunu daraltır: conflict yerine order_id_exists gibi. Önce subcodea bakın, yoksa codea düşün — sözleşme genişler, daralmaz.

Şema doğrulamasından geçmeyen isteklerde (eksik alan, yanlış tip, aralık dışı değer) code değeri validation_error olur ve details alan yolunu hata türüne eşler: {"body.url": "url_scheme"}. Tür programla eşlenmek içindir (missing, greater_than gibi); açıklama message alanındadır.

Komisyon ve Kontör Sistemi

Coinzen'de komisyon asla müşteri ödemesinin içinden kesilmez. USDT ve diğer kripto ödemeleri doğrudan sizin adresinize geçer ve o cüzdanın anahtarları yalnızca sizdedir. Platform hizmet bedeli önceden yüklediğiniz kontör bakiyenizden düşer; böylece tahsilatınız her zaman tam, net ve eksiksiz kalır.

• Standart komisyon oranımız %1'dir. Yeni açılan hesaplara özel ilk 45 gün boyunca avantajlı oran olan %0,1 uygulanır. Mağazanıza tanımlı güncel komisyon oranını GET /v1/credit yanıtındaki fee_bps alanından görebilirsiniz (on binde: 10 = %0,1; 100 = %1).
• Komisyon yalnızca başarıyla tamamlanan (paid ve overpaid) faturalardan tahsil edilir.
• İptal edilen, süresi dolan veya eksik kalan faturalardan hiçbir komisyon alınmaz.
• Kontör bakiyeniz bittiğinde açık faturaların tahsilat süreci etkilenmez, güvenle işlenir; yalnızca yeni fatura açma istekleri bakiye uyarısı (HTTP 402) alır.

İki Adımlı İşlem Modeli

Fatura ödendiğinde komisyon kaydı blokzincir takip hızını yavaşlatmamak için anında pending olarak açılır ve hiçbir dış servise bağımlı olmadan hızlıca işlenir. Döviz kuru hesaplaması arka planda yapılarak net tutar bakiyenizden düşülür.

Olası bir blokzincir reorg durumunda ödeme geri çekilirse komisyon kesintisi de anında iptal edilir; düşülmüşse reversal kaydıyla bakiyenize iade edilir.

Hızlı Kontör Yükleme

POST /v1/credit/deposit-addresses çağrısı ile size özel kalıcı bir USDT yükleme cüzdan adresi alırsınız. Bu adrese gönderdiğiniz bakiye blokzincirde onaylandığı anda kontörünüze otomatik olarak eklenir — manuel onay veya bekleme yoktur.

Otomatik Kontör Tamamlama

Bu özellik aktif edildiğinde, kontör bakiyeniz sıfırlansa dahi mağazanızın satışları durmaz. Bir sonraki küçük faturanızın tahsilatı doğrudan kontör bakiyenize aktarılır. Hizmetiniz kesintisiz sürer.

• Kontöre yönlendirilen bu faturadan ayrıca komisyon alınmaz.
• Güvenliğiniz için üst sınır uygulanır (varsayılan 25 USD). Üst sınırı aşan faturalar yönlendirilmez, büyük siparişleriniz riske edilmez.
• PUT /v1/credit/auto API uç noktası veya panel üzerinden dilediğiniz an açıp kapatabilir, kendi üst sınırınızı belirleyebilirsiniz.

Bakiye Uyarıları

Kontör bakiyeniz kritik eşiğin altına indiğinde credit.low, tükendiğinde ise credit.exhausted webhook olayı tetiklenir; böylece önceden haberdar olursunuz.

Desteklenen Blokzincir Ağları ve Varlıklar

Aşağıdaki tablo canlı mainnet ağ kayıt defterinin özetidir. Çalışma zamanındaki anlık liste için GET /v1/networks uç noktasını kullanabilirsiniz.

API Uç Noktaları

İstek Şemaları

Entegrasyonun ilk gününde çağrılan uçların gövdeleri aşağıda. Tüm uçların tam şeması makine okunur biçimde GET /openapi.json adresinde yayınlanıyor; Postman'e aktarabilir ya da istemci üretebilirsiniz.

Sorgu Parametreleri