Gereksinimlerin Özeti
- Method: GET
- Path: /api/v1/products
- Kimlik Doğrulama: X-API-Key header
- Yanıt Formatı: application/json
- Temel Yanıt Yapısı: {"result": {"products": [...]}}
- Karakter Kodlaması: UTF-8
1. Kimlik Doğrulama
Erişimi kısıtlamak için bir erişim anahtarı tanımlayın:
X-API-Key: <YOUR_API_KEY>
Anahtar gönderilmezse API kimlik doğrulaması olmadan da çalışabilir; ancak her zaman bir anahtar kullanmanızı öneririz.
2. API Endpoint
Hizmetimiz, ürünlerin listesini döndüren bir GET endpoint'i gerektirir.
Örnek URL:
https://your-domain.com/api/v1/products
3. Yanıt Yapısı
Başarı Durumu: 200 OK
Yanıt gövdesinde, bir products dizisi içeren bir result anahtarına sahip bir nesne bulunmalıdır. Ayrıca bir pagination nesnesi de döndürmenizi öneririz.
{
"result": {
"products": [
{
"id": 123,
"name": "Product Name",
"url": "/product/sample-product",
"product_categories": [
{ "name": "Category 1" },
{ "name": "Category 2" }
],
"product_attributes": [
{
"name": "description",
"value": "Product description as HTML or text"
}
],
"product_variants": [
{
"stock_number": 10,
"price": 250000,
"product_attributes": [
{ "name": "color", "value": "red" },
{ "name": "size", "value": "L" }
]
},
{
"stock_number": 5,
"price": 260000,
"product_attributes": [
{ "name": "color", "value": "blue" },
{ "name": "size", "value": "M" }
]
}
]
}
]
}
}
4. Önemli Alan Uyumluluk Notları
Zorunlu Alanlar:
- id: Benzersiz ürün tanımlayıcısı (zorunlu - tam sayı olmalıdır)
- name: Ürün adı (zorunlu)
- url: Göreceli (relative) olmalıdır (örneğin /product/123). Bunu web sitenizin ana alan adına ekleyeceğiz (zorunlu)
- product_variants: Varyantların dizisi. Her varyant şunları içerir:
stock_number: Tam sayı (stok). stock_number <= 0 olan varyantlar yok sayılır.
price: Tam sayı (fiyat) veya "unavailable" metni. Eğer price = "unavailable" ise o varyant yok sayılır.
product_attributes: { name, value } dizisi (renk, beden, garanti gibi).
Not: Bir ürünün hiç geçerli varyantı yoksa (veya hiç varyantı yoksa) sistemimizden kaldırılır.
İsteğe Bağlı Alanlar:
- product_categories: En azından bir name alanı içeren nesnelerin dizisi. Boş bir dizi olabilir.
- product_attributes: O ürünün açıklamasını eklemek için { name, value } yapısına sahip nesnelerin dizisi.
Açıklamalar için, mutlaka name = "description" olan bir öğe döndürün. value HTML olabilir. Biz onu metne dönüştürürüz. Not: Şu anda yalnızca description nesnesi kabul edilir. product_attributes içindeki diğer nesneler yok sayılır ve ürün bilgisine eklenmez.
5. Bizim Tarafımızdaki Birleştirme ve Doğrulama Kuralları
- Bir ürünün yalnızca tek bir varyantı varsa ve bu varyant geçerliyse (stock_number > 0 ve price != "unavailable"), onu "basit" (simple) bir ürün olarak kabul eder ve price ile stock değerlerini doğrudan ürünün kendisi için saklarız.
- Bir ürünün birden fazla varyantı varsa:
- Geçersiz varyantlar kaldırılır.
- Geçerli varyantlar, öznitelik kümelerine göre (örneğin {color: red, size: L}) gruplanır ve aynı özniteliklere sahip varyantların stokları toplanır.
- Filtrelemeden sonra geçerli varyant grubu kalmazsa ürün elenir.
6. Hata Durumları
- 401 Unauthorized: Erişim anahtarı gönderilmezse veya yanlışsa.
- 429 Too Many Requests: İstek limiti (rate limit) aşılırsa.
- 500 Internal Server Error: Sizin tarafınızda beklenmeyen bir hata oluşursa.
7. cURL ile Hızlı Test Örneği
-H "Accept: application/json" \ -H "X-API-Key: YOUR_API_KEY"
8. Sizin İçin Son Kontrol Listesi
- [ ] GET /api/v1/products endpoint'ini uygulayın
- [ ] Yanıtı {"result": {"products": [...]}} formatında döndürün
- [ ] Her ürün için şu anahtarlar bulunsun: id, name, url, product_categories, product_attributes, product_variants
- [ ] product_attributes içinde name = "description" olan bir öğe bulunsun (HTML kullanılabilir)
- [ ] Varyantlar stock_number, price ve product_attributes içersin
- [ ] stock_number <= 0 veya price = "unavailable" olan varyantları yanıttan kaldırın (ya da hiç göndermeyin)
- [ ] X-API-Key ile kimlik doğrulaması etkin
- [ ] Hata durum kodları ve hata formatı tanımlı
9. Web Sitesini Vardast Platformuna Ekleme
- Web sitesi türü olarak "Other" (Diğer) seçin
- Web sitesi adresinizi girin
- Token bölümüne erişim anahtarınızı girin
10. Ürün Örnekleri
10.1 Tek Geçerli Varyantlı Basit Ürün
{
"result": {
"products": [
{
"id": 501,
"name": "Plain T-Shirt",
"url": "/p/tshirt-plain",
"product_categories": [{ "name": "Clothing" }],
"product_attributes": [
{
"name": "description",
"value": "<p>High-quality cotton t-shirt</p>"
},
{ "name": "brand", "value": "ACME" }
],
"product_variants": [
{
"stock_number": 15,
"price": 249000,
"product_attributes": [{ "name": "size", "value": "M" }]
}
]
}
]
}
}
10.2 Öznitelik Gruplamalı Çok Varyantlı Ürün
{
"result": {
"products": [
{
"id": 777,
"name": "Running Shoes",
"url": "/p/run-shoe",
"product_categories": [{ "name": "Shoes" }, { "name": "Sports" }],
"product_attributes": [
{
"name": "description",
"value": "<p>Suitable for daily running</p>"
}
],
"product_variants": [
{
"stock_number": 5,
"price": 1899000,
"product_attributes": [
{ "name": "color", "value": "black" },
{ "name": "size", "value": 42 }
]
},
{
"stock_number": 2,
"price": 1899000,
"product_attributes": [
{ "name": "color", "value": "black" },
{ "name": "size", "value": 42 }
]
},
{
"stock_number": 0,
"price": 1899000,
"product_attributes": [
{ "name": "color", "value": "black" },
{ "name": "size", "value": 43 }
]
},
{
"stock_number": 3,
"price": "unavailable",
"product_attributes": [
{ "name": "color", "value": "blue" },
{ "name": "size", "value": 42 }
]
}
]
}
]
}
}
Yukarıdaki örnekte yalnızca (black, 42) varyantları geçerlidir ve stokları toplanır (=7). Diğer varyantlar kaldırılır.
10.3 Geçerli Varyantı Olmayan Ürün (Kaldırılacaktır)
{
"result": {
"products": [
{
"id": 888,
"name": "Headphones",
"url": "/p/headphone",
"product_categories": [{ "name": "Audio" }],
"product_attributes": [
{ "name": "description", "value": "<p>Strong bass sound</p>" }
],
"product_variants": [
{
"stock_number": 0,
"price": 990000,
"product_attributes": [{ "name": "color", "value": "black" }]
},
{
"stock_number": 1,
"price": "unavailable",
"product_attributes": [{ "name": "color", "value": "black" }]
}
]
}
]
}
}
Bu durumda hiç geçerli varyant yoktur; bu ürün elenecektir.