Satıcı API v1

Genel bakış

Satıcı API, Yenitrend'de satış yapan mağazaların kendi stok, muhasebe ya da sipariş yazılımlarını bağlaması için tasarlanmış bir REST API'dir. Tüm istekler HTTPS üzerinden, JSON gövdeyle yapılır.

Temel adres: https://yenitrend.com/api/seller/v1

Başarılı her yanıtın gövdesi tek bir data alanı taşır:

{
  "data": { … }
}

• Her anahtar tek bir mağazaya aittir; mağaza kimliği yalnız anahtardan alınır. İstekte mağaza kimliği gönderilmez.
• Siparişler sipariş numarasıyla çağrılır (ör. YT7K3M9QX2BD). Ürün, paket, iptal talebi ve iade kimlikleri sayıdır.
• Başka bir mağazanın kaydı her zaman "bulunamadı" (404) döner.
• Bilinmeyen alan ya da sorgu parametresi içeren istek reddedilir (400 invalid_input).
• Teslim bilgisi yalnız okunur; teslim durumu kargodan gelir.
• Entegratör, müşteri kişisel verilerini satıcı adına işleyen taraftır (veri işleyen). Bu verileri yalnız siparişin yerine getirilmesi için kullanabilir. Sipariş listesinde alıcı adı, telefonu ve adresi yoktur (yalnız il/ilçe); detayda iletişim bilgisi teslimden ya da iptalden sonra maskelenir.

Kimlik doğrulama

Her istekte Authorization başlığına anahtarı ekle:

Authorization: Bearer yt_live_<keyId>_<secret>

• Anahtarı satıcı, Satıcı Paneli → API Erişimi sayfasında şifresini tekrar girerek oluşturur ve sana iletir. Anahtar yalnız oluşturulduğu anda bir kez gösterilir.
• Kapsam: Tam (okuma + yazma) ya da Salt okunur. Salt okunur anahtarla yazma isteği 403 insufficient_scope döner.
• Bir mağazanın en fazla 3 aktif anahtarı olabilir. İptal edilen anahtar anında geçersiz olur.
• Anahtarı loglara, hata raporlarına ya da istemci tarafı (tarayıcı, mobil uygulama) koda koyma.
• Askıdaki mağaza sipariş ve iadeleri okuyabilir, askıdan önceki siparişleri kargolayabilir; ürün, iptal ve iade yazma işlemleri 403 seller_not_allowed döner.

Hata biçimi

Hatalı her yanıt aynı zarfla döner. details isteğe bağlıdır ve düzeltmeye yarayan yapısal bilgi taşır (ör. field, reason, alan yolu + mesaj içeren issues).

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": {
    "code": "insufficient_scope",
    "message": "Bu API anahtarı yalnız okuma yetkili; yazma işlemi yapılamaz."
  }
}

İstek limitleri

Limitler mağaza başınadır; mağazanın tüm anahtarları aynı kotayı paylaşır.

Limit aşılınca 429 rate_limited döner; Retry-After başlığı kaç saniye beklemen gerektiğini söyler. Geçersiz anahtarla yapılan tekrarlı istekler IP adresi başına ayrıca sınırlanır. Sipariş iptali ve iptal talebi kabulü, satıcı panelindeki satış sonrası işlemlerle ortak bir limiti paylaşır (tekrar denemeler de bu limitten düşer).

Idempotency-Key

Tüm yazma uçlarında (POST, PUT, DELETE) Idempotency-Key başlığı zorunludur ve UUID biçiminde olmalıdır (dry_run=true isteklerinde isteğe bağlı). Ağ hatasında aynı isteği aynı anahtarla güvenle tekrar gönderebilirsin; işlem bir kez yapılır.

• Aynı anahtar + aynı gövde: ilk isteğin sonucu aynen döner, yanıtta Idempotent-Replayed: true başlığı olur. Sipariş, kargo, iptal ve iade komutlarında gövdede replayed: true da gelir.
• Ürün ve fiyat/stok uçlarında aynı anahtar + farklı gövde: 422 idempotency_key_reused.
• Sipariş iptali, iptal talebi kabulü ve kargo uçlarında aynı anahtar + farklı içerik (ör. farklı takip no): 409 conflict. İade kararlarında tekrar koruması iadenin durumuna bağlıdır; aynı kararı iki kez vermek çift etki doğurmaz.
• POST /stock-price tekrar yanıtı kısa özettir: kalem sonuçları ve kodları döner, önceki/yeni fiyat ve stok ayrıntısı dönmez.
• İlk istek hâlâ işleniyorsa: 409 idempotency_in_progress (+ Retry-After).
• Kayıtlar 7 gün saklanır. Her yeni işlem için yeni bir UUID üret.

dry_run (deneme)

POST /products, PUT /products/{id} ve POST /stock-price uçları ?dry_run=true parametresini kabul eder. İstek gerçek istekle birebir aynı kurallarla doğrulanır, ama hiçbir şey kaydedilmez. Yanıtta dryRun: true olur; ürün oluşturmada durum kodu 201 yerine 200'dür.

• Görseller indirilmez; yalnız adreslerin geçerliliği denetlenir.
• Idempotency-Key isteğe bağlıdır; deneme için kayıt tutulmaz.
• Deneme istekleri de istek limitine sayılır. Ayrı bir test ortamı yoktur.
• POST /products/{id}/status ve sipariş uçları dry_run desteklemez.

Para, tarih ve sayfalama

