Genel kurallar

İlgili: Kimlik doğrulama · Ürünler ve siparişler · README

#İstekler

• API adresi: https://b2b.cardv.net/api/v1 (Live) veya https://sandbox.cardv.net/api/v1 (Sandbox).
• Yollar eğik çizgiyle bitmez. /api/v1/orders/ değil, /api/v1/orders kullanın.
• JSON gövdelerini UTF-8 olarak ve Content-Type: application/json başlığıyla gönderin.
• Tutarları metin olarak gönderin, örneğin "9.25". Sıfırla doldurmanız gerekmez: "25", "25.5" ve "25.50" aynı tutardır. En fazla 4 ondalık basamak kabul edilir.
• Anlaşılır bir User-Agent belirleyin, örneğin AcmeShop-CardV/1.4.

#Para ve zaman

• Fiyatlar, toplamlar ve bakiyeler 2 ondalık basamaklıdır, örneğin "merchant_price": "9.25". Daha fazla basamak yalnızca tutar gerçekten içeriyorsa görünür.
• Nominal değerler karttaki gibi yazılır, örneğin "denomination_value": "10" veya "12.50".
• Tutarları ondalık (decimal) bir türle okuyun, asla kayan noktalı sayıyla değil.
• Ödemeyi cüzdanınızın para biriminde yaparsınız (GET/account içindeki default_currency, şu an USD).
• face_currency, kartın üzerinde yazan para birimidir. Cüzdanınızın para biriminden farklı olabilir.
• Maliyet hesabında her zaman merchant_price değerini kullanın. price_label gibi etiketler yalnızca görüntüleme içindir. range SKU'larda listedeki merchant_price yalnızca en düşük tutarın fiyatıdır: maliyetinizi öğrenmek için tam tutar ile fiyat teklifi alın.
• Tüm zamanlar UTC'dir ve ISO 8601 biçimindedir, örneğin 2026-09-29T08:15:30.123456Z.
• Gerçek bir ISO 8601 ayrıştırıcısı kullanın. Saniyedeki ondalık basamak sayısı değişebilir.
• İmzalamada kullanılan X-Timestamp, saniye cinsinden Unix zamanıdır.

#Numaralar

• Numaraları metin olarak saklayın. İçlerini ayrıştırmaya çalışmayın. İleride uzayabilirler.
• Siparişlerde ayrıca sayısal bir id alanı da vardır. Onu kullanmayın, order_id kullanın.
• Kendi sipariş numaranızda yalnızca şu karakterleri kullanın: A–Z a–z 0–9 - _ ..

#Sayfalama

GET/skus sayfalıdır. limit ve offset gönderin:

GET /api/v1/skus?limit=100&offset=200

{"count": 1234, "limit": 100, "results": ["..."], "filter_options": {}}

• limit varsayılan olarak 100'dür, en fazla 500 olabilir. Daha büyük değerler 500'e düşürülür.
• count, toplam sonuç sayısıdır. offset değeri count değerine ulaşana kadar devam edin.
• Negatif ya da sayı olmayan bir limit veya offset HTTP 400 döner.
• Bilinmeyen bir filtre değeri hata vermez, boş liste döner.
• GET/recharge/orders da daha küçük limitlerle sayfalıdır. Bkz. Mobil hat yükleme.

#İstek limiti

• Varsayılan limit, hesabınızın tamamı için dakikada 60 istektir. Tüm anahtarlarınız ve Portal kullanıcılarınız bu limiti paylaşır. Hesabınız için farklı bir limit tanımlanmış olabilir.

• Dakika, saatte :00 anında başlar. Reddedilen istekler de sayılır.

• Limiti aşarsanız HTTP 429 ve Retry-After başlığı (beklemeniz gereken saniye) alırsınız:

  JSONCopy

  {"detail": "Merchant API rate limit exceeded. Expected available in 23 seconds."}

• Yeni siparişlerin ayrı ve daha düşük bir limiti vardır: varsayılan olarak dakikada 20 yeni sipariş. Hediye kartı siparişleri (POST/orders) ve yükleme siparişleri (POST/recharge/orders) bu limiti paylaşır. Hesabınız için farklı bir değer geçerli olabilir. Bir sipariş isteği her iki limite de sayılır.

• Zaten var olan bir external_order_id gönderirseniz orijinal sipariş döner. Bu tekrar sipariş limitini kullanmaz; güvenli bir yeniden deneme bu yüzden engellenmez.

• Sipariş limitini aşarsanız yine HTTP 429 ve Retry-After alırsınız:

  JSONCopy

  {"detail": "Merchant order rate limit exceeded. Expected available in 23 seconds."}

• Limitin altında kalmak için: SKU listesini önbelleğe alın, sık sorgulamak yerine Webhook kullanın ve her 429 yanıtından sonra biraz daha uzun bekleyin.

#Hatalar

Önce her zaman HTTP durum kodunu kontrol edin. Sonra JSON gövdesini okuyun. Sorunun ne olduğunu gövdedeki anahtar (alan adı) söyler. Mesaj metnine güvenmeyin.

Kimlik doğrulama, yetki, bulunamadı ve istek limiti hataları detail kullanır:

{"detail": "Order not found."}

Sipariş ve fiyat sorgusu hataları ilgili alanın adını verir:

{"balance": "Insufficient available balance."}

Hatalı bir sipariş satırı, items listenizdeki sırasıyla, satır satır bildirilir:

{"items": [{}, {"quantity": ["Ensure this value is greater than or equal to 1."]}]}

Bazı hatalar JSON değildir:

• error code: 1010 gibi düz metinli bir HTTP 403, CardV'nin ağ katmanından gelir. İsteğiniz CardV'ye hiç ulaşmamıştır. Sunucu IP adresinizi ve User-Agent değerinizi CardV'ye iletin.
• Bilinmeyen bir yol (404) veya proxy hatası (5xx) HTML dönebilir.

Hataları kaydederken imzalama sırlarını, imzaları veya kodları asla loglara yazmayın.

#HTTP durum kodları

POST/orders isteğini yalnızca aynı gövde ve aynı sipariş numarasıyla tekrar deneyin. Bkz. güvenli yeniden deneme akışı.

#Yanıtlar

• brand_logo_url ve image_url, CardV'de barındırılan görsellerin tam adresleridir ya da "" değerindedir. Herkese açıktır ve önbelleğe alınabilir.
• Siparişteki invoice_url ve delivery_file_url alanları /orders/O-00001234/invoice gibi yollardır. Henüz bir şey yoksa "" olur. Bu adresler yalnızca Portal'da çalışır: API anahtarıyla çağrıldığında HTTP 403 döner. Faturaları ve kodların CSV dosyalarını Portal'dan açın.

#Uyumluluk

• Tanımadığınız alanları yok sayın. CardV, yeni API sürümü çıkarmadan alan ekleyebilir.
• Yeni durum değerleri eklenebilir. Bilinmeyen bir durumu "henüz tamamlanmadı" olarak değerlendirin.
• JSON anahtarlarının sırasına veya mesajların metnine güvenmeyin.