Katalog

Kategoriler ve alan setleri, ürün aktarımı, fiyat ve stok, satış durumu, artımlı senkron ve toplu iş sonucu.

Bu sayfadaki uçlar yalnız Çarşı işletmelerinde (vertical: store) vardır; restoran anahtarıyla çağrılırsa 404 not_available_for_vertical döner. Toplu yazmalar (ürün ekleme, fiyat ve stok, satış durumu) 202 ve bir batchId döner; sonuç GET /batches/{id} ile okunur. Yanıtın kendisi sonuç değildir.

Bu sayfadaki uçlar

Her satır API referansındaki tam tanıma gider — alanlar, yanıt kodları ve deneme konsolu orada.

1. Önce kategorileri çekin

GET/categories

Kanonik kategori ağacı ve her yaprak kategorinin çözülmüş alan seti.

Bu uç iki soruyu birden cevaplar: ürün hangi kategoriye bağlanabilir ve o kategoride hangi alanlar isteniyor. Ağaç platform kataloğudur, işletmeye göre değişmez. Liste sayfasızdır; nextCursor her zaman null döner.

Yanıt

{
  "items": [
    {
      "id": "cm_ornek_kategori", "name": "Örnek Kategori", "parentId": "cm_ornek_ust", "level": 3,
      "leaf": true,                                  // ürün yalnız yaprağa bağlanır
      "attributes": [
        { "id": "garanti_suresi", "required": true, "type": "sayisal", "unit": "ay",
          "min": 24, "max": null, "values": null, "variantAxis": false,
          "allowCustomValue": false, "inheritedFrom": "cm_ornek_ust" }
      ]
    }
  ],
  "nextCursor": null
}

Alan setini kategori taşır, işletme türü değil. Set kalıtımlıdır (en yakın ata kazanır) ama kalıtımı siz hesaplamazsınız; çözülmüş hâli döner. inheritedFrom kalıtımla geldiyse kaynak kategorinin kimliğini verir, kategorinin kendi bildirimiyse null olur. attributes yalnız yaprak kategoride dolu gelir.

2. Ürünleri aktarın

POST/products

Yeni ürün oluşturur. Asenkron, istek başına en çok 1000 kalem.

Bu uç oluşturur, güncellemez. Dükkânda zaten kayıtlı bir ürün kalemde already_exists hatası verir; fiyat ve stok için PUT /products/price-and-stock, satış durumu için PUT /products/status kullanılır. Kalem alanları sunucuda kalem kalem doğrulanır; bir kalemin hatası öbürlerini durdurmaz.

Kalem alanları

Alan	Tip	Açıklama
`name`zorunlu	string	Ürün adı.
`price`zorunlu	number	Sıfırdan büyük sayı. Dizge kabul edilmez.
`taxRate`zorunlu	1 \| 10 \| 20	KDV oranı. Ürünün oranını işletme belirler; eksik oran `tax_rate_required` ile reddedilir.
`barcode`	string	8–14 rakam (boşluk ve tire temizlenir). Model kodu buraya yazılmaz. `sku` yoksa zorunludur.
`sku`	string	Satıcıya özel kalıcı stok kodu; barkodsuz ürün için kullanılır. `barcode` yoksa zorunludur.
`clientReferenceId`	string	Kaynak sistemdeki ürün kimliği: en çok 64 karakter; harf, rakam, `_` ve `-`. İşletmede tekil olmalıdır (`duplicate_reference`). Siparişlerde kalemi bununla eşlersiniz.
`stock`	integer	Gönderilirse stok takibi açılır; hiç gönderilmezse ürün her zaman mevcut sayılır.
`categoryId`	string	`GET /categories` yanıtında `leaf: true` olan bir kategori (`invalid_category`).
`attributes`	object	Kategorinin zorunlu nitelikleri. Zorunlu nitelik eksikse ürün kaydedilir ama satışa çıkmaz (`missing_attribute`). Nitelik değerleri bu uçla saklanmaz; yalnız eksiklik denetlenir.
`brand · unit · weight · description`	string	İsteğe bağlı ürün bilgisi.
`image`	string	Kabul edilmez. Ürün görseli işletme panelinden yüklenir. Dış adresli bir görsel gelirse kalem yazılır ve `image_ignored` uyarısı döner (ileti: Görsel adresi kabul edilmedi; ürün görseli işletme panelinden yüklenir.).

İstek

