Veri API

Hazır bağlantısı olmayan siteler verilerini Veri API ile kendileri gönderir; aynı API ile görüşmelerde açılan talepleri ve çağrıları da okuyabilirsiniz. Tüm uçlar /api/v1/ altındadır ve firma API anahtarıyla (Authorization: Bearer rz_live_…) çalışır. Kimlik doğrulama ve kapsamlar için Kimlik doğrulama, uç uç ayrıntılar için API başvurusu sayfalarına bakın.

Neyi, hangi uçla

Veri	Uç	Kapsam	Paket
Ürünler	PUT /api/v1/catalog/products, DELETE …/products/{item_ref}	ingest:catalog	her pakette
Kategoriler	PUT /api/v1/catalog/categories, DELETE …/categories/{kategori_id}	ingest:catalog	her pakette
Bilgi içeriği	PUT /api/v1/kb/articles	ingest:kb	her pakette
Siparişler	PUT /api/v1/orders	ingest:orders	her pakette
Sepetler	PUT / GET /api/v1/sepetler, DELETE …/sepetler/{dis_id}	ingest:carts, read:carts	Veri API + Sepetler
Müşteriler	PUT /api/v1/musteriler, DELETE …/musteriler/{dis_id}	ingest:customers	Veri API + Sepetler
Talepler (okuma)	GET /api/v1/requests	read:requests	Veri API
Çağrılar ve konular (okuma)	GET /api/v1/cagrilar, GET /api/v1/konular/istatistik	calls:read	Veri API (+ Konu analitiği)

Besleme uçları (ürün, kategori, bilgi, sipariş) her pakette açıktır, çünkü asistan bu verilerle çalışır.

Temel kurallar

• Upsert: kayıtlar kendi kimliğinize göre (item_ref, kategori_id, id, external_id, dis_id) eklenir ya da güncellenir. İçeriği değişmeyen kayıt yeniden yazılmaz (unchanged).
• Toplu iş: istekte 1–1000 kayıt (items); aynı kimlik bir istekte iki kez olamaz (422 duplicate_key: …). Bilinmeyen alan 422 döner.
• Tam senkron (?full=true): listede olmayan kayıtlar pasiflenir. Tam liste tek istekte (≤1000) gönderilmelidir; daha büyük kataloglarda artımlı gönderip kaldırılanları DELETE ile pasifleyin.
• Sıra dışı istekler: siparişte kayıtlı sürümden eski modified_at taşıyan gönderim yazılmaz; yeni veri ezilmez.
• Gömme: değişen ürün ve bilgi kayıtları için anlamsal arama vektörleri arka planda üretilir; istek beklemez.
• Sınırlar: anahtar başına dakikada 120 istek, gövde en çok 5 MB. Hatalar ve sınırlar →

Örnek: ürün ve sipariş gönderimi

curl

export RZ_API="https://<konsol-adresiniz>"
export RZ_KEY="rz_live_xxx"

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, "stokta": true,
        "url": "https://magaza.example.com/urun/x2"}]}'
# {"dataset":"urun","inserted":1,"updated":0,"unchanged":0,"deactivated":0,"skipped":0}

JavaScript

// Node 18+ (yerleşik fetch)
const API = process.env.RZ_API;
const KEY = process.env.RZ_KEY; // rz_live_xxx

async function putOrders(orders, idempotencyKey) {
  const res = await fetch(`${API}/api/v1/orders`, {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': idempotencyKey,
    },
    body: JSON.stringify({ items: orders }),
  });
  if (res.status === 429) {
    const wait = Number(res.headers.get('Retry-After') ?? 60);
    await new Promise((r) => setTimeout(r, wait * 1000));
    return putOrders(orders, idempotencyKey); // aynı anahtarla güvenle tekrar
  }
  if (!res.ok) throw new Error(`${res.status} ${JSON.stringify(await res.json())}`);
  return res.json(); // { inserted, updated, unchanged, unmapped_statuses }
}

await putOrders([{
  external_id: '98765', number: '98765', status: 'processing',
  customer_name: 'Ayşe Yılmaz', phone: '05321234567', email: '[email protected]',
  items: [{ name: 'Kablosuz Kulaklık X2', qty: 1, total: '1899.90', ref: '1234' }],
  total: '1899.90', carrier: 'Örnek Kargo', tracking_number: '123456789012',
  created_at: '2026-09-24T10:15:00+03:00', modified_at: '2026-09-24T12:00:00+03:00',
}], 'siparis-98765-v3');

