WeSIMTech Bayi (Reseller) API

Bağlı tüm ağ kaynaklarındaki eSIM ürünlerini kendi markanızla satın: hesabınıza özel fiyat, hesap para biriminde tahsilat, ön ödemeli bakiye ve cari (açık hesap), test/canlı ortam, idempotent sipariş, ücretli yükleme, iptal iadesi ve imzalı webhook. Bu sayfadaki 40 uç, sırayla entegrasyon akışını izler.

Hızlı başlangıç (15 dakika)

1. Bayi panelinden test anahtarı üretin (wsm_test_…). Test siparişleri ücretlendirilmez, anında sahte profillerle teslim edilir.
2. POST /auth/test ile anahtarı, yetkileri ve IP allowlist'i doğrulayın.
3. GET /packages?country=DE ile katalogdan fiyatınızı görün; POST /quotes ile toplamı ve bakiye yeterliliğini alın.
4. Benzersiz Idempotency-Key ve teklifteki fiyatı max_unit_price olarak göndererek POST /orders çağırın.
5. order.delivered webhook'unu dinleyin ya da GET /orders/{reference} ile profiles[].activation_code (LPA) alın.
6. Canlıya geçmek için aynı kodu wsm_live_… anahtarıyla çalıştırın.

curl -X POST "https://wesim.tech/api/v1/auth/test" \
  -H "Authorization: Bearer wsm_test_YOUR_KEY"

curl "https://wesim.tech/api/v1/packages?country=DE&limit=20" \
  -H "Authorization: Bearer wsm_test_YOUR_KEY"

curl -X POST "https://wesim.tech/api/v1/orders" \
  -H "Authorization: Bearer wsm_test_YOUR_KEY" \
  -H "Idempotency-Key: ord-0001" \
  -H "Content-Type: application/json" \
  -d '{"package_id":"EU-42_3_30","quantity":1,"client_reference":"ERP-1001","max_unit_price":10.55}'

Kimlik doğrulama ve ortamlar

Bakiye ve cari (açık hesap) kuralı

Harcanabilir tutar = cüzdan bakiyesi + kullanılabilir cari. Cari, yalnız hesabınızda cari satış izni açıksa ve cari blokeli değilse kullanılır. Cüzdan bakiyesi negatife inebilir; negatif kısım kullanılan caridir.

• Canlı sipariş ve yükleme tutarı istek anında, hesap kilitlenerek düşülür. Aynı anda gelen istekler bakiyeyi aşamaz.
• Yetmezse 402 insufficient_balance döner; sipariş/yükleme oluşmaz, tahsilat yapılmaz. error.details: required_amount, available_to_spend, shortfall, Valuta, credit_enabled, credit_status.
• Tüm fiyat ve tutarlar hesabınızın para birimindedir. Kur doğrulanamazsa satış yapılmaz (503 fx_unavailable).
• Teslim edilemeyen adet, başarısız sipariş, reddedilen yükleme ve kabul edilen iptal otomatik iade edilir. Tüm hareketler GET /account/ledger'da.

{
    "success": false,
    "error": {
        "code": "insufficient_balance",
        "message": "Yetersiz bakiye: bu işlem için 52.40 USD gerekiyor, kullanılabilir tutar 20.00 USD. Hesabınızda cari satış izni yok; bakiye yükleyin.",
        "details": {
            "context": "Sipariş B2B-…",
            "currency": "USD",
            "required_amount": 52.4,
            "available_to_spend": 20,
            "shortfall": 32.4,
            "wallet_balance": 20,
            "credit_enabled": false,
            "credit_status": "active"
        },
        "documentation_url": "/api-docs#errors"
    },
    "meta": {
        "request_id": "req_…",
        "api_version": "v1"
    }
}

Idempotency ve fiyat koruması

POST /orders e POST /esims/{iccid}/topups Idempotency-Key başlığı ister. Zaman aşımında aynı anahtarla tekrar deneyin: aynı gövde ilk yanıtı döndürür (çift sipariş/çift tahsilat olmaz); aynı anahtar farklı gövdeyle 409 döner. Anahtarlar 24 saat saklanır.

Fiyat koruması: teklifteki fiyatı max_unit_price / max_total_amount (yüklemede max_price) olarak gönderin. Fiyat arada yükselmişse 409 price_changed döner ve tahsilat yapılmaz.

Sayfalama, senkron ve limitler

• İmleç: pagination.next_cursor değerini cursor (katalog) ya da before_id (sipariş, defter) olarak gönderin; has_more=false son sayfadır.
• Katalog senkronu: günde bir tam çekim + saatlik updated_since çekimi önerilir. Satıştan kalkan kodlar GET /packages/{id}'de replaced_package_id ile yeni pakete yönlenir.
• Hız limiti: plan/anahtar bazında dakikalık ve günlük. Her yanıtta X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Daily-*; aşımda 429 + Retry-After.

Hata kodları

Hata yanıtı: {"success":false,"error":{"code","message","details?","documentation_url"},"meta":{"request_id"}}. İş akışınızı error.code'a göre kurun; mesaj metni değişebilir.

Webhook olayları ve imza doğrulama

Gönderim başlıkları: X-WSM-Event, X-WSM-Event-Id, X-WSM-Timestamp, X-WSM-Signature: sha256=<hex>. İmza: HMAC_SHA256(secret, timestamp + "." + ham_gövde). 2xx dışı yanıtlar üstel geri çekilmeyle tekrar denenir; aynı olay birden fazla gelebilir, X-WSM-Event-Id ile tekilleştirin.

<?php // PHP
$raw = file_get_contents('php://input');
$ts  = $_SERVER['HTTP_X_WSM_TIMESTAMP'] ?? '';
$sig = substr($_SERVER['HTTP_X_WSM_SIGNATURE'] ?? '', 7); // "sha256=" sonrası
if (abs(time() - (int)$ts) > 300 || !hash_equals(hash_hmac('sha256', $ts . '.' . $raw, $secret), $sig)) {
    http_response_code(401); exit;
}
http_response_code(200); // önce yanıtlayın, işi kuyrukta yapın

// Node.js
const ok = crypto.timingSafeEqual(
  Buffer.from(crypto.createHmac('sha256', secret).update(ts + '.' + rawBody).digest('hex')),
  Buffer.from(sig));

Yetki (scope) kataloğu