Pazaryeri API Entegrasyonu: Trendyol, Hepsiburada ve N11

Pazaryeri API Entegrasyonuna Genel Bakış

Türkiye'nin en büyük e-ticaret pazaryerlerinden olan Trendyol, Hepsiburada ve N11, satıcıların ürün yönetimi, sipariş takibi ve stok güncelleme gibi işlemlerini otomatikleştirmek için kapsamlı API'ler sunar. Bu yazıda her üç platformun API yapısını, kimlik doğrulama yöntemlerini, temel endpoint'lerini ve entegrasyon sürecinde dikkat edilmesi gereken noktaları detaylı olarak inceleyeceğiz.

Kimlik Doğrulama ve API Erişimi

Trendyol API Kimlik Doğrulama

Trendyol, HTTP Basic Authentication yöntemini kullanır. Satıcı panelinden oluşturulan API anahtarı ve secret bilgileri, her istekte Authorization header'ında Base64 ile encode edilerek gönderilir.

import requests
import base64

TRENDYOL_API_KEY = "your_api_key"
TRENDYOL_API_SECRET = "your_api_secret"
TRENDYOL_SUPPLIER_ID = "your_supplier_id"
TRENDYOL_BASE_URL = "https://api.trendyol.com/sapigw"

credentials = base64.b64encode(
    f"{TRENDYOL_API_KEY}:{TRENDYOL_API_SECRET}".encode()
).decode()

headers = {
    "Authorization": f"Basic {credentials}",
    "Content-Type": "application/json",
    "User-Agent": f"{TRENDYOL_SUPPLIER_ID} - SelfIntegration"
}

Önemli: Trendyol, User-Agent header'ında supplier ID bilgisini zorunlu tutar. Bu değer eksik veya hatalıysa istekler reddedilir.

Hepsiburada API Kimlik Doğrulama

Hepsiburada, satıcılarına merchant ID ve secret key sağlar. Kimlik doğrulama genellikle özel header'lar üzerinden yapılır.

HB_MERCHANT_ID = "your_merchant_id"
HB_SECRET_KEY = "your_secret_key"
HB_BASE_URL = "https://mpop-sit.hepsiburada.com"

hb_headers = {
    "Content-Type": "application/json",
    "merchantId": HB_MERCHANT_ID,
    "secretKey": HB_SECRET_KEY
}

N11 API Kimlik Doğrulama

N11, diğerlerinden farklı olarak SOAP tabanlı bir API sunar. Kimlik bilgileri her SOAP isteğinin body'sinde auth bloğu içinde gönderilir. Ancak N11 ayrıca REST API desteği de sunmaya başlamıştır.

from zeep import Client

N11_APP_KEY = "your_app_key"
N11_APP_SECRET = "your_app_secret"

client = Client("https://api.n11.com/ws/ProductService.wsdl")

auth = {
    "appKey": N11_APP_KEY,
    "appSecret": N11_APP_SECRET
}

# Ürün arama örneği
response = client.service.GetProductList(
    auth=auth,
    pagingData={"currentPage": 0, "pageSize": 20}
)

Ürün Yönetimi

Trendyol'da Ürün Oluşturma

Trendyol'da ürün oluşturmak için önce kategori, marka ve kategori özelliklerini sorgulayıp doğru ID'leri almanız gerekir. Bu adım entegrasyonun en kritik kısmıdır.

# Kategori listesini çekme
categories_url = f"{TRENDYOL_BASE_URL}/product-categories"
response = requests.get(categories_url, headers=headers)
categories = response.json()

# Kategori özelliklerini çekme
cat_id = 411  # Örnek: Tişört kategorisi
attrs_url = f"{TRENDYOL_BASE_URL}/product-categories/{cat_id}/attributes"
attrs = requests.get(attrs_url, headers=headers).json()

# Ürün oluşturma
product_url = f"{TRENDYOL_BASE_URL}/suppliers/{TRENDYOL_SUPPLIER_ID}/v2/products"

product_data = {
    "items": [
        {
            "barcode": "8680000000001",
            "title": "Erkek Pamuklu Basic Tişört",
            "productMainId": "TSH-001",
            "brandId": 1791,
            "categoryId": 411,
            "quantity": 100,
            "stockCode": "TSH-001-M-SYH",
            "dimensionalWeight": 250,
            "description": "Yüksek kalite pamuklu basic tişört",
            "currencyType": "TRY",
            "listPrice": 299.99,
            "salePrice": 249.99,
            "vatRate": 10,
            "cargoCompanyId": 17,
            "images": [
                {"url": "https://example.com/image1.jpg"}
            ],
            "attributes": [
                {"attributeId": 338, "attributeValueId": 4294},
                {"attributeId": 343, "attributeValueId": 4751}
            ]
        }
    ]
}

