Katalog: ürünler ve kategoriler

/api/v1/catalog/products — PUT

PUT/api/v1/catalog/products

Ürünleri toplu yaz

item_ref’e göre ekler ya da günceller (upsert). İçeriği değişmeyen ürün yeniden yazılmaz ve yeniden gömülmez (unchanged). Toplu işte en çok 1000 kayıt; aynı item_ref bir istekte iki kez olamaz (422 duplicate_key). full=true ile listede olmayan ürünler pasiflenir.

• Kimlik doğrulama: Authorization: Bearer rz_live_…
• Kapsam: ingest:catalog
• Paket özelliği: yok (her pakette açık)
• Idempotency-Key: isteğe bağlı (tekrar denemeler için önerilir)

Parametreler

Ad	Yer	Tür	Sınır	Anlamı
full	query	boolean	varsayılan false	true: listede olmayan kayıtlar pasiflenir (ek- önekli elle eklenen bilgi satırları korunur). Tam liste tek istekte (≤1000) gönderilmeli.

İstek gövdesi (application/json)

• ile işaretli alanlar zorunludur. Bilinmeyen alan 422 ile reddedilir.

ProductBatch

Alan	Tür	Sınır	Anlamı
items *	ApiProduct[]	en az 1, en çok 1000	1–1000 kayıt.

ApiProduct

Alan	Tür	Sınır	Anlamı
item_ref *	string	min 1, max 200	Sitedeki kalıcı ürün/varyasyon kimliği.
urun_adi *	string	min 1, max 500	Ürün adı.
urun_kodu	string | null	max 2000	Stok kodu/SKU; yoksa item_ref.
model_adi	string | null	max 2000	Model adı; yoksa addan türetilir.
marka	string | null	max 2000	Marka.
kategori	string | null	max 2000	Kategori yolu, Üst > Alt.
fiyat	number | string | null	≥ 0, ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$	Satış fiyatı (TL).
normal_fiyat	number | string | null	≥ 0, ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$	İndirimsiz fiyat.
indirimde	boolean | null		İndirimde mi.
stokta	boolean	varsayılan true	Stokta mı (varsayılan true).
stok	string | null	max 2000	Müşteriye okunacak stok metni.
renk	string | null	max 2000	Renk.
depolama	string | null	max 2000	Depolama.
bellek	string | null	max 2000	Bellek.
islemci	string | null	max 2000	İşlemci.
ekran	string | null	max 2000	Ekran.
uyumluluk	string | null	max 4000	Uyumlu modeller.
durum	string | null	max 2000	sıfır / ikinci el / teşhir; yoksa ad ve kategoriden türetilir.
kargo_suresi	string | null	max 2000	Kargoya veriliş süresi.
url	string | null	max 2000	Ürün sayfası.
gorsel	string | null	max 2000	Görsel adresi.
kisa_aciklama	string | null	max 4000	Kısa açıklama (HTML düz metne çevrilir).

Örnek

curl -s -X PUT "$RZ_API/api/v1/catalog/products" \
  -H "Authorization: Bearer $RZ_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: urunler-2026-09-27-1" \
  -d '{"items": [{"item_ref": "1234", "urun_adi": "Kablosuz Kulaklık X2", "marka": "Ornek",
        "kategori": "Ses > Kulaklık", "fiyat": 1899.90, "normal_fiyat": 2199.90, "stokta": true,
        "url": "https://magaza.example.com/urun/x2"}]}'

Yanıt 200

Şema: IngestResult

Alan	Tür	Sınır	Anlamı
dataset *	string
inserted *	integer
updated *	integer
unchanged *	integer
deactivated *	integer
skipped *	integer

{
  "dataset": "urun",
  "inserted": 1,
  "updated": 0,
  "unchanged": 0,
  "deactivated": 0,
  "skipped": 0
}

Hata durumları: 401, 403, 404, 413, 422, 429 — bkz. Hatalar ve sınırlar.

---

/api/v1/catalog/products/{item_ref} — DELETE

DELETE/api/v1/catalog/products/{item_ref}

Ürünü pasifle

Ürün silinmez, pasiflenir: asistan artık önermez. Aynı item_ref tekrar gönderilirse yeniden aktifleşir. Kayıt yoksa 404 not_found.

• Kimlik doğrulama: Authorization: Bearer rz_live_…
• Kapsam: ingest:catalog
• Paket özelliği: yok (her pakette açık)
• Idempotency-Key: isteğe bağlı (tekrar denemeler için önerilir)

