Kozmoz Developer

Başlangıç

Anahtar oluşturmaktan ilk başarılı isteğe kadar, adım adım.

1. Anahtarınızı oluşturun

Satıcı hesabınızla panele girin ve API ve Entegrasyon bölümünü açın. Anahtara bir ad verin, entegrasyonunuzun ihtiyacı olan yetkileri seçin ve oluşturun.

Gizli anahtar bir kez gösterilir. Oluşturma ekranını kapattıktan sonra onu bir daha hiçbir yerden okuyamazsınız — biz de okuyamayız, çünkü veritabanında düz metni değil yalnızca doğrulamaya yarayan karşılığı duruyor. Kaybederseniz eskisini iptal edip yeni bir anahtar oluşturursunuz.

2. Yetkilendirme başlığını hazırlayın

API anahtarı ile gizli anahtarı arasına iki nokta koyup base64'e çevirin ve Authorization başlığında gönderin.

Kurulum
apiKey    = kzm_7QF3MHKD2NRAX9TB
apiSecret = P4XQ9HD2KMR7TB3NVYWZ5CJF8LGA6SEU

base64("kzm_7QF3MHKD2NRAX9TB:P4XQ9HD2KMR7TB3NVYWZ5CJF8LGA6SEU")
= a3ptXzdRRjNNSEtEMk5SQVg5VEI6UDRYUTlIRDJLTVI3VEIzTlZZV1o1Q0pGOExHQTZTRVU=

Authorization: Basic a3ptXzdRRjNNSEtEMk5SQVg5VEI6UDRYUTlIRDJLTVI3VEIzTlZZV1o1Q0pGOExHQTZTRVU=

Yukarıdaki değerler temsilidir; kendi anahtarınızla değiştirin.

3. İlk isteği gönderin

/me ucu, kimliğinizin çalıştığını ve anahtarın hangi yetkileri taşıdığını döner. Entegrasyonu kurarken ilk bunu çağırın: cevap geliyorsa bağlantı tamamdır.

cURL
curl -X GET "https://saglik.kozmoz724.com/api/v1/me" \
  -H "Authorization: Basic a3ptXzdRRjNNSEtEMk5SQVg5VEI6UDRYUTlIRDJLTVI3VEIzTlZZV1o1Q0pGOExHQTZTRVU=" \
  -H "User-Agent: Kozmoz724 - 1042 - SelfIntegration"
C#
using var client = new HttpClient();

var basic = Convert.ToBase64String(
    Encoding.UTF8.GetBytes($"{apiKey}:{apiSecret}"));

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Basic", basic);

// Zorunlu: entegrasyonunuzu tanitan bir deger
client.DefaultRequestHeaders.UserAgent.ParseAdd("Kozmoz724 - 1042 - SelfIntegration");

var response = await client.GetAsync("https://saglik.kozmoz724.com/api/v1/me");
var json = await response.Content.ReadAsStringAsync();
PHP
$basic = base64_encode($apiKey . ':' . $apiSecret);

$ch = curl_init('https://saglik.kozmoz724.com/api/v1/me');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Basic ' . $basic,
    'User-Agent: Kozmoz724 - 1042 - SelfIntegration',
]);

$json = curl_exec($ch);
curl_close($ch);
Python
import requests
from requests.auth import HTTPBasicAuth

response = requests.get(
    "https://saglik.kozmoz724.com/api/v1/me",
    auth=HTTPBasicAuth(api_key, api_secret),
    headers={"User-Agent": "Kozmoz724 - 1042 - SelfIntegration"},
    timeout=30,
)

data = response.json()
Node.js
const basic = Buffer.from(`${apiKey}:${apiSecret}`).toString('base64');

const response = await fetch('https://saglik.kozmoz724.com/api/v1/me', {
  headers: {
    Authorization: `Basic ${basic}`,
    'User-Agent': 'Kozmoz724 - 1042 - SelfIntegration',
  },
});

const data = await response.json();

4. Sayfalama ve artımlı senkronizasyon