curl -X POST "https://api.supergelsin.com/api/partner/v1/products" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01" \
  -H "Idempotency-Key: ornek-gonderim-0001" \
  -H "Content-Type: application/json" \
  -d '{"items":[
        {"clientReferenceId":"POS-1042",
         "barcode":"8690000000017",
         "name":"Örnek Süt 1 L",
         "price":42.5,
         "stock":18,
         "taxRate":1,
         "categoryId":"cm_ornek_kategori"}
      ]}'

202 Accepted

{ "batchId": "cm_ornek_is", "status": "QUEUED", "totalItems": 1,
  "expiresAt": "2026-02-07T10:00:00.000Z" }

Idempotency-Key

Değeri siz üretirsiniz ve o gönderime özel olmalıdır. Aynı anahtar ve aynı gövdeyle gelen istek 24 saat boyunca yeni iş açmaz; ilk işin batchId değeri 200 ve idempotent: true ile döner. Aynı anahtar başka bir işlemle ya da farklı bir gövdeyle gelirse 422 idempotency_key_reuse döner. Anahtar 128 karakterden uzunsa istek reddedilmez; değer ilk 128 karakterine kırpılır ve baştaki ile sondaki boşluklar atılır: ilk 128 karakteri aynı olan iki anahtar aynı anahtar sayılır. Sistem arızasıyla FAILED olan iş yeni bir anahtarla yeniden gönderilir; aynı anahtar 24 saat boyunca aynı FAILED işi döndürür.

Kalıcı kimlik gerekir

barcode ya da sku göndermelisiniz. İkisi de yoksa kalem missing_identity ile reddedilir: kalıcı kimliği olmayan ürün her gönderimde yeniden yaratılırdı. clientReferenceId bu boşluğu doldurmaz.

Fiyat sayı olmalı

Dizge kabul edilmez. "1.234,56" ile "1,234.56" farklı entegratörlerden gelir ve ikisi de ayrıştırılabilir görünür; biri bin kat yanlış fiyat yazar. Para alanında tahmin yürütülmez.

3. Sonucu okuyun

GET/batches/{id}

Yanıt

{
  "batchId": "cm_ornek_is", "status": "COMPLETED_WITH_ERRORS", "operation": "product_create",
  "createdAt": "2026-01-31T10:00:00.000Z", "startedAt": "2026-01-31T10:00:02.000Z",
  "finishedAt": "2026-01-31T10:00:09.000Z", "expiresAt": "2026-02-07T10:00:00.000Z",
  "summary": { "totalItems": 6, "successCount": 4, "errorCount": 1, "pendingCount": 1 },
  "errors": [
    { "clientReferenceId": "POS-1042", "barcode": "8690000000017", "errorCode": "already_exists",
      "message": "..." }
  ],
  "pending": [
    { "clientReferenceId": "POS-77", "barcode": null, "pendingReason": "missing_attribute", "message": "..." }
  ],
  "warnings": [
    { "clientReferenceId": "POS-88", "barcode": null, "code": "image_ignored", "message": "..." }
  ]
}

Alan	Tip	Açıklama
`status`	enum	`QUEUED`, `PROCESSING`, `COMPLETED`, `COMPLETED_WITH_ERRORS`, `FAILED`. `COMPLETED_WITH_ERRORS` görürseniz `errors[]` dizisini okuyun. `FAILED`: hiçbir kalem işlenmedi (`failureReason` sebebi söyler).
`operation`	enum	`product_create · price_stock · product_status`
`errors[]`	array	Hatalı kalemler (`errorCode`, `message`). Yalnız sorunlu kalemler saklanır; başarılı kalemler listelenmez.
`pending[]`	array	Hata değil: kaydedilmiş ama satışa çıkmamış kalemler. `pendingReason` sebebi söyler: `new_master_review` (yeni ürün kaydı incelemede), `missing_attribute` (zorunlu nitelik eksik), `restricted_product` (yasaklı ürün şüphesiyle incelemede). Çözüm aynı ürünü yeniden göndermek değildir.
`warnings[]`	array	Başarılı ama uyarılı kalemler (ör. `image_ignored`). Sayaçlara eklenmez; uyarılı başarılı kalem `successCount` içinde zaten vardır.

Eşleştirme dizi sırasıyla değil clientReferenceId (ve varsa barcode) ile yapılır. Sonuçlar 7 gün saklanır (expiresAt); süre dolunca 404 not_found döner. Başka işletmenin ya da başka anahtarın işi de 404 verir. Hata ve uyarı kodlarının tamamı Hata Kodları sayfasındadır.

