Geliştiriciler/Başlarken

CardV Merchant API

CardV, işletmelere hediye kartı, oyun yüklemesi ve eSIM gibi ön ödemeli dijital ürünler satar. Merchant API sayesinde sunucunuz bu ürünleri otomatik olarak satın alabilir. Bakiyenizi görür, ürünü bulur, fiyatını öğrenir, siparişi verir ve kodları alırsınız. Siparişlerin ödemesi, CardV'deki ön ödemeli cüzdanınızdan yapılır. Bakiye yükleme ve sipariş geçmişi gibi diğer her şey Merchant Portal'dan yapılır.

#Dokümanlar

Doküman	İçerik
Kimlik doğrulama	Başlıklar, sipariş imzalama, anahtar kurulumu
Ürünler ve siparişler	Bakiye, ürünler, fiyatlar, siparişler, kodlar
Genel kurallar	Tutarlar, tarihler, numaralar, istek limiti, hatalar
Webhook'lar	Sunucunuza gönderilen sipariş bildirimleri
Sandbox	Test ve canlıya geçiş kontrol listesi
Güvenlik	Anahtarları ve kodları korumak

#Ortamlar

	Live	Sandbox
API adresi	`https://b2b.cardv.net/api/v1`	`https://sandbox.cardv.net/api/v1`
Merchant Portal	`https://b2b.cardv.net/portal/`	Aynı Portal, Sandbox'a geçin

Sandbox, CardV'nin test parasıyla çalışan ayrı bir test kopyasıdır. API anahtarları, bakiyeler, siparişler ve ürün numaraları iki ortamda birbirinden farklıdır.

#Hızlı başlangıç

Başvurun. Portal'dan üye işyeri hesabı için başvurun ve e-posta adresinizi doğrulayın.
Onayı bekleyin. CardV işletmenizi inceler. Ardından size bir Merchant ID (üye işyeri numarası) verilir, örneğin M00000001.
Sandbox'ı açın. Portal'a giriş yapın ve üst menüden Sandbox'ı seçin. Hesabınıza 1.000 USD test parası tanımlanır.
API anahtarı oluşturun. Portal'da Integrations → API keys bölümüne gidin. Bir anahtar oluşturun, ardından CardV'nin e-postayla gönderdiği kodla anahtarı görüntüleyin. Anahtarı gizli bilgi deponuza kaydedin.

Bakiyenizi kontrol edin:

Shell

export CARDV_BASE=https://sandbox.cardv.net
export CARDV_MERCHANT_ID=M00000001     # yours
export CARDV_API_KEY=cvb2b_...         # from your secret store
AUTH=(-H "X-Merchant-Id: $CARDV_MERCHANT_ID" -H "X-Api-Key: $CARDV_API_KEY")

curl -sS "$CARDV_BASE/api/v1/balance" "${AUTH[@]}"

Bir ürün bulun:
Shell
```
curl -sS "$CARDV_BASE/api/v1/skus?search=steam&limit=20" "${AUTH[@]}"
```
"availability": "available" olan bir ürün seçin ve sku_id değerini not edin.
Fiyatı öğrenin:
Shell
```
curl -sS "$CARDV_BASE/api/v1/skus/S000001/quote?quantity=1" "${AUTH[@]}"
```
merchant_price değerini not edin. Bu, adet başına ödeyeceğiniz tutardır.
Siparişi verin. Bu istek imzalı olmalıdır. Kimlik doğrulama sayfasındaki örneklerden birini şu gövdeyle kullanın:
JSON
```
{
  "external_order_id": "TEST-0001",
  "items": [
    {"sku_id": "S000001", "quantity": 1, "expected_unit_price": "9.2500"}
  ]
}
```
Yanıt olarak HTTP 201 ve O-00001234 gibi bir CardV sipariş numarası alırsınız.
Kodları alın. Durum succeeded olana kadar GET/api/v1/orders/O-00001234 isteğini tekrarlayın. Kodlar items[].deliveries[].display_fields alanındadır. Sipariş tamamlandığında bir Webhook bildirimi de alabilirsiniz.
Canlıya geçin. Önce Sandbox kontrol listesini tamamlayın.

Yukarıdaki numaralar ve fiyatlar örnektir. Kendi kataloğunuzda dönen değerleri kullanın.

#Kısaca API

Toplam yedi uç nokta vardır. Tüm yollar /api/v1 ile başlar.

Uç nokta	Ne işe yarar	İmza
`GET/account`	Şirket bilgileriniz ve API durumu	Hayır
`GET/balance`	Harcayabileceğiniz tutar	Hayır
`GET/skus`	Satın alabileceğiniz ürünler ve size özel fiyatları	Hayır
`GET/skus/{sku_id}`	Tek bir ürün	Hayır
`GET/skus/{sku_id}/quote`	Belirli bir adet için güncel fiyat	Hayır
`POST/orders`	Cüzdanınızdan ödenen sipariş verme	Evet
`GET/orders/{order_id}`	Sipariş durumu ve kodlar	Hayır

Başka bir uç noktayı API anahtarıyla çağırırsanız HTTP 403 alırsınız:

JSON

{"detail": "This operation is only available in the Merchant Portal."}

Mobil hat yüklemesi (kontör yükleme) API üzerinden yapılamaz.

#Numaralar

Ne	Örnek	Not
Merchant ID	`M00000001`	Size aittir. Hiç değişmez.
SKU (satın alabileceğiniz bir ürün)	`S000456`	Fiyat sorgusu ve sipariş için kullanılır.
CardV sipariş numarası	`O-00001234`	Kendi siparişinizle birlikte saklayın.
Kendi sipariş numaranız	`SHOP-10001`	Siz belirlersiniz (`external_order_id`).

Numaraları metin olarak saklayın. İçlerini ayrıştırmaya çalışmayın. Bkz. Genel kurallar.

#Portal'dan yapılanlar

Cüzdana bakiye yükleme ve düşük bakiye e-posta uyarısı
Sipariş geçmişi, arama ve CSV dışa aktarma
Sipariş faturaları
Cüzdan hareketleri ve mutabakat
Webhook kurulumu, gönderim geçmişi ve yeniden gönderme
API anahtarları
IP izin listesi
Ekip üyeleri ve roller
Denetim kaydı
İki adımlı doğrulama (2FA)
Live ile Sandbox arasında geçiş

#Uyumluluk ve destek

Yanıtlara önceden haber vermeden yeni alanlar ve yeni durum değerleri ekleyebiliriz. Tanımadığınız alanları yok sayın. Bilinmeyen bir sipariş durumunu "henüz tamamlanmadı" olarak değerlendirin. Hata mesajlarının metnine güvenmeyin.

Destek için [email protected] adresine yazın. Merchant ID'nizi, ortamı, sipariş numaralarını, saati (UTC) ve HTTP durum kodunu ekleyin. API anahtarlarını, imzaları, Webhook sırlarını veya kart kodlarını asla göndermeyin.

Entegrasyonla ilgili sorunuz mu var? Merchant ID’nizi ve sipariş ya da istek kimliğini ekleyerek [email protected] adresine yazın.