Partner API v1

Partner Onboarding

BaZaaRDan Partner API entegrasyonuna başlamak için partner uygulaması oluşturulur, Client ID / Client Secret alınır, gerekli izinler tanımlanır ve test ortamında doğrulama yapılır.

Onboarding Flow

Partner Entegrasyon Akışı

Bu akış ERP, muhasebe, depo, kargo ve özel entegrasyon yazılımlarının BaZaaRDan satıcı verilerine güvenli şekilde bağlanması için kullanılır.

1. Partner Uygulaması Oluşturma

Her entegrasyon için ayrı bir partner uygulaması oluşturulmalıdır. Bu uygulama hangi satıcıya bağlı çalışacağını, hangi izinlere sahip olacağını ve webhook endpointlerini belirler.

App Name Partner uygulamasının görünen adıdır.
Seller Scope Uygulamanın hangi satıcı hesabı için çalışacağını belirler.
Permissions Uygulamanın hangi endpointlere erişebileceğini belirler.
Webhook URL Olay bildirimlerinin gönderileceği partner endpointidir.

2. Client ID ve Client Secret Alma

Partner uygulaması oluşturulduktan sonra Client ID ve Client Secret üretilir. Client ID request headerında gönderilir; Client Secret ise HMAC imzası üretmek için kullanılır.

Environment
BAZAARDAN_API_BASE=https://bazaardan.com/api/partner/v1
BAZAARDAN_CLIENT_ID=YOUR_CLIENT_ID
BAZAARDAN_CLIENT_SECRET=YOUR_CLIENT_SECRET

3. Permission Seçimi

Uygulamaya sadece ihtiyaç duyduğu izinler verilmelidir. Gereksiz yetki verilmesi güvenlik riski oluşturur.

orders:readGET /orders.php

Sipariş listesini okumak için kullanılır.

orders:detailGET /order_detail.php

Tek sipariş kalemi detayını okumak için kullanılır.

stock:writePOST /stock_update.php

SKU veya product_id bazlı stok güncellemek için kullanılır.

4. Postman ile İlk Test

Client bilgileri üretildikten sonra en hızlı test Postman Starter Kit ile yapılır. Önce /ping.php, sonra /orders.php çalıştırılmalıdır.

POSTMAN PAKETİNİ İNDİR POSTMAN REHBERİ

5. SDK ile Entegrasyon

Postman testi başarılı olduktan sonra partner kendi backend dili için uygun SDK starter kit ile entegrasyonu başlatabilir.

PHP SDK PHP backend entegrasyonları için hazır client ve webhook doğrulama helperı.

PHP SDK Rehberi
Node.js SDK Node.js / TypeScript backend entegrasyonları için hazır client ve webhook doğrulama helperı.

Node.js SDK Rehberi

6. Webhook Endpoint Tanımlama

Partner sistemine sipariş veya stok olayları gönderilecekse webhook endpoint tanımlanmalıdır. Webhook endpointi gelen her requestte imza doğrulaması yapmalıdır.

Webhook Headers
X-BZ-WEBHOOK-ID
X-BZ-WEBHOOK-TIMESTAMP
X-BZ-WEBHOOK-SIGNATURE
X-BZ-WEBHOOK-EVENT
Webhook Signature
hash_hmac("sha256", timestamp + "." + raw_body, webhook_secret)

7. Production Checklist

  • Client ID ve Client Secret production ortam değişkenlerinden okunuyor.
  • Client Secret public repository, frontend veya mobil uygulama içinde yok.
  • Ping testi başarılı.
  • Sipariş listeleme testi başarılı.
  • Stok güncelleme kontrollü ürün üzerinde test edildi.
  • Webhook endpointi 2xx cevap döndürüyor.
  • Webhook signature doğrulaması aktif.
  • Permission listesi minimum yetki prensibine göre verildi.