TotalApp Dökümanlar
Ctrl K
Anasayfa
EN | TR
Uygulamaya Git

Amazon SP-API Entegrasyonu

Amazon Selling Partner hesabınızı Login with Amazon (LWA) ile bağlayın, FBA stoğunu ve siparişleri senkronize edin ve stok seviyeleri, sipariş hacmi ve gelir hakkında Yapay Zeka Asistanı'na soru sorun.

Genel Bakış

Amazon Entegrasyonu ekranı (E-ticaret → Pazaryeri Yönetimi → Amazon), TotalApp ile Amazon Selling Partner API (SP-API) hesabınız arasındaki bağlantı merkezidir. LWA OAuth bilgilerinizi yönetir, refresh token'ınızı kısa ömürlü erişim token'larıyla değiştirir, FBA stoğunu ve güncel siparişleri çeker, kullanılan SP-API uç noktalarını listeler ve pazaryeri verilerinize doğrudan erişimi olan gömülü bir Yapay Zeka Asistanı sunar.

SP-API Kimlik Doğrulama Mantığı

Amazon SP-API üç bileşenden oluşur: LWA (Login with Amazon — Client ID & Secret uygulamanızın kimliğini doğrular), her satıcıya özel bir Refresh Token (satıcı uygulamanıza izin verdiğinde üretilir; tenant bazında AES-256 ile şifrelenerek saklanır) ve müşteri PII verilerini içeren uç noktalar için istek anında alınan bir Restricted Data Token (RDT). Eski uygulamalar için AWS IAM Role (SigV4) yolu hâlâ desteklenir ancak artık zorunlu değildir.

LWA Client ID/Secret → Refresh Token (tenant) → Access Token (1s) → RDT (PII) → Sipariş / Stok / Feed

Yalnızca Sunucu Taraflı API Çağrıları

LWA token uç noktasına (api.amazon.com) ve bölgesel SP-API uç noktasına (ör. sellingpartnerapi-na.amazon.com) yapılan tüm istekler tarayıcınızdan değil TotalApp sunucusundan yapılır. Client Secret ve Refresh Token'ınız asla tarayıcıya açık edilmez ve CORS kısıtlamaları önlenir.

Amazon SP-API Geliştirici Kurulum & Onboarding Rehberi

TotalApp'in ihtiyaç duyduğu her şeyi elde etmek için bu dört aşamayı sırayla izleyin. Geliştirici ekibinizin baştan sona takip edebileceği pratik bir kontrol listesidir.

1Amazon Seller Central Geliştirici Profili

  1. Seller Central'da Apps & Services → Develop Apps bölümüne gidip geliştirici olarak kaydolun.
  2. Geliştirici Profili'ni doldurun: uygulamanızı, eriştiğiniz veriyi, güvenlik & PII işleme pratiklerinizi açıklayın.
  3. Doğru rolleri seçin. Alıcı adı/adresi (Orders API) çekiyorsanız PII (Kişisel Veri) rollerini talep etmelisiniz — onay için net bir veri kullanım gerekçesi gerekir.
  4. Püf noktası: uygulama açıklamasını veri akışları konusunda spesifik ve dürüst tutun. Belirsiz veya aşırı geniş PII talepleri, reddin en yaygın sebebidir. Yalnızca gerçekten kullandığınız rolleri isteyin.

2AWS Hesabı & IAM Role Kurulumu (yalnızca eski SigV4)

Yalnızca uygulamanız eski SigV4 imzalama sözleşmesini kullanıyorsa gereklidir. Yeni LWA-only uygulamalar bu adımı atlayabilir.

  1. SP-API ARN'i üzerinde execute-api:Invoke yetkisi veren bir IAM Policy oluşturun.
  2. Bir IAM User (AssumeRole çağıran) ve imzalama için üstlenilecek bir IAM Role oluşturun.
  3. IAM Role üzerinde Trust Relationship (Güven İlişkisi) yapılandırarak IAM User'ın (veya SP-API servis principal'ının) sts:AssumeRole yapmasına izin verin.
  4. Role ARN değerini kaydedin — TotalApp'te opsiyonel AWS Role ARN olarak girin.