response = requests.post(product_url, json=product_data, headers=headers)
batch_id = response.json().get("batchRequestId")

Trendyol'da ürün oluşturma asenkron çalışır. Dönen batchRequestId ile işlemin durumunu sorgulayabilirsiniz:

batch_url = f"{TRENDYOL_BASE_URL}/suppliers/{TRENDYOL_SUPPLIER_ID}/products/batch-requests/{batch_id}"
status = requests.get(batch_url, headers=headers).json()

if status["status"] == "COMPLETED":
    print("Ürün başarıyla oluşturuldu")
elif status["status"] == "FAILED":
    for item in status.get("failedItems", []):
        print(f"Hata: {item['reasons']}")

Hepsiburada'da Ürün Listeleme

Hepsiburada'da ürün listeleme süreci, önce Hepsiburada kataloğundaki ürünü eşleştirme (listing) mantığıyla çalışır. Satıcılar mevcut katalog ürünlerine teklif verir.

# Ürün listeleme
listing_url = f"{HB_BASE_URL}/product/api/products/list"

listing_data = {
    "hepsiburadaSku": "HB00000XXXXX",
    "merchantSku": "TSH-001-M",
    "price": 249.99,
    "availableStock": 100,
    "dispatchTime": 2
}

response = requests.post(listing_url, json=listing_data, headers=hb_headers)

Sipariş Yönetimi

Trendyol Sipariş Sorgulama

from datetime import datetime, timedelta

# Son 24 saatteki siparişleri çek
end_date = int(datetime.now().timestamp() * 1000)
start_date = int((datetime.now() - timedelta(days=1)).timestamp() * 1000)

orders_url = (
    f"{TRENDYOL_BASE_URL}/suppliers/{TRENDYOL_SUPPLIER_ID}/orders"
    f"?startDate={start_date}&endDate={end_date}"
    f"&status=Created&page=0&size=50"
)

orders = requests.get(orders_url, headers=headers).json()

for order in orders.get("content", []):
    print(f"Sipariş No: {order['orderNumber']}")
    print(f"Durum: {order['status']}")
    for line in order["lines"]:
        print(f"  Ürün: {line['productName']} x {line['quantity']}")

Sipariş Durumu Güncelleme

Tüm pazaryerlerinde siparişin yaşam döngüsü benzerdir: Yeni → Hazırlanıyor → Kargoya Verildi → Teslim Edildi. Kargoya verildi bilgisi takip numarasıyla birlikte gönderilir.

# Trendyol - Paket kargoya verildi bildirimi
shipment_url = (
    f"{TRENDYOL_BASE_URL}/suppliers/{TRENDYOL_SUPPLIER_ID}"
    f"/shipment-packages/{shipment_package_id}"
)

shipment_data = {
    "status": "Picked",
    "trackingNumber": "1234567890"
}

requests.put(shipment_url, json=shipment_data, headers=headers)

Stok ve Fiyat Güncelleme

Stok ve fiyat güncellemeleri, çoklu satış kanalı yöneten işletmeler için en kritik operasyondur. Bir kanalda satış gerçekleştiğinde diğer kanallardaki stokların anlık güncellenmesi gerekir.

# Trendyol toplu stok/fiyat güncelleme
update_url = f"{TRENDYOL_BASE_URL}/suppliers/{TRENDYOL_SUPPLIER_ID}/products/price-and-inventory"

update_data = {
    "items": [
        {
            "barcode": "8680000000001",
            "quantity": 95,
            "salePrice": 229.99,
            "listPrice": 279.99
        },
        {
            "barcode": "8680000000002",
            "quantity": 0,
            "salePrice": 199.99,
            "listPrice": 249.99
        }
    ]
}

response = requests.post(update_url, json=update_data, headers=headers)

Rate Limiting ve Hata Yönetimi

Pazaryeri API'leri belirli rate limit kurallarına sahiptir. Bu limitleri aşmamak için dikkatli bir istek yönetimi gerekir.