4. Günlük iş: fiyat ve stok

PUT/products/price-and-stock

Entegratör trafiğinin büyük bölümü budur.

Gövde

{ "items": [
    { "barcode": "8690000000017", "price": 44.9, "stock": 12 },
    { "sku": "ORNEK-DOMATES", "stock": 0 }          // ürün tükendi olur
] }

Kalem barcode, sku ya da clientReferenceId ile eşlenir (en az biri gerekir; birden çoğu gönderilirse hepsi aynı ürünü göstermelidir). price ve stock alanlarından en az biri gerekir.
Stok 0 olunca ürün out_of_stock sebebiyle tükendi olur. Stok artışı, işletmenin elle kapattığı ürünü açmaz. Stok gönderen kalemde stok takibi açılır. Değişiklik aramaya yansır.
Aynı dükkânda önce açılmış bir ürün ekleme işi bitmeden sonraki fiyat, stok ve durum işleri beklemeye alınır.

Bu uç yeni ürün yaratmaz. Bulunamayan kalem not_found döner; yeni ürün için POST /products kullanılır. Birden çok ürüne uyan ya da birbirini tutmayan kimlik ambiguous_identity olur. price ve stock alanlarından hiçbiri gönderilmezse kalem empty_update ile reddedilir.

5. Satıştan kaldırma sebep kodludur

PUT/products/status

Gövde

{ "items": [
    { "barcode": "8690000000017", "onSale": false, "reason": "seasonal" },
    { "sku": "ORNEK-DOMATES", "onSale": true }
] }

Stok takibi kapalı üründe de çalışır. Kapalı ürün vitrinde, siparişte ve aramada kapalı görünür. onSale: false için reason zorunludur; açarken sebep temizlenir.

Kabul edilen sebepler

Alan	Tip	Açıklama
`merchant_out_of_stock`	enum	İşletmede kalmadı.
`seasonal`	enum	Mevsimlik ürün.
`supplier`	enum	Tedarik sorunu.
`price`	enum	Fiyat güncellemesi bekleniyor.
`discontinued`	enum	Ürün artık satılmıyor.

6. Artımlı senkron

GET/products

cURL

curl "https://api.supergelsin.com/api/partner/v1/products?updatedSince=2026-01-31T00:00:00Z&limit=200" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01"
# yanıt -> { "items": [...], "nextCursor": "MTc4..." }

curl "https://api.supergelsin.com/api/partner/v1/products?cursor=MTc4...&limit=200" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01"

Alan	Tip	Açıklama
`limit`	integer	Sayfa boyutu, 1–500; varsayılan 100.
`updatedSince`	ISO 8601	Saat dilimi zorunlu. Bu an ve sonrasında değişen ürünleri getirir (sınır dahildir).
`cursor`	string	Önceki yanıttaki nextCursor. nextCursor null ise akışın sonuna gelinmiştir.

Sıralama updatedAt artan, ardından id artandır. İmleç bu çift üzerinden ilerlediği için sayfalar arasında kayıt atlanmaz. Bozuk imleç hata değildir; akışı baştan başlatır. Arşivlenen ürün akıştan düşmez, status: ARCHIVED olarak kalır. Stok takibi kapalıysa stock alanı null döner; 0 ile karıştırılmamalıdır.

Ürün alanları

Alan	Tip	Açıklama
`status`	enum	Öncelik sırası: `ARCHIVED`, `REJECTED`, `PENDING_REVIEW`, ardından pasif ya da satışta olmayan için `OFF_SALE`, aksi hâlde `ACTIVE`. `PENDING_REVIEW` ve `REJECTED` ürünler panelden düzeltilir.
`onSale`	boolean	Müşteriye şu an satışta mı.
`offSaleReason`	string \| null	Satıştan kaldırma sebebi (ör. `out_of_stock`, `merchant_out_of_stock`, `seasonal`, `supplier`, `price`, `discontinued`, `moderation`).
`trackStock`	boolean	Stok takibi açık mı.

Katalog

Kategoriler ve alan setleri, ürün aktarımı, fiyat ve stok, satış durumu, artımlı senkron ve toplu iş sonucu.

Bu sayfadaki uçlar

Her satır API referansındaki tam tanıma gider — alanlar, yanıt kodları ve deneme konsolu orada.

1. Önce kategorileri çekin

GET/categories

Kanonik kategori ağacı ve her yaprak kategorinin çözülmüş alan seti.

Yanıt

