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.2500". Böylece yuvarlama hatası oluşmaz.
• Anlaşılır bir User-Agent belirleyin, örneğin AcmeShop-CardV/1.4.

#Para ve zaman

• Tutarlar 4 ondalık basamaklı metinlerdir, örneğin "merchant_price": "9.2500".
• 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.
• 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

Yalnızca 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.

#İ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. Hesap seviyenize göre 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."}

• 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 API anahtarları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.