3LWA (Login with Amazon) Uygulama Kaydı

  1. Develop Apps altındaki uygulamanızda LWA credentials bölümünü açın.
  2. Client ID ve Client Secret değerlerini üretin/kopyalayın.
  3. Satıcı izin verdikten sonra authorization code'u alacak OAuth Redirect URI('ler)ini yapılandırın.
  4. Kendi kendine yetkilendirme için uygulamayı Draft durumunda bırakın, üçüncü taraf satıcılar için yayınlayın.

4Auth Akışı (OAuth 2.0 + opsiyonel AWS STS)

  1. Satıcı LWA yetkilendirme ekranından onay verir → Amazon bir Authorization Code ile geri yönlendirir.
  2. Kodu POST https://api.amazon.com/auth/o2/token adresinde (grant_type=authorization_code) bir Refresh Token ile değiştirin. Tenant bazında AES-256 şifreli saklayın.
  3. Çağrı anında refresh token'ı 1 saatlik Access Token ile değiştirin (grant_type=refresh_token). TotalApp bunu tenant bazında önbelleğe alır.
  4. (Eski) SigV4 gerekliyse geçici AWS kimlik bilgileri için STS AssumeRole çağırıp her isteği SigV4 ile imzalayın. Aksi halde x-amz-access-token içindeki erişim token'ı yeterlidir.

TotalApp'te Bağlantıyı Kurma

Ayarlar → Entegrasyonlar → E-Ticaret → Amazon bölümünü açın ve şunları girin:

AlanNerede bulunurÖrnek
LWA Client IDSeller Central → Develop Apps → LWA credentialsamzn1.application-oa2-client...
LWA Client SecretSeller Central → Develop Apps → LWA credentialsamzn1.oa2-cs.v1...
Refresh TokenLWA yetkilendirme (consent) akışındanAtzr|IwEBI...
Marketplace IDSatış yaptığınız Amazon pazaryeriATVPDKIKX0DER (US)
BölgePazaryeri grubunuza uygun NA / EU / FEna
AWS Role ARN (opsiyonel)Yalnızca eski SigV4 uygulamaları içinarn:aws:iam::…:role/SPAPIRole

Amazon Entegrasyonu ekranında Satıcı Bağlantısı panelini açın ve Bağlantıyı Test Et düğmesine tıklayın. TotalApp bir LWA token değişimi yapar (OAuth bilgilerinizi doğrular) ve kapsamı onaylamak için bir sayfa FBA stoğu çeker.

Amazon Hesabını Bağla düğmesi

Amazon Hesabını Bağla düğmesi, LWA yetkilendirme akışını başlatmak için Amazon onay ekranını açar. Üretimde, yönlendirme geri çağrısı authorization code'u refresh token ile değiştirir ve bu token tenant'ınız için şifreli olarak saklanır.

API Uç Noktaları & Backend Modülleri

Ekran bir API Uç Noktaları referans paneli sunar. {marketplaceId} gibi yol parametreleri çağrı sırasında doldurulur. Müşteri PII verisi dönen uç noktalar RDT olarak işaretlenir.

Kimlik Doğrulama — api.amazon.com

MetotYolAmaç
POST/auth/o2/tokenLWA erişim token değişimi (refresh → access)
POST/tokens/2021-03-01/restrictedDataTokenRestricted Data Token (PII)

Veri API'leri — sellingpartnerapi-<bölge>.amazon.com

MetotYolModül
GET/orders/v0/orders (RDT)getOrders & getOrderItems
GET/fba/inventory/v1/summariesgetInventorySummaries
POST/feeds/2021-06-30/documentssubmitFeed (fiyat/stok kataloğu)

Rate Limit & Retry