Liste uçları page (0'dan başlar) ve size (en fazla 200) alır. Cevaptaki totalPages ile döngüyü kurabilirsiniz.

Her çalışmada bütün kataloğu çekmeyin: updatedSince ile yalnız son çalışmadan bu yana değişenleri alın. Hem çok daha hızlı biter, hem de istek sınırına takılmazsınız.

GET Artımlı ürün senkronizasyonu
GET https://saglik.kozmoz724.com/api/v1/products?updatedSince=2026-08-17T00:00:00Z&page=0&size=200

5. Toplu gönderim ve sonucunu okuma

Ürün, fiyat ve stok yazma uçları isteği anında işlemez. Gönderimi kabul eder, size bir numara döner; işleme kuyrukta yapılır ve sonucu o numarayla sorgularsınız.

Bu, 5.000 ürünlük bir gönderimin istek zaman aşımına uğramaması içindir. Zaman aşımına uğrasaydı aynı 5.000 ürünü tekrar gönderir, yük katlanırdı. Aynı model satır bazında hata vermeyi de mümkün kılıyor: 5.000 üründen 3'ü hatalıysa 4.997'si işlenir ve yalnız 3'ü için sebep döner.

POST 1) Gönder — cevap 202 Accepted
curl -X POST "https://saglik.kozmoz724.com/api/v1/products/price-and-stock" \
  -H "Authorization: Basic a3ptXzdRRjNNSEtEMk5SQVg5VEI6UDRYUTlIRDJLTVI3VEIzTlZZV1o1Q0pGOExHQTZTRVU=" \
  -H "User-Agent: Kozmoz724 - 1042 - SelfIntegration" \
  -H "Content-Type: application/json" \
  -d '{
        "items": [
          { "barcode": "8690000000017", "quantity": 42, "salePrice": 249.90 },
          { "sku": "KZM-1002", "quantity": 0 }
        ]
      }'

# cevap
{ "batchRequestId": "3c7e18a0b6d54f92ae0d47c8b1539f2a", "itemCount": 2, "status": "Queued" }
GET 2) Sonucu sorgula
GET https://saglik.kozmoz724.com/api/v1/products/batch-requests/3c7e18a0b6d54f92ae0d47c8b1539f2a

{
  "status": "Completed",
  "itemCount": 2,
  "succeededCount": 1,
  "failedCount": 1,
  "items": [
    { "lineIndex": 0, "status": "Succeeded", "productId": 9412 },
    { "lineIndex": 1, "status": "Failed",
      "failReason": "Bu barkod veya stok koduna sahip ürününüz bulunamadı." }
  ]
}
lineIndex, gönderdiğiniz listedeki sıradır. Kendi kaydınızla eşleştirmek için bunu kullanın; hangi satırın neden reddedildiğini böyle bulursunuz.
Oluşturulan ürünler yayına kapalı gelir. Görseli ve başlığı görülmeden bir ürünün vitrine düşmemesi için böyle. Kontrol ettikten sonra panelden ya da güncelleme ucundan published: true göndererek yayınlarsınız.

6. İstek sınırı

Her anahtar için, her uç nokta grubunda 10 saniyede 50 istek hakkınız var. Kalan hakkınızı her cevabın X-RateLimit-Remaining başlığında görürsünüz.

Sınırı aşarsanız 429 alırsınız ve Retry-After başlığı kaç saniye beklemeniz gerektiğini söyler. Körlemesine tekrar denemek yerine o süreyi bekleyin — aksi hâlde bekleme uzar.

Gruplar birbirini engellemez. Ürün yüklerken sipariş çekmeye devam edebilirsiniz; sayaç her grup için ayrı tutuluyor.

7. Hata aldığınızda

Bütün hatalar aynı biçimde döner. code alanına göre dallanın — message metnini iyileştirdiğimizde kodunuz bozulmasın.

Hata biçimi
{
  "error": {
    "code": "insufficient_scope",
    "message": "Bu anahtarın gerekli yetkisi yok. Gereken yetki: Ürün yazma.",
    "requestId": "9f2c41ab7d5e4c8fa1b3e6d0c742915e"
  }
}

Her cevapta X-Kozmoz-Request-Id başlığı da bulunur. Sorun bildirirken bu numarayı iletirseniz isteği saniyeler içinde buluruz. Hata kodlarının tam listesi API referansında.

Hazır olduğunuzda API referansına geçin.