İçeriğe geç

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.

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/v1

Sürüm yoldadır. v1’e yalnızca alan eklenir; bir yeniden adlandırma ya da kaldırma v2 olur.

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.1
Host: magaza.example.com
X-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.

Başka bir web kökeninden çağıran tarayıcı, token’ın izinli kökenler listesinde olmalıdır:

  • köken https://alan ya da https://alan:port biçimindedir — yol ve joker yoktur; http:// yalnızca localhost için;
  • eşleşme birebirdir: https://magaza.example.com, https://sahte-magaza.example.com adresini 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 halde 403 origin_not_allowed);
  • yanıtlarda Access-Control-Allow-Credentials hiç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.

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ı).

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: Accept-Language ya 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: USD ya 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:

  1. POST /cart (ya da sepetsiz ilk POST /cart/lines) X-Ciqra-Cart-Token: g-… döndürür — istemci tarafında saklayın.
  2. Her sepet çağrısında X-Ciqra-Cart-Token olarak 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.

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/token
X-Ciqra-Storefront-Access-Token: ciqra_sfp_…
Content-Type: application/json
{ "email": "[email protected]", "password": "…" }

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_token dö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-Token iç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-store döndürür; müşteri token’ı taşıyan bir katalog okuması asla paylaşılabilir işaretlenmez.

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.

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.

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.