SP-API bir token bucket algoritması kullanır ve operasyon başına hız aşıldığında HTTP 429 döner. TotalApp, geçici throttling'in bir senkronizasyonu bozmaması için jitter'lı üstel geri çekilme ile (en fazla 3 deneme) yeniden dener.

Senkronizasyon Ayarları & Kayıtlar

Senkronizasyon Ayarları paneli Otomatik Sipariş Çekme ve Stok Senkronizasyonu anahtarlarını sunar. Senkronizasyon Kayıtları paneli her bağlantı testini, stok ve sipariş senkronizasyonunu zaman damgası, kapsam ve başarı/başarısızlık detayıyla kaydeder; böylece son etkinliği bir bakışta denetleyebilirsiniz.

Yapay Zeka Asistanı

Yapay Zeka Asistanı paneli Amazon verilerinize sohbet tabanlı bir arayüz sunar. Bilgiler yapılandırıldığında TotalApp, canlı FBA stoğunuzu ve son 30 günün siparişlerini sunucu tarafında çeker ve bağlam olarak sağlar.

Neler Sorabilirsiniz

  • Stok soruları: “Hangi SKU'lar tükendi veya karşılanabilir stoğu düşük?”
  • Sipariş soruları: “Son 30 günkü siparişlerimi duruma göre özetle.”
  • Gelir soruları: “Toplam gelirim ne kadar ve en çok satanlar hangileri?”

Writer Engine Desteği

Asistan, Ayarlar → Agentic → Writer Engine seçiminize uyar. Local CLI veya Hosted API modunda canlı Amazon verisi sunucu tarafında çekilerek bağlama eklenir. Ollama, Local LLM veya Web LLM modunda istek tamamen istemci tarafında çalışır ve canlı pazaryeri verisi kullanılamaz — veriye dayalı raporlar için Local CLI veya Hosted API'ye geçin.

Rapor Olarak Kaydetme

Yapay zeka yanıt verdikten sonra yanıtın altında bir Rapor Olarak Kaydet düğmesi belirir. Tıkladığınızda yanıt, sorunuz ve içinde bulunulan ay ile otomatik olarak adlandırılıp E-ticaret Raporları altına kaydedilir.

Sık Sorulan Sorular

Hâlâ AWS IAM Role ve SigV4 imzalamaya ihtiyacım var mı?
Hayır, yeni uygulamalar için gerekmez. 2023 SP-API güncellemesinden bu yana x-amz-access-token başlığındaki bir LWA erişim token'ı yeterlidir. TotalApp, opsiyonel AWS Role ARN alanını yalnızca hâlâ SigV4 sözleşmesindeki eski uygulamalar için tutar.
Refresh Token'ım nerede saklanır?
Refresh Token, tenant bazında AES-256 ile şifrelenerek saklanır. Tüm LWA token değişimleri ve SP-API çağrıları TotalApp sunucusunda gerçekleşir — Client Secret ve Refresh Token asla tarayıcıya açık edilmez.
Sipariş detayları neden Restricted Data Token (RDT) gerektiriyor?
Müşteri PII verisi (alıcı adı, teslimat adresi) dönen uç noktalar, tam kaynağa ve veri elemanlarına kapsamlanmış bir RDT gerektirir. TotalApp, Orders API'yi çağırmadan önce /tokens/2021-03-01/restrictedDataToken adresinden otomatik olarak bir RDT ister.
Bilgileri girdikten hemen sonra test başarısız oluyor. Ne kontrol etmeliyim?
Önce LWA Client ID/Secret ve Refresh Token'ın doğru olduğunu onaylayın (LWA token hatası bunlardan birinin yanlış olduğu ya da token'ın iptal edildiği anlamına gelir). Ardından Marketplace ID ve Bölge'nin eşleştiğini onaylayın — ör. bir US pazaryeri (ATVPDKIKX0DER) na bölgesini kullanmalıdır.

Sonraki Adımlar