Vitrin API'si
Vitrin API’si, bir CIQRA mağazası üzerinde kendi ön yüzünüzü — bir Next.js sitesi, bir mobil uygulama, bir kiosk — kurmanızı sağlar. Mağazanın web sitesinin ziyaretçiye gösterdiğini okur ve bir sepet yürütür; ödeme mağazanın kendi ödeme sayfasında yapılır.
Uygulama API’si değildir: uygulama, OAuth ya da scope gerektirmez ve müşterileri, siparişleri ya da personelin yönettiği hiçbir şeyi okuyamaz.
Temel adres
Bölüm başlığı “Temel adres”Mağazanın kendi alan adını çağırın (birincil alan adı ya da *.myciqra.com adresi):
https://{mağaza alan adı}/api/storefront/v1Sürüm yoldadır. v1’e yalnızca alan eklenir; bir yeniden adlandırma ya da kaldırma v2 olur.
Erişim token’ları
Bölüm başlığı “Erişim token’ları”Token’ları mağaza sahibi yönetim panelinde oluşturur (Ayarlar → Vitrin API’si). Token ciqra_sfp_… biçimindedir ve
tasarım gereği herkese açıktır — bir tarayıcı paketinde ya da uygulamada yer alabilir. Her istekte gönderin:
GET /api/storefront/v1/products HTTP/1.1Host: magaza.example.comX-Ciqra-Storefront-Access-Token: ciqra_sfp_…- Token tek bir mağazaya aittir. Başka bir mağazanın alan adında tanınmaz (
401 invalid_token). - Token yalnızca oluşturulduğunda bir kez gösterilir; mağaza yalnızca özetini saklar. İptal bir sonraki istekte geçerli olur.
- Her token’ın kendi izinli kökenleri ve istek hızı vardır. Bir mağazada en çok 10 etkin token olabilir.
Tarayıcılar ve CORS
Bölüm başlığı “Tarayıcılar ve CORS”Başka bir web kökeninden çağıran tarayıcı, token’ın izinli kökenler listesinde olmalıdır:
- köken
https://alanya dahttps://alan:portbiçimindedir — yol ve joker yoktur;http://yalnızcalocalhostiçin; - eşleşme birebirdir:
https://magaza.example.com,https://sahte-magaza.example.comadresini asla kabul etmez; - ön kontrol (
OPTIONS) mağazanın etkin token’larından birinin listelediği her köken için yanıtlanır; asıl istek taşıdığı token’a göre denetlenir (aksi halde403 origin_not_allowed); - yanıtlarda
Access-Control-Allow-Credentialshiçbir zaman yoktur.credentials: "omit"kullanın — API çerezleri zaten yok sayar.
Origin başlığı olmayan bir istek (sizin sunucunuz) için CORS koşulu yoktur.
Müşteri token’ı olmadan kişisel veri yok
Bölüm başlığı “Müşteri token’ı olmadan kişisel veri yok”API, istek içindeki tüm çerezleri hiçbir şey okumadan önce kaldırır; böylece hiçbir alışveriş oturumu, üye sepeti ya da B2B fiyatı herkese açık bir token’la taşınamaz ve hiçbir katalog ya da sepet yanıtında ad, e-posta, telefon, adres veya sipariş alanı bulunmaz. Alışverişçinin kendi hesabına yalnızca müşteri token’ı ile erişilir (bkz. Müşteri hesapları).
Uç noktalar
Bölüm başlığı “Uç noktalar”| Yöntem | Yol | Ne yapar |
|---|---|---|
| GET | /shop |
Mağaza adı, alan adı, temel ve etkin para birimleri, diller, API sürümü. |
| GET | /products |
Ürünlerden bir sayfa. ?collection=, ?category=, ?sort= (default, newest, title, price-asc, price-desc, best-selling), ?page= (1–500), ?limit= (1–100, varsayılan 24). |
| GET | /products/{handle} |
Tek ürün: açıklama, görseller, seçenekler, fiyatı, eski fiyatı ve stok durumuyla varyantlar. |
| GET | /collections |
Listelenen koleksiyonlar. |
| GET | /collections/{handle} |
Tek koleksiyon (ürünleri: /products?collection={handle}). |
| GET | /categories |
Kategori ağacı. |
| GET | /search?q= |
q ile eşleşen ürünler (2–200 karakter), alaka sırasıyla, /products gibi sayfalı. |
| POST | /cart |
Yeni, boş bir sepet. |
| GET | /cart |
X-Ciqra-Cart-Token ile belirtilen sepet. |
| POST | /cart/lines |
Varyant ekle: { "variantId", "quantity", "properties", "components", "note" }. |
| PUT | /cart/lines/{lineId} |
Satırın adedini ayarla (0 siler). |
| DELETE | /cart/lines/{lineId} |
Satırı kaldır. |
| POST | /checkout |
Bu sepet için mağazanın ödeme sayfasına tek kullanımlık bağlantı. |
Yalnızca mağazanın anonim bir ziyaretçisinin görebildiği döner: taslaklar, yalnız üyelere açık ürünler ve pazarın
satmadığı ürünler yoktur (404).
Dil ve para birimi
Bölüm başlığı “Dil ve para birimi”- Dil:
Accept-Languageya da?locale=tr. Mağazada o dil varsa adlar, açıklamalar ve bağlantılar o dilde gelir. - Para birimi: mağaza etkinleştirdiyse
X-Ciqra-Currency: USDya da?currency=USD; aksi halde temel para birimi. API çağıranın ülkesinden tahmin yapmaz; aynı istek her zaman aynı yanıtı verir.
Tutarlar, yanlarında belirtilen para biriminde ondalık sayılardır ({ "amount": 19.9, "currencyCode": "EUR" }) ve çevrilmiş olarak gelir.
Sepet çerezle değil, başlıkla taşınır:
POST /cart(ya da sepetsiz ilkPOST /cart/lines)X-Ciqra-Cart-Token: g-…döndürür — istemci tarafında saklayın.- Her sepet çağrısında
X-Ciqra-Cart-Tokenolarak gönderin.
Satır eklemek, mağazanın ürün sayfasının kurallarının aynısını uygular: stok (satılabilir olandan fazlası asla eklenmez), kişiselleştirme alanları, paket seçimleri, hediye notu ve pazar fiyat listeleri. Ret, koduyla döner:
| Durum | error |
Anlamı |
|---|---|---|
| 404 | variant_not_found |
Burada satışta böyle bir varyant yok. |
| 409 | out_of_stock |
Eklenecek stok kalmadı. |
| 409 | not_sold_in_market |
Pazarın fiyat listesi bunu satmıyor. |
| 422 | personalization_invalid / bundle_invalid |
Zorunlu alanlar ya da paket seçimleri eksik veya hatalı. |
Bir satırı stoğun üstüne çıkarmak, onu satılabilir adede indirir ve X-Ciqra-Cart-Stock: adjusted ekler.
POST /checkout, { "checkoutUrl", "expiresAt" } döndürür. Alışverişçinin tarayıcısını oraya gönderin (yönlendirme ya
da yeni sekme). Bağlantı 30 dakika içinde bir kez çalışır: sepeti mağazanın alan adına taşır ve mağazanın ödeme
sayfasını açar. Sonrasında elinizdeki sepet token’ı o sepeti artık göstermez — alışverişçinin ödemede girdiği iletişim
bilgileri ve adres alışverişçi ile mağaza arasında kalır. Bir sonraki sipariş için yeni sepet başlatın.
Müşteri hesapları
Bölüm başlığı “Müşteri hesapları”Alışverişçi mağazanın kendi e-posta ve parolasıyla oturum açar, siz de onun için bir müşteri token’ı alırsınız:
POST /api/storefront/v1/customer/tokenX-Ciqra-Storefront-Access-Token: ciqra_sfp_…Content-Type: application/json
Yanıt { "accessToken": "ciqra_sfc_…", "expiresAt": "…" } biçimindedir. Bunu herkese açık token’la birlikte
X-Ciqra-Customer-Access-Token olarak gönderin.
| Yöntem | Yol | Ne yapar |
|---|---|---|
| POST | /customer/token |
Oturum aç. 401 invalid_credentials, 403 email_not_confirmed, 429 locked / rate_limited, 400 captcha. |
| POST | /customer/token/renew |
Yeni bir token; gönderdiğiniz token çalışmayı bırakır (rotasyon). |
| DELETE | /customer/token |
Bu istemcide oturumu kapat. |
| DELETE | /customer/tokens |
Alışverişçinin tüm istemcilerinde oturumu kapat. |
| GET | /customer/ |
Alışverişçinin profili: ad, e-posta, telefon, dil. |
| GET | /customer/orders |
Alışverişçinin siparişleri, en yeni önce (?page=, ?limit=). |
| GET | /customer/orders/{numara} |
Tek sipariş: satırlar, toplamlar, teslimat adresi, kargo takibi. |
| POST | /customer/orders/{numara}/reorder |
Siparişin ürünlerini, ekleme kurallarının aynısıyla sepete (X-Ciqra-Cart-Token) geri koyar. |
Bilinmesi gerekenler:
- Müşteri token’ı 14 gün yaşar. Yalnızca onu veren mağazada ve yalnızca onu üreten herkese açık token’la birlikte
çalışır; alışverişçi parolasını değiştirdiğinde ya da sıfırladığında, hesap kapatıldığında veya mağaza sahibi herkese açık
token’ı iptal ettiğinde hemen sona erer. Geçerliliğini yitirmiş token
401 invalid_customer_tokendöndürür — yeniden oturum açın. - Hesaplar mağazaya özeldir: iki CIQRA mağazasındaki aynı e-posta, birbiriyle ilgisiz iki hesaptır.
- Mağaza oturum açmayı captcha ile koruyorsa yanıt token’ını
X-Captcha-Tokeniçinde gönderin. - Oturum açmanın, mağazanın hesap başına kilitlemesine ek olarak herkese açık token ve istemci adresi başına kendi bütçesi vardır.
- Her müşteri yanıtı
Cache-Control: no-storedöndürür; müşteri token’ı taşıyan bir katalog okuması asla paylaşılabilir işaretlenmez.
Önbellek
Bölüm başlığı “Önbellek”Katalog okumaları (/shop, /products, /collections, /categories, /search)
Cache-Control: public, max-age=60, stale-while-revalidate=300, bir ETag ve
Vary: Origin, Accept-Language, X-Ciqra-Currency, X-Ciqra-Storefront-Access-Token ile yanıtlanır; 304 için
If-None-Match ile yeniden doğrulayın. CDN’iniz bunları bu anahtarlarla önbelleğe alabilir. Sepet, ödeme ve tüm hatalar
Cache-Control: no-store döndürür.
İstek sınırları
Bölüm başlığı “İstek sınırları”Her token’ın mağaza sahibinin belirlediği bir bütçesi vardır (dakikada 60 ile 6.000 istek, varsayılan 600; 120’ye kadar
ani yük) ve mağazanın tüm token’ları için ortak bir tavanı vardır. Aşılırsa saniye cinsinden Retry-After ile
429 rate_limited alırsınız. Her istemci (web, uygulama, sunucu) için ayrı token kullanın ki biri diğerinin bütçesini harcamasın.
Hatalar
Bölüm başlığı “Hatalar”Her ret, HTTP durumuyla birlikte { "error": "<kod>", "message": "<cümle>" } biçimindedir: 400 hatalı girdi,
401 invalid_token, 403 origin_not_allowed, 404 bulunamadı (mağaza API’yi kapattığında da), 409 çakışma,
422 geçersiz alanlar, 429 rate_limited.