CukoZ Go entegrasyon API’si

Kendi araçlarınızın (ve CukoZ Suite’in) bir Go mağazasını okumasını sağlar. Varsayılan olarak salt-okunurdur; isteğe bağlı olarak (anahtar izniyle) ürün kataloğu gönderilebilir.

Taban adres: https://go.cukoz.com/api/entegrasyon

Kimlik doğrulama

Go panelinde Ayarlar → CukoZ Suite → Bağlantı anahtarı oluştur ile czgo_… anahtarını üretin ve her isteğe gönderin:

GET /api/entegrasyon/ping
X-Go-Api-Key: czgo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Anahtar tek bir mağazayı temsil eder; yanıtlar yalnızca o mağazanın verisidir. Varsayılan izin yalnızca okumadır; PUT /catalog için anahtar “ürün/menü senkronu” izniyle üretilmelidir.
• Mağaza başına tek etkin anahtar vardır; yenisi eskisini iptal eder.
• GET uçları okur; tek yazma ucu PUT /catalog’dur.

Uç noktalar

Uç nokta	Açıklama
GET /ping	Bağlantı testi: { ok, store, slug, currency, version }
GET /customers	Müşteriler. Parametreler: updatedSince (ISO tarih), page, pageSize (1–200, varsayılan 100). En eski değişiklik önce gelir.
GET /orders	Siparişler. Parametreler: since (oluşturma zamanı), page, pageSize.
GET /summary	Son 30 gün: revenue30Minor, orders30, pendingOrders, customers, lowStockVariants
PUT /catalog	Ürün kataloğu gönderme (yalnızca “ürün/menü senkronu” izniyle üretilmiş anahtar; aksi halde 403 scope_required). Aşağıya bakın.

Listeler şu biçimdedir: { "items": [...], "total": 123, "page": 1, "pageSize": 100 }. Tutarlar kuruş (minor unit) cinsindendir.

Örnek: müşteri

{ "id": "cus_…", "name": "Ayşe Demir", "email": "ayse@ornek.com", "phone": "05xx…", "orderCount": 3,
  "totalSpentMinor": 128900, "lastOrderAtUtc": "2026-09-28T10:15:00+00:00", "createdAtUtc": "…", "updatedAtUtc": "…" }

Katalog gönderme (PUT /catalog)

{
  "categories": [{ "externalId": "c-1", "name": "Ana Yemekler", "parentExternalId": null, "sortOrder": 1, "active": true }],
  "products":   [{ "externalId": "i-1", "title": "Adana Kebap", "description": "Acılı", "categoryExternalId": "c-1",
                   "imageUrl": "https://…/adana.jpg", "priceMinor": 25000, "sku": "ADN", "available": true, "active": true }],
  "publishNew": false
}

• Kayıtlar kendi kimliğinizle (externalId) eşleşir; tekrar göndermek güvenlidir (idempotent). En fazla 500 ürün ve 200 kategori.
• Yeni ürün taslak açılır (publishNew: true ise ve active ise satışta). Mevcut ürünün fiyatı, adı, açıklaması, kategorisi ve durumu (available: false → satın alınamaz) güncellenir; satış durumu, adres ve mağazadaki fotoğraflar korunur. active: false olan ürün arşivlenir.
• Yanıt: { categoriesCreated, productsCreated, productsUpdated, productsArchived }.

Artımlı senkron

Son gördüğünüz updatedAtUtc değerini bir sonraki istekte updatedSince olarak verin. CukoZ Suite bu yöntemi kullanır.

Hatalar

Kod	Anlamı
401 api_key_required	X-Go-Api-Key başlığı yok ya da biçimi yanlış
401 api_key_invalid	Anahtar geçersiz ya da iptal edilmiş
403 store_unavailable	Mağaza askıya alınmış
404 not_found	Bilinmeyen uç nokta
429	İstek sınırı aşıldı; kısa süre bekleyin

Hatalar { "error": "kod", "message": "Türkçe açıklama" } biçimindedir.

CukoZ Suite tarafı

Suite, bu API’yi Entegrasyonlar → CukoZ Go sağlayıcısı üzerinden kullanır ve müşterileri Kişiler’e aktarır: Suite bağlantısı.