{
  "items": [
    {
      "id": "cm_ornek_kategori", "name": "Örnek Kategori", "parentId": "cm_ornek_ust", "level": 3,
      "leaf": true,                                  // ürün yalnız yaprağa bağlanır
      "attributes": [
        { "id": "garanti_suresi", "required": true, "type": "sayisal", "unit": "ay",
          "min": 24, "max": null, "values": null, "variantAxis": false,
          "allowCustomValue": false, "inheritedFrom": "cm_ornek_ust" }
      ]
    }
  ],
  "nextCursor": null
}

2. Ürünleri aktarın

POST/products

Yeni ürün oluşturur. Asenkron, istek başına en çok 1000 kalem.

Kalem alanları

Alan	Tip	Açıklama
`name`zorunlu	string	Ürün adı.
`price`zorunlu	number	Sıfırdan büyük sayı. Dizge kabul edilmez.
`taxRate`zorunlu	1 \| 10 \| 20	KDV oranı. Ürünün oranını işletme belirler; eksik oran `tax_rate_required` ile reddedilir.
`barcode`	string	8–14 rakam (boşluk ve tire temizlenir). Model kodu buraya yazılmaz. `sku` yoksa zorunludur.
`sku`	string	Satıcıya özel kalıcı stok kodu; barkodsuz ürün için kullanılır. `barcode` yoksa zorunludur.
`clientReferenceId`	string	Kaynak sistemdeki ürün kimliği: en çok 64 karakter; harf, rakam, `_` ve `-`. İşletmede tekil olmalıdır (`duplicate_reference`). Siparişlerde kalemi bununla eşlersiniz.
`stock`	integer	Gönderilirse stok takibi açılır; hiç gönderilmezse ürün her zaman mevcut sayılır.
`categoryId`	string	`GET /categories` yanıtında `leaf: true` olan bir kategori (`invalid_category`).
`attributes`	object	Kategorinin zorunlu nitelikleri. Zorunlu nitelik eksikse ürün kaydedilir ama satışa çıkmaz (`missing_attribute`). Nitelik değerleri bu uçla saklanmaz; yalnız eksiklik denetlenir.
`brand · unit · weight · description`	string	İsteğe bağlı ürün bilgisi.
`image`	string	Kabul edilmez. Ürün görseli işletme panelinden yüklenir. Dış adresli bir görsel gelirse kalem yazılır ve `image_ignored` uyarısı döner (ileti: Görsel adresi kabul edilmedi; ürün görseli işletme panelinden yüklenir.).

İstek

curl -X POST "https://api.supergelsin.com/api/partner/v1/products" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01" \
  -H "Idempotency-Key: ornek-gonderim-0001" \
  -H "Content-Type: application/json" \
  -d '{"items":[
        {"clientReferenceId":"POS-1042",
         "barcode":"8690000000017",
         "name":"Örnek Süt 1 L",
         "price":42.5,
         "stock":18,
         "taxRate":1,
         "categoryId":"cm_ornek_kategori"}
      ]}'

202 Accepted

{ "batchId": "cm_ornek_is", "status": "QUEUED", "totalItems": 1,
  "expiresAt": "2026-02-07T10:00:00.000Z" }

Idempotency-Key

Kalıcı kimlik gerekir

Fiyat sayı olmalı

Dizge kabul edilmez. "1.234,56" ile "1,234.56" farklı entegratörlerden gelir ve ikisi de ayrıştırılabilir görünür; biri bin kat yanlış fiyat yazar. Para alanında tahmin yürütülmez.

3. Sonucu okuyun

GET/batches/{id}

Yanıt

{
  "batchId": "cm_ornek_is", "status": "COMPLETED_WITH_ERRORS", "operation": "product_create",
  "createdAt": "2026-01-31T10:00:00.000Z", "startedAt": "2026-01-31T10:00:02.000Z",
  "finishedAt": "2026-01-31T10:00:09.000Z", "expiresAt": "2026-02-07T10:00:00.000Z",
  "summary": { "totalItems": 6, "successCount": 4, "errorCount": 1, "pendingCount": 1 },
  "errors": [
    { "clientReferenceId": "POS-1042", "barcode": "8690000000017", "errorCode": "already_exists",
      "message": "..." }
  ],
  "pending": [
    { "clientReferenceId": "POS-77", "barcode": null, "pendingReason": "missing_attribute", "message": "..." }
  ],
  "warnings": [
    { "clientReferenceId": "POS-88", "barcode": null, "code": "image_ignored", "message": "..." }
  ]
}

