Taşeron API’si

REST, JSON ve tek bir başlık. Kataloğunuzu beslemek ve siparişlerinizi yönetmek için ihtiyacınız olan her şey aşağıda.

Kimlik doğrulama

Her isteğe x-api-key başlığını ekleyin. Alternatif olarak Authorization: Bearer de kabul edilir.

curl http://localhost:4000/api/v1/me \
  -H "x-api-key: ohk_live_9f2c1a7b3d4e5f60_…"

Anahtarınız yalnızca oluşturulduğu anda gösterilir; veritabanında yalnızca SHA-256 özeti saklanır. Kaybederseniz kurtarılamaz — panelden yenisini üretin ve eskisini iptal edin.

Hız sınırı

Varsayılan sınır anahtar başına dakikada 600 istektir. Her yanıt x-ratelimit-limit, x-ratelimit-remaining ve x-ratelimit-reset başlıklarını taşır. Sınır aşıldığında 429 ve retry-after döner — bu süreyi bekleyip yeniden deneyin.

Hata biçimi

Tüm hatalar aynı gövdeyi döner. Entegrasyonunuzu insan tarafından okunan message alanına değil, sabit code alanına göre kurun.

{
  "error": {
    "code": "validation_failed",
    "message": "İstek gövdesi doğrulanamadı.",
    "details": [
      { "path": "products.0.price_cents", "message": "Tutar negatif olamaz" }
    ],
    "request_id": "3f2a…"
  }
}

Destek talebi açarken request_id değerini iletin: ilgili isteğin tüm yaşam döngüsünü loglardan çekebiliyoruz.

Uç noktalar

GET/api/v1/me

Anahtarınızın hangi taşerona ait olduğunu ve yetkilerini döner. Entegrasyonu doğrulamak için ilk çağıracağınız uç nokta.

Yanıt

{
  "data": {
    "vendor_id": "a0000000-…",
    "vendor_name": "Teknomarkt",
    "scopes": ["products:read", "products:write", "orders:read"],
    "rate_limit_per_minute": 600
  }
}

POST/api/v1/productsproducts:write

Toplu ürün beslemesi (en fazla 500 kalem). İdempotenttir: aynı external_id ile tekrar gönderim mevcut kaydı günceller, yenisini oluşturmaz. archive_missing:true gönderirseniz bu istekte yer almayan ürünler arşivlenir.

İstek gövdesi

{
  "products": [
    {
      "external_id": "SKU-12345",
      "title": "Apple iPhone 15 128GB Siyah",
      "gtin": "0195949038204",
      "brand": "Apple",
      "category_slug": "telefon",
      "price_cents": 5499900,
      "compare_at_price_cents": 6299900,
      "stock": 42,
      "shipping_fee_cents": 0,
      "free_shipping_threshold_cents": 50000,
      "estimated_delivery_days": 1,
      "image_urls": ["https://cdn.magazaniz.com/iphone15.jpg"],
      "status": "active"
    }
  ],
  "archive_missing": false
}

Yanıt

{
  "data": {
    "received": 1,
    "created": 0,
    "updated": 1,
    "archived": 0,
    "failed": []
  }
}

GET/api/v1/productsproducts:read

Kataloğunuzu sayfalayarak listeler. limit, offset, status ve q parametrelerini alır.

PATCH/api/v1/products/{external_id}products:write

Tek ürünü kısmi günceller. Yalnızca fiyat ve stok değiştiğinde tüm beslemeyi göndermek yerine bu uç noktayı kullanın.

İstek gövdesi

{ "price_cents": 5299900, "stock": 37 }

DELETE/api/v1/products/{external_id}products:write

Ürünü arşivler. Fiziksel silme yapılmaz: geçmiş siparişlerin kalem kayıtları korunur ve yanlışlıkla silinen ürün geri alınabilir.

GET/api/v1/ordersorders:read

Size düşen alt siparişleri kalemleriyle döner. Müşterinin diğer mağazalardan aldığı ürünler görünmez. since parametresiyle artımlı çekim yapabilirsiniz.

PATCH/api/v1/orders/{id}orders:write

Sipariş durumunu ve kargo bilgisini günceller. Durum geçişleri tek yönlüdür; “shipped” için takip numarası zorunludur.

İstek gövdesi

{
  "status": "shipped",
  "carrier": "Yurtiçi Kargo",
  "tracking_number": "1234567890"
}

Kanonik ürün eşleştirme

Ohaaaa, farklı mağazaların aynı ürününü tek bir karşılaştırma kartında toplar. Eşleştirme şu sırayla yapılır:

1. GTIN / barkod — küresel olarak benzersizdir, en güvenilir sinyaldir. Mümkünse daima gönderin.
2. Marka + normalize başlık — barkodsuz beslemeler için. Muhafazakâr davranır: yalnızca tam imza eşleşmesi kabul edilir.
3. Eşleşme yoksa — yeni bir kanonik ürün açılır.

GTIN göndermek doğrudan satışınıza yansır: barkodlu ürünler karşılaştırma kartında rakiplerinizle yan yana görünür ve en iyi toplam fiyatı verdiğinizde ilk sırada listelenirsiniz.