PHP (WooCommerce)

<?php
// WooCommerce'te bir sipariş değişince Veri API'ye gönderin (ör. bir eklentide).
add_action('woocommerce_update_order', function ($order_id) {
    $o = wc_get_order($order_id);
    if (!$o) { return; }
    $items = [];
    foreach ($o->get_items() as $item) {
        $items[] = [
            'name'  => $item->get_name(),
            'qty'   => $item->get_quantity(),
            'total' => wc_format_decimal($item->get_total(), 2),
            'ref'   => (string) ($item->get_variation_id() ?: $item->get_product_id()),
        ];
    }
    $body = ['items' => [[
        'external_id'   => (string) $o->get_id(),
        'number'        => (string) $o->get_order_number(),
        'status'        => $o->get_status(),            // ör. processing
        'customer_name' => trim($o->get_billing_first_name() . ' ' . $o->get_billing_last_name()),
        'phone'         => $o->get_billing_phone(),
        'email'         => $o->get_billing_email(),
        'items'         => $items,
        'total'         => wc_format_decimal($o->get_total(), 2),
        'currency'      => $o->get_currency(),
        'created_at'    => $o->get_date_created()->format(DATE_ATOM),
        'modified_at'   => $o->get_date_modified()->format(DATE_ATOM),
    ]]];
    wp_remote_request(RZ_API . '/api/v1/orders', [
        'method'  => 'PUT',
        'timeout' => 10,
        'headers' => [
            'Authorization'   => 'Bearer ' . RZ_KEY,   // rz_live_xxx; wp-config.php'de tanımlayın
            'Content-Type'    => 'application/json',
            'Idempotency-Key' => 'wc-' . $o->get_id() . '-' . $o->get_date_modified()->getTimestamp(),
        ],
        'body'    => wp_json_encode($body),
    ]);
});

WooCommerce kullanıyorsanız çoğu durumda buna gerek yoktur: mağaza bağlantısı ve WooCommerce’in kendi webhook’u aynı işi kodsuz yapar.

Python

import hashlib, json, os, requests

API, KEY = os.environ["RZ_API"], os.environ["RZ_KEY"]  # rz_live_xxx
s = requests.Session()
s.headers["Authorization"] = f"Bearer {KEY}"

def put_products(items, *, full=False):
    """1000'erlik partiler halinde; tam senkron yalnız tek partide mümkündür."""
    for i in range(0, len(items), 1000):
        batch = items[i:i + 1000]
        # Aynı parti için aynı anahtar: ağ hatasından sonra tekrar göndermek güvenlidir.
        key = hashlib.sha256(json.dumps(batch, sort_keys=True).encode()).hexdigest()
        r = s.put(f"{API}/api/v1/catalog/products", params={"full": str(full).lower()},
                  json={"items": batch}, headers={"Idempotency-Key": key}, timeout=30)
        r.raise_for_status()
        print(r.json())

put_products([{"item_ref": "1234", "urun_adi": "Kablosuz Kulaklık X2", "fiyat": 1899.90, "stokta": True}])

Talepleri artımlı çekme

GET /api/v1/requests, talepleri updated_at artan sırada döner. next_cursor’ı saklayıp bir sonraki istekte cursor olarak gönderin; has_more=false ise şimdilik yeni kayıt yoktur. Çağrılar (/api/v1/cagrilar) aynı yöntemle created_at sırasında çekilir.

cursor = load_cursor()                     # ilk seferde None
while True:
    r = s.get(f"{API}/api/v1/requests", params={"cursor": cursor, "limit": 100}, timeout=30).json()
    for item in r["items"]:
        handle(item)
    cursor = r["next_cursor"]
    save_cursor(cursor)
    if not r["has_more"]:
        break

Anında haber almak için bunun yerine webhook’ları kullanın.

Kişisel veri

KVKK

Sipariş, sepet ve müşteri kayıtlarındaki telefon numaraları şifreli saklanır; eşleştirme için yalnız firmaya özel bir özet kullanılır. Okuma uçlarında (talepler, sepetler, çağrılar) telefon ve ad varsayılan olarak maskelidir. Firmanızın yöneticisi Ayarlar → API anahtarları → Kişisel veri ayarını açarsa bu uçlar ve webhook’lar tam numarayı döner. Bu ayarı yalnız verileri işlemek için hukuki dayanağınız varsa ve alıcı sisteminiz yeterince korunuyorsa açın.