• Trendyol: Dakikada ortalama 60 istek limiti vardır. Batch işlemler tercih edilmelidir.
• Hepsiburada: Yoğun saatlerde throttle uygulanabilir. 429 yanıtlarına karşı retry mekanizması kurulmalıdır.
• N11: SOAP servisleri genel olarak daha yavaş yanıt verir; timeout sürelerinizi buna göre ayarlayın.

import time
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

def create_session_with_retry():
    session = requests.Session()
    retry_strategy = Retry(
        total=3,
        backoff_factor=1,
        status_forcelist=[429, 500, 502, 503, 504],
        allowed_methods=["GET", "POST", "PUT"]
    )
    adapter = HTTPAdapter(max_retries=retry_strategy)
    session.mount("https://", adapter)
    return session

session = create_session_with_retry()

Webhook ve Bildirimler

Trendyol ve Hepsiburada, sipariş değişikliklerini polling yöntemiyle takip etmenizi bekler; yani belirli aralıklarla API'yi sorgularsınız. Ancak bazı entegrasyon iş ortakları webhook desteği sunmaktadır. Polling yaparken aşağıdaki stratejiyi uygulamak faydalıdır:

• Yeni siparişler için her 5-10 dakikada bir sorgulama yapın.
• Stok senkronizasyonunu her 15-30 dakikada bir çalıştırın.
• Son sorgu zamanını saklayarak yalnızca güncellenmiş kayıtları çekin.
• Gece saatlerinde sorgu sıklığını azaltarak API limitlerinden tasarruf edin.

Ortak Entegrasyon Mimarisi

Birden fazla pazaryerini tek merkezden yönetmek için bir abstraction layer oluşturmak en doğru yaklaşımdır:

from abc import ABC, abstractmethod

class MarketplaceClient(ABC):
    @abstractmethod
    def get_orders(self, start_date, end_date):
        pass

    @abstractmethod
    def update_stock(self, sku, quantity):
        pass

    @abstractmethod
    def update_price(self, sku, price):
        pass

class TrendyolClient(MarketplaceClient):
    def get_orders(self, start_date, end_date):
        # Trendyol'a özgü implementasyon
        pass

    def update_stock(self, sku, quantity):
        pass

    def update_price(self, sku, price):
        pass

class HepsiburadaClient(MarketplaceClient):
    def get_orders(self, start_date, end_date):
        # Hepsiburada'ya özgü implementasyon
        pass

    # ...

Bu yaklaşımla iş mantığınız pazaryerine bağımlı olmaktan çıkar ve yeni bir pazaryeri eklenmesi yalnızca yeni bir client sınıfı yazmak anlamına gelir.

Sık Karşılaşılan Sorunlar ve Çözümleri

1. Kategori özellik uyumsuzluğu: Zorunlu özellikleri eksik göndermek en yaygın hata sebebidir. Ürün oluşturmadan önce mutlaka kategori attribute'larını sorgulayın ve required: true olanları eksiksiz doldurun.
2. Barkod çakışması: Aynı barkodla farklı ürün oluşturmaya çalışmak reddedilir. Her varyant için benzersiz barkod kullanın.
3. Resim URL erişim sorunu: Pazaryerleri sağladığınız resim URL'lerine erişemezse ürün reddedilir. CDN üzerinden sunulan, HTTPS destekli ve public erişime açık URL'ler kullanın.
4. Timestamp formatı: Trendyol millisaniye cinsinden Unix timestamp beklerken, N11 farklı tarih formatları kullanabilir. Her platformun beklediği formatı doğrulayın.
5. Karakter limitleri: Ürün başlıkları ve açıklamaları platformdan platforma değişen karakter limitlerine sahiptir. Önceden truncate etmek, API hatasından daha iyidir.

Sonuç

Trendyol, Hepsiburada ve N11 entegrasyonları farklı teknik yaklaşımlar gerektirse de (REST vs SOAP, Basic Auth vs custom header), temel iş mantığı ortaktır. Sağlam bir abstraction katmanı, iyi yapılandırılmış hata yönetimi ve güvenilir bir retry mekanizması ile çoklu pazaryeri entegrasyonunu sürdürülebilir bir şekilde yönetebilirsiniz. Entegrasyona başlamadan önce her platformun güncel API dokümantasyonunu incelemeniz ve sandbox ortamlarında testlerinizi tamamlamanız kritik öneme sahiptir.