API QUICKSTART VE GENEL BAKIŞ
Pazaryeri entegrasyonunu kontrollü adımlarla kurun
Cozmopol Integration API; ürün, kategori, marka, stok, fiyat, sipariş, fatura, soru-cevap ve iade süreçlerini REST tabanlı endpoint'lerle bağlar. Entegrasyonun ilk hedefi yalnız başarılı bir istek göndermek değil; kimlik bilgilerini güvenli tutan, tekrar denenebilir ve izlenebilir bir operasyon akışı kurmaktır.
Entegrasyon ilkeleri
- Temel adres ve veri biçimi
- Yayımlanmış örnekler `https://entegrasyon.cozmopol.net/api/v2` temel adresini ve JSON istek/yanıtlarını kullanır. Endpoint yolu ve HTTP metodunu API referansındaki güncel tanımla eşleştirin.
- Kimlik doğrulama
- Partner Portal'dan alınan API anahtarı ve vendor bilgileriyle çalışılır. Quickstart, vendor bilgileriyle token üretimini opsiyonel akış olarak gösterir ve çağrılarda `Authorization: Bearer` başlığını kullanır. Secret ve token değerleri yalnız sunucu tarafında saklanmalıdır.
- Rate limit ve yeniden deneme
- Genel dokümantasyonda herkese uygulanan sayısal bir istek kotası yayımlanmamıştır. Entegrasyonunuza tanımlanan limitleri partner bilgileriyle doğrulayın; başarısız çağrılarda kontrolsüz döngü yerine artan bekleme, idempotency ve toplu işlem durum takibi uygulayın.
- OAuth ve SDK kapsamı
- Yayımlanmış quickstart API key ve token akışını belgeler; genel bir OAuth yetkilendirme akışı veya belirli programlama dilleri için kararlı SDK listesi sunmaz. Resmî SDK duyurusu yoksa REST endpoint'lerini ve güncel örnekleri kaynak kabul edin.
İlk çağrı neyi doğrular?
Ping isteği temel adrese erişimi, Authorization başlığının iletimini ve JSON yanıtının uygulamanız tarafından okunabildiğini kontrol eder.
`pong` yanıtı ürün entegrasyonunun tamamlandığı anlamına gelmez. Sonraki aşamada kategori ve marka kimliklerini alın, ürün alanlarını doğrulayın, test verisiyle yükleme yapın ve dönen kaydı kontrol edin.
Toplu ürün işlemlerinde dönen batch kimliğini saklayın ve toplu işlem endpoint'i üzerinden sonucu izleyin. Sipariş, stok, fiyat ve iade güncellemelerinde kendi işlem kimliğinizi loglayarak tekrar gönderimleri ayırt edin.
Alan eşlemesini üretime geçmeden önce yazılı hale getirin. Barkod, ürün başlığı, kategori özellikleri, para birimi, vergi, stok ve fiyat alanlarının kaynak sisteminizdeki karşılığını belirleyin. Zorunlu bir alan eksikse kaydı sessizce atlamak yerine doğrulama kuyruğuna alın; böylece katalogdaki kısmi güncellemeler ve veri kayıpları izlenebilir kalır.
HTTP durum kodlarını iş sonucundan ayrı değerlendirin. Başarılı bir bağlantı her kaydın kabul edildiğini garanti etmeyebilir; yanıt gövdesindeki kayıt ve hata ayrıntılarını güvenli loglarda ilişkilendirin. `401` ve `403` yanıtlarında anahtar veya yetki kapsamını, `400` sınıfında istek alanlarını, geçici sunucu ve ağ sorunlarında ise sınırlı yeniden deneme politikasını inceleyin.
API anahtarı ve token değerlerini ortam sırrı olarak yönetin, düzenli rotasyon planı belirleyin ve yalnız ihtiyaç duyan servislerin erişmesine izin verin. İstek loglarında Authorization başlığını, müşteri adreslerini ve diğer kişisel verileri maskeleyin. Test ortamında üretim müşterisi veya gerçek ödeme bilgisi kullanmayın.
API sürümü veya endpoint sözleşmesi değiştiğinde entegrasyonu doğrudan üretimde güncellemeyin. Changelog ve güncel referansı inceleyin, sözleşme testlerini çalıştırın ve küçük bir katalog ya da sipariş kümesiyle kademeli geçiş yapın. Eski ve yeni akışı aynı anda izleyebileceğiniz kısa bir geri dönüş planı operasyon kesintisi riskini azaltır.
Sonraki adımlar
1. Erişimi hazırlayın
Partner Portal üzerinden vendor bilgilerini ve API anahtarını alın. Anahtarı kaynak koda, tarayıcı bundle'ına veya herkese açık loglara eklemeyin.
2. Bağlantıyı sınayın
Token akışını gerekiyorsa tamamlayın, ping ve health endpoint'leriyle ortam erişimini doğrulayın. Durum kodlarını ve güvenli hata özetlerini kaydedin.
3. Katalog sırasını izleyin
Önce kategori, özellik ve marka verilerini eşleyin; ardından ürün oluşturma, listeleme, stok ve fiyat güncelleme akışlarını test edin.
4. Operasyonları tamamlayın
Sipariş durumları, faturalar, müşteri soruları ve iadeler için zamanlanmış veya olay tabanlı görevler kurun. Üretime geçmeden önce başarısız çağrı ve tekrar deneme senaryolarını doğrulayın.