• Para her zaman kuruş cinsinden tam sayıdır ve yanıtlarda "currency": "TRY" ile gelir. Örnek: 129,90 TL = 12990. Ondalıklı sayı gönderme. Fiyatlar KDV dahildir.
• Tarihler ISO-8601 biçiminde ve UTC'dir. Örnek: 2026-10-01T09:30:00Z.
• Sayfalama: liste uçları page (1'den başlar) ve size (varsayılan 50, en fazla 100) alır. Yanıt { data: { items, page, size, hasMore } } biçimindedir; hasMore false olana kadar sonraki sayfayı iste. Ürün listesi ayrıca toplam kayıt sayısını (total) da döner.
• Gövde application/json olmalıdır (aksi 415); 256 KB'tan büyük gövde 413 döner.

Uç listesi

Yollar temel adrese göredir (https://yenitrend.com/api/seller/v1). Alanların tam şeması OpenAPI dosyasındadır.

Ürün yazma kuralları

• Stok yalnız POST /stock-price ile değişir. PUT /products/{id} mevcut seçeneğin stoğunu değiştirmez; yalnız yeni eklenen seçeneğin (id'siz) başlangıç stoğu verilir.
• stock değeri satılabilir adettir: Yenitrend'de ödemesi beklenen sepet ayırmaları bu değerden otomatik düşülür (yanıtta reserved alanı). Elindeki stoktan, API'den çektiğin ama henüz kargolamadığın siparişleri düşüp gönder.
• Satıcı hesabı işlem sırasında askıya alınırsa kalan kalemler seller_not_allowed sonucuyla döner.
• PUT isteğinde images ve variants zorunlu ve tam listedir. Mevcut seçenekleri id ile gönder; listede olmayan mevcut seçenek pasife alınır. Gönderilmeyen isteğe bağlı ürün alanları mevcut değerini korur. Dikkat: seçenek içinde priceOverride gönderilmezse o seçeneğin özel fiyatı silinir ve ürün fiyatına döner; özel fiyatı korumak için her PUT'ta yeniden gönder.
• Görseller: en fazla 8 adres. Herkese açık https adresleri sunucu indirir; ürünün mevcut /uploads/… yolları olduğu gibi korunur.
• Seçenek boyutunun adı (ör. Beden, Renk) ürünün variantLabel alanıdır; ayrıca kategori özelliği tablosu yoktur.
• Ana katalog açıldığında her ürün bir katalog kaydına bağlanır. POST /products seçeneklerinde catalogItemId (GET /catalog/lookup yanıtından) ya da geçerli bir barcode (GTIN) ver: eşleşen onaylı kayda bağlanır, içerik katalogdan gelir (content_ignored). Katalogda eşleşme yoksa ürün yeni katalog önerisi olarak incelemeye gider; bunun için gövdede contentConsent: true (içeriğin sana ait olduğu ve katalogda diğer satıcıların teklifleriyle kullanılmasına izin verdiğin beyanı), catalogCategoryId (en alt katalog kategorisi) ve birden çok seçenekte her seçenek için axisValues (ör. {"renk":"Siyah"}) gerekir. İzin yoksa 409 invalid_state (details.reason: consent_required), kategori yoksa 400 (details.field: catalogCategoryId); bu durumlarda ürün oluşturulmaz. Yanıttaki catalog alanı bağ durumunu (linked / proposed) ve yayın engelini gösterir. Bu alanlar katalog açılmadan önce bilinmeyen alan sayılır (400).

Ürün oluşturma ve güncelleme yanıtında warnings dizisi şu kodları taşıyabilir:

Örnekler

Kargolanacak siparişleri listele

curl -s "https://yenitrend.com/api/seller/v1/orders?status=open&page=1&size=50" \
  -H "Authorization: Bearer yt_live_<keyId>_<secret>"

{
  "data": {
    "items": [ … ],
    "page": 1,
    "size": 50,
    "hasMore": true,
    "counts": { "open": 4, "new": 2, "preparing": 2, "shipped": 9, "delivered": 31, "cancelled": 1 }
  }
}

Stok ve fiyat güncelle

Önce dry_run=true ile dene; kalem sonuçlarını (ok ya da hata code) kontrol et.

curl -s -X POST "https://yenitrend.com/api/seller/v1/stock-price?dry_run=true" \
  -H "Authorization: Bearer yt_live_<keyId>_<secret>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5d2a7f30-1c6e-4b8a-9f04-7e3b2c1a0d96" \
  -d '{
    "items": [
      { "stockCode": "KLM-001-S", "stock": 25 },
      { "barcode": "8690000000017", "price": 12990 },
      { "variantId": 4182, "price": 24900, "stock": 3 }
    ]
  }'

Sonuç doğruysa aynı gövdeyi dry_run olmadan, yeni bir Idempotency-Key ile gönder:

curl -s -X POST "https://yenitrend.com/api/seller/v1/stock-price" \
  -H "Authorization: Bearer yt_live_<keyId>_<secret>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1c2b9e-8a47-4d0e-9a51-6c2f7e4b1d20" \
  -d '{ "items": [ … ] }'

Paketi kargoya ver

Paket kimliğini sipariş detayından ya da paket açma yanıtından al. Firma kodları GET /carriers ucunda.

curl -s -X POST "https://yenitrend.com/api/seller/v1/orders/YT7K3M9QX2BD/shipments/918/ship" \
  -H "Authorization: Bearer yt_live_<keyId>_<secret>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b0e4c11-52d3-4f7a-8e6b-0c1d2a3b4c5d" \
  -d '{ "carrier": "yurtici", "trackingNo": "123456789012" }'

OpenAPI ve destek

Makinece okunabilir şema (OpenAPI 3.1): /api/seller/v1/openapi.json (anahtar gerekmez).

Sorun ya da öneri için iletişim sayfasından bize yaz. Mesajına anahtarını ekleme; yalnız anahtarın başındaki yt_live_<keyId> kısmı yeterli.

Satıcıysan anahtarını Satıcı Paneli → API Erişimi sayfasından yönetebilirsin.