Parametreler

Ad	Yer	Tür	Sınır	Anlamı
item_ref *	path	string		Sitedeki kalıcı ürün/varyasyon kimliği.

Örnek

curl -s -X DELETE "$RZ_API/api/v1/catalog/products/1234" -H "Authorization: Bearer $RZ_KEY"

Yanıt 200

Şema: IngestResult

Alan	Tür	Sınır	Anlamı
dataset *	string
inserted *	integer
updated *	integer
unchanged *	integer
deactivated *	integer
skipped *	integer

{
  "dataset": "urun",
  "inserted": 0,
  "updated": 0,
  "unchanged": 0,
  "deactivated": 1,
  "skipped": 0
}

Hata durumları: 401, 403, 404, 413, 422, 429 — bkz. Hatalar ve sınırlar.

---

/api/v1/catalog/categories — PUT

PUT/api/v1/catalog/categories

Kategorileri toplu yaz

kategori_id’ye göre upsert. yol verilmezse aynı istekteki üst kategorilerden türetilir (Üst > Alt).

• Kimlik doğrulama: Authorization: Bearer rz_live_…
• Kapsam: ingest:catalog
• Paket özelliği: yok (her pakette açık)
• Idempotency-Key: isteğe bağlı (tekrar denemeler için önerilir)

Parametreler

Ad	Yer	Tür	Sınır	Anlamı
full	query	boolean	varsayılan false	true: listede olmayan kayıtlar pasiflenir (ek- önekli elle eklenen bilgi satırları korunur). Tam liste tek istekte (≤1000) gönderilmeli.

İstek gövdesi (application/json)

• ile işaretli alanlar zorunludur. Bilinmeyen alan 422 ile reddedilir.

CategoryBatch

Alan	Tür	Sınır	Anlamı
items *	ApiCategory[]	en az 1, en çok 1000	1–1000 kayıt.

ApiCategory

Alan	Tür	Sınır	Anlamı
kategori_id *	string	min 1, max 200	Kategori kimliği.
kategori_adi *	string	min 1, max 300	Kategori adı.
ust_kategori_id	string | null	max 2000	Üst kategori kimliği.
yol	string | null	max 2000	Tam yol; yoksa türetilir.
urun_sayisi	integer | null	≥ 0	Ürün sayısı.

Örnek

curl -s -X PUT "$RZ_API/api/v1/catalog/categories?full=true" \
  -H "Authorization: Bearer $RZ_KEY" -H "Content-Type: application/json" \
  -d '{"items": [{"kategori_id": "1", "kategori_adi": "Ses"},
                 {"kategori_id": "12", "kategori_adi": "Kulaklık", "ust_kategori_id": "1", "urun_sayisi": 42}]}'

Yanıt 200

Şema: IngestResult

Alan	Tür	Sınır	Anlamı
dataset *	string
inserted *	integer
updated *	integer
unchanged *	integer
deactivated *	integer
skipped *	integer

{
  "dataset": "kategori",
  "inserted": 2,
  "updated": 0,
  "unchanged": 0,
  "deactivated": 0,
  "skipped": 0
}

Hata durumları: 401, 403, 404, 413, 422, 429 — bkz. Hatalar ve sınırlar.

---

/api/v1/catalog/categories/{kategori_id} — DELETE

DELETE/api/v1/catalog/categories/{kategori_id}

Kategoriyi pasifle

Kategoriyi pasifler; aynı kimlik tekrar gönderilince aktifleşir. Kayıt yoksa 404 not_found.

• Kimlik doğrulama: Authorization: Bearer rz_live_…
• Kapsam: ingest:catalog
• Paket özelliği: yok (her pakette açık)
• Idempotency-Key: isteğe bağlı (tekrar denemeler için önerilir)

Parametreler

Ad	Yer	Tür	Sınır	Anlamı
kategori_id *	path	string		Kategori kimliği.

Örnek

curl -s -X DELETE "$RZ_API/api/v1/catalog/categories/12" -H "Authorization: Bearer $RZ_KEY"

Yanıt 200

Şema: IngestResult

Alan	Tür	Sınır	Anlamı
dataset *	string
inserted *	integer
updated *	integer
unchanged *	integer
deactivated *	integer
skipped *	integer

{
  "dataset": "kategori",
  "inserted": 0,
  "updated": 0,
  "unchanged": 0,
  "deactivated": 1,
  "skipped": 0
}

Hata durumları: 401, 403, 404, 413, 422, 429 — bkz. Hatalar ve sınırlar.