Alan	Tip	Açıklama
`status`	enum	`QUEUED`, `PROCESSING`, `COMPLETED`, `COMPLETED_WITH_ERRORS`, `FAILED`. `COMPLETED_WITH_ERRORS` görürseniz `errors[]` dizisini okuyun. `FAILED`: hiçbir kalem işlenmedi (`failureReason` sebebi söyler).
`operation`	enum	`product_create · price_stock · product_status`
`errors[]`	array	Hatalı kalemler (`errorCode`, `message`). Yalnız sorunlu kalemler saklanır; başarılı kalemler listelenmez.
`pending[]`	array	Hata değil: kaydedilmiş ama satışa çıkmamış kalemler. `pendingReason` sebebi söyler: `new_master_review` (yeni ürün kaydı incelemede), `missing_attribute` (zorunlu nitelik eksik), `restricted_product` (yasaklı ürün şüphesiyle incelemede). Çözüm aynı ürünü yeniden göndermek değildir.
`warnings[]`	array	Başarılı ama uyarılı kalemler (ör. `image_ignored`). Sayaçlara eklenmez; uyarılı başarılı kalem `successCount` içinde zaten vardır.

4. Günlük iş: fiyat ve stok

PUT/products/price-and-stock

Entegratör trafiğinin büyük bölümü budur.

Gövde

{ "items": [
    { "barcode": "8690000000017", "price": 44.9, "stock": 12 },
    { "sku": "ORNEK-DOMATES", "stock": 0 }          // ürün tükendi olur
] }

Kalem barcode, sku ya da clientReferenceId ile eşlenir (en az biri gerekir; birden çoğu gönderilirse hepsi aynı ürünü göstermelidir). price ve stock alanlarından en az biri gerekir.
Stok 0 olunca ürün out_of_stock sebebiyle tükendi olur. Stok artışı, işletmenin elle kapattığı ürünü açmaz. Stok gönderen kalemde stok takibi açılır. Değişiklik aramaya yansır.
Aynı dükkânda önce açılmış bir ürün ekleme işi bitmeden sonraki fiyat, stok ve durum işleri beklemeye alınır.

5. Satıştan kaldırma sebep kodludur

PUT/products/status

Gövde

{ "items": [
    { "barcode": "8690000000017", "onSale": false, "reason": "seasonal" },
    { "sku": "ORNEK-DOMATES", "onSale": true }
] }

Stok takibi kapalı üründe de çalışır. Kapalı ürün vitrinde, siparişte ve aramada kapalı görünür. onSale: false için reason zorunludur; açarken sebep temizlenir.

Kabul edilen sebepler

Alan	Tip	Açıklama
`merchant_out_of_stock`	enum	İşletmede kalmadı.
`seasonal`	enum	Mevsimlik ürün.
`supplier`	enum	Tedarik sorunu.
`price`	enum	Fiyat güncellemesi bekleniyor.
`discontinued`	enum	Ürün artık satılmıyor.

6. Artımlı senkron

GET/products

cURL

curl "https://api.supergelsin.com/api/partner/v1/products?updatedSince=2026-01-31T00:00:00Z&limit=200" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01"
# yanıt -> { "items": [...], "nextCursor": "MTc4..." }

curl "https://api.supergelsin.com/api/partner/v1/products?cursor=MTc4...&limit=200" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01"

Alan	Tip	Açıklama
`limit`	integer	Sayfa boyutu, 1–500; varsayılan 100.
`updatedSince`	ISO 8601	Saat dilimi zorunlu. Bu an ve sonrasında değişen ürünleri getirir (sınır dahildir).
`cursor`	string	Önceki yanıttaki nextCursor. nextCursor null ise akışın sonuna gelinmiştir.

Ürün alanları

Alan	Tip	Açıklama
`status`	enum	Öncelik sırası: `ARCHIVED`, `REJECTED`, `PENDING_REVIEW`, ardından pasif ya da satışta olmayan için `OFF_SALE`, aksi hâlde `ACTIVE`. `PENDING_REVIEW` ve `REJECTED` ürünler panelden düzeltilir.
`onSale`	boolean	Müşteriye şu an satışta mı.
`offSaleReason`	string \| null	Satıştan kaldırma sebebi (ör. `out_of_stock`, `merchant_out_of_stock`, `seasonal`, `supplier`, `price`, `discontinued`, `moderation`).
`trackStock`	boolean	Stok takibi açık mı.