Yardım › Pazaryeri

Pazaryeri Entegrasyonu — Sıfırdan Rehber

Trendyol, Hepsiburada, Tokopedia ya da Shopee'de satış yapan firmada siparişler çoğu zaman satıcı panelinden elle kopyalanır, stok her akşam platform platform düzeltilir ve platformun ay sonunda yatırdığı para neden eksik geldi bilinmez. Pazaryeri penceresi bu işi HNR'ye bağlar: platform siparişleri HNR'ye satış siparişi olarak iner, paketleme ve kargo bilgisi platforma geri bildirilir, HNR'deki serbest stok ve fiyat platforma gönderilir, iadeler ve platform kesintileri izlenir, dönemin beklenen hakedişi hesaplanır.

1. Genel bakış: platformlar ve olgunluk

Dört gerçek platform ve bir test sürücüsü vardır. Türkiye için Trendyol ve Hepsiburada, Endonezya için Tokopedia ve Shopee; Simülasyon ise gerçek pazaryerine bağlanmadan aynı akışı örnek siparişlerle prova etmenizi sağlar. Bir firma birden çok bağlantı açabilir (aynı platformda iki mağaza da olabilir).

Kimlik bilgileri, canlı banka bağlantısıyla aynı anahtarla (HNR_BANKA_KIMLIK_ANAHTARI) şifrelenir. Anahtar tanımlı değilse pencerede kırmızı uyarı çıkar ve hiçbir platforma bağlanılamaz; anahtarı sistem yöneticisi Node başlatıcısına verir.

2. Akış bir bakışta

1. Bağlantı — sistem yöneticisi Ayarlar'da platformu seçer, kimlik bilgilerini girer, platform carisini ve aralıkları belirler, bağlantıyı test eder.
2. Ürün eşleme — her platform ürünü bir stok kartına bağlanır (elle, CSV/XLSX ya da barkod önerisiyle).
3. Sipariş inişi — yeni siparişler çekilir; eşlemesi tam olan sipariş HNR'ye PZ serisinden satış siparişi olarak yazılır ve stoğu rezerve eder.
4. Paketle → Kargoya ver → Teslim — her adım platforma bildirilir; takip numarası sevkiyattan, platformdan ya da elle gelir.
5. Stok ve fiyat — HNR'deki serbest stok, platform payı ve tampon düşülerek; fiyat KDV dahil olarak platforma gönderilir. Yalnız değişenler gider.
6. İade ve hakediş — platform iadeleri iner ve hata kuyruğunda yapılacak işi gösterir; Pazaryeri hakedişi sekmesi dönemin brüt satışından komisyon, kargo kesintisi, hizmet bedeli ve iadeyi düşer.

3. Bağlantı kurma ve kimlik bilgileri

Bağlantılar Ayarlar › Firma Bilgileri › Pazaryeri bağlantıları bölümündedir ve yalnız sistem yöneticisi tarafından görülür ve yönetilir (pazaryeri yetkisi olan kullanıcılar bile bağlantı ve kimlik ekranını açamaz). Yeni bağlantı için Yeni bağlantı düğmesine basın; form üç adımdır.

1. Pazaryeri — platformu seçin. Kutuda platformun belge başlığı, olgunluk notu ve Platformdan alınacaklar listesi görünür; bilgileri satıcı panelinden önceden toplayın.
2. Kimlik ve ayarlar — bağlantı adı, platform carisi, depo, platformun alanları, aralıklar; sonra Kaydet.
3. Test — Bağlantıyı test et: HNR platforma kimliğiyle bağlanmayı dener. Başarılıysa "Bağlantı testi başarılı" yazar ve durum Çalışıyor olur; değilse hatanın sınıfı gösterilir.

Platform başına istenen alanlar (yıldızlı olanlar zorunlu; 🔒 = gizli kimlik alanı). Alan adları ekranda sürücünün kendi etiketiyle görünür:

• Trendyol: Satıcı ID*, Ortam (canli / test), Kendi kargo anlaşması (hayir / evet — evet ise takip numarası HNR'den Trendyol'a gönderilir), API Key* 🔒, API Secret* 🔒.
• Hepsiburada: Merchant ID*, Entegratör adı (User-Agent), Ortam, Kendi kargo anlaşması, API kullanıcı adı* 🔒, Servis anahtarı* 🔒.
• Tokopedia: fs_id (App ID)*, Shop ID*, Tahmini komisyon oranı (%) (Tokopedia sipariş listesinde komisyon gelmediği için hakediş tahmini bu oranla yapılır), Client ID* 🔒, Client Secret* 🔒.
• Shopee: Partner ID*, Shop ID*, Ortam, Kargoya teslim (dropoff: şubeye bırakma · pickup: kurye alır), Partner Key* 🔒, Access token* 🔒, Refresh token 🔒.
• Simülasyon: Tohum (aynı tohum aynı siparişleri üretir), Ürünler* (satır başına platform ürün kodu|fiyat|ad), Günlük sipariş sayısı, Komisyon oranı (%), Kargodan teslime (dk), İade edilecek sipariş numaraları, Platformda iptal edilecek sipariş numaraları, Para birimi, Kullanıcı adı* 🔒 (demo), Parola* 🔒.

Ortak alanlar her platformda aynıdır:

Bağlantı kartı durumu: Test bekliyor (kaydedildi, test edilmedi ya da ayar değişti), Çalışıyor (son test ya da eşitleme başarılı), Hata. Siparişi olan bağlantı silinemez ve pazaryeri türü değiştirilemez — pasifleştirin (otomatik eşitlemeyi kapatın) ya da yeni bağlantı açın. Siparişi olmayan bağlantı silinince kayıtlı kimlik bilgileri ve ürün eşlemeleri de silinir.

4. Ürün eşleme

Platform, ürünü kendi koduyla tanır; HNR stok kartıyla. Ürün eşleme sekmesi ikisini bağlar. Eşlemenin anahtarı platform ürün kodu + varyant'tır; sipariş kaleminde barkod varsa barkodla da bulunur. Siparişte eşlenmemiş tek bir kalem bile varsa sipariş iner ama HNR'ye yazılmaz (ESLEME_YOK); eşlemeyi ekledikten sonra siparişte HNR'ye yeniden yaz'a basın.

• Elle — üstteki satırda Stok kartı, Platform ürün kodu / barkod, Varyant, Stok payı %, Tampon, Sabit fiyat girip Eşle. Aynı platform ürünü zaten eşliyse eşleme güncellenir.
• Siparişte görülen, eşlenmemiş platform ürünleri — gelen siparişlerde eşlemesi olmayan ürünler sarı kutuda sayılarıyla listelenir; birine tıklayınca kodu forma taşınır, yalnız stok kartını seçersiniz.
• Barkoddan öner — barkodlu stok kartlarınızdan eşlenmemiş olanları öneri olarak listeler (GTIN biçimli 8/12/13/14 haneli barkodlar önce; gider, hizmet ve işçilik kartları hariç). Trendyol ve Simülasyon ürünü barkoduyla tanıdığı için öneri doğrudan kullanılabilir. Hepsiburada, Tokopedia ve Shopee ürünü kendi kimliğiyle tanır: barkoddan yalnız siparişte görülmüş ürünler kesin önerilir, ötekilerde platform ürün kodunu siz girersiniz.
• CSV / XLSX içe aktar — ilk satırı başlık olan dosya: stok, urun (ya da barkod), varyant, sku, fiyat, pay, tampon. Önce önizleme gelir: "İçe aktarma önizlemesi: … yeni, … güncellenecek, … hatalı satır" ve hatalı satırlar numarasıyla; Uygula yazar, Vazgeç bırakır. Bir dosyada en çok 5.000 satır; aynı platform ürünü dosyada iki kez olamaz; stok kartı bulunamayan satır atlanır.

Stok payı % bu platforma serbest stoğun yüzde kaçının açılacağıdır (varsayılan 100). Tampon paydan sonra düşülen güvenlik adedidir (varsayılan 0) — son birkaç ürünü iki platformda aynı anda satmamak için. Sabit fiyat doluysa platforma olduğu gibi o fiyat gönderilir. Eşlemeyi silmek yerine Pasifleştir derseniz o ürünün stok ve fiyatı gönderilmez ama geçmiş siparişler bozulmaz.

5. Siparişler: iniş ve HNR siparişi

Siparişler sekmesinin üstünde dört kutu vardır: Paketlenmeyi bekleyen, Kargoya verilecek, Kargoda, Hata kuyruğu; kutuya tıklamak listeyi o duruma süzer. Platform ve durum süzgeçleri, "Sipariş no, müşteri ya da HNR no ara" kutusu ve sütunlar (Tarih, Platform, Sipariş no, Müşteri, Ürünler, Tutar, Durum, HNR siparişi) buradadır. Satıra tıklayınca sipariş kartı açılır.

İniş tekrarsızdır. Bir sipariş platform numarası ve paket numarasıyla tanınır; aynı sipariş ikinci kez gelirse yeni kayıt açılmaz, yalnız durumu, takip numarası ve kesintileri güncellenir. Pazaryeri siparişi HNR'den silinmez; iptal de bir durumdur ve geçmiş korunur.

HNR siparişi. Eşlemesi tam ve platform carisi seçili olan yeni sipariş, HNR'ye satış siparişi olarak yazılır: cari = platform carisi, belge serisi PZ (ör. PZ2026000001, kanal "pazaryeri"; numara bir kez verilir, yeniden kullanılmaz), açıklama "Trendyol siparişi 123456 / paket … [PZ#…]", teslim tarihi = platformun son kargo tarihi, son müşterinin adı Dikkatine alanında. Kalem fiyatı platformun satış fiyatıdır; KDV dahil geldiği için HNR'ye fiyat = brüt ÷ (1 + KDV/100) olarak yazılır. Yazım yarıda kesilirse açıklamadaki işaretle bulunur; aynı sipariş iki kez yazılmaz. Platform onayı: Tokopedia'da HNR yazımından sonra sipariş platformda onaylanır; öteki platformlarda onay paketleme adımıdır.

Son müşteri bilgileri. Alıcının adı, e-postası, telefonu, TCKN/VKN'si, vergi dairesi, fatura ve teslim adresi pazaryeri kaydında saklanır (HNR siparişinin carisi platform carisidir; son müşteri bilgisi e-Arşiv faturası içindir). Listede ve kartta kimlik numarası maskelidir (ör. *******1234), e-posta a***@…, telefon yalnız son dört hane; adresler gizlidir. Tam hâlini yalnız pazaryeri yönetimi yetkisi olan görür ve her görüntüleme denetim izine yazılır.

Durum makinesi. Sipariş yalnız ileri gider: Yeni → Onaylandı → Paketlendi → Kargoda → Teslim edildi. İptal teslimden önce olur; İade kargodan ya da teslimden sonra. Platformdan gelen geri adım (gecikmiş ya da eski bir sayfa) yok sayılır; iptal ve iade her zaman uygulanır. HNR'den izinsiz bir geçiş denenirse "Sipariş … durumundan … durumuna geçemez." uyarısı çıkar.

HNR siparişi sütunu karşılığın hâlini gösterir: HNR'ye yazılmadı, HNR'ye yazılıyor, HNR siparişi açık, Faturalandı (sipariş HNR'de faturaya dönünce kendiliğinden), HNR siparişi silindi. İki uyarı hata değildir ama göz atın: "Serbest stok yetersiz, sipariş bekleyen (backorder) oldu: …" (sipariş yine yazılır) ve "Sipariş entegrasyondan önce kargoya verilmiş; HNR siparişi yazılmadı (yeniden dene ile yazılabilir)." (bağlantı kurulmadan önce kargolanmış eski siparişler kendiliğinden yazılmaz).

6. Paketle, kargoya ver, teslim

Sipariş kartındaki düğmeler sıradaki adımı yapar ve önce platforma bildirir, sonra durumu yazar; platform reddederse durum değişmez ve hata gösterilir. Listede de satırdaki Paketle / Kargoya ver düğmesiyle aynı iş yapılır.

• Paketle — platforma "hazırlanıyor/paketlendi" bildirilir (Trendyol Picking/Invoiced; Hepsiburada'da paket oluşturulur ve paket numarası siparişe yazılır). Durum Paketlendi.
• Kargoya ver — Takip numarası ve Kargo firması kutuları isteğe bağlıdır. Boş bırakılırsa takip numarası önce Sevkiyat'tan okunur (HNR siparişi ya da onun faturası bir sevkiyattaysa o sevkiyatın takip numarası ve kargo firması), orada da yoksa platformun anlaşmalı kargosundan gelir. Trendyol ve Hepsiburada'da Kendi kargo anlaşması = evet ise takip numarası HNR'den platforma gönderilir; Shopee'de dropoff/pickup ayarı kullanılır. Durum Kargoda.
• Teslim — çoğunlukla platform bildirir. Kendi kargonuzla gönderdiyseniz sevkiyatta teslimat kanıtı (POD) alınınca sipariş kendiliğinden Teslim edildi olur; gerekirse kartta Teslim edildi düğmesiyle elle işaretlenir.
• İptal et — siparişi platformda iptal eder; geri alınamaz, onay sorulur. HNR siparişi açıksa hata kuyruğuna "Platformda iptal; HNR siparişi açık" düşer: kartta HNR siparişini sil ile kapatın (bu, sizin HNR sipariş silme izninizle yapılır).

Sipariş kartının altında İadeler ve Değişiklik izi bölümleri vardır: her durum geçişi kimin yaptığı (ya da "sistem") ve kaynağıyla (elle, platform, sevkiyat POD) kaydedilir.

7. Stok ve fiyat gönderimi

Gönderilen stok şöyle hesaplanır (ATP ile aynı kural):
serbest = mevcut − kullanılamaz (karantina / fason / pasif depo) − açık satış siparişlerinin kalanı (rezerv)
gönderilen = en az 0, aşağı yuvarla(serbest × stok payı / 100) − tampon
Örnek: mevcut 120, karantinada 10, açık siparişlerde 30 → serbest 80; pay %50 → 40; tampon 5 → platforma 35 gider.

Pazaryeri siparişi HNR'ye yazıldığı anda açık satış siparişi olur ve rezervden düşer; platformda da zaten düşmüştür — iki kez sayılmaz. Birden çok platform aynı serbest stoktan kendi payını alır; payların toplamı 100'ü aşabilir (bu yöneticinin bilinçli kararıdır: her platform aynı malı görür, ilk satan alır).

Fiyat şu sırayla bulunur: eşlemedeki Sabit fiyat (olduğu gibi gönderilir) → eşlemeye bağlı fiyat listesi → fiyat motoru (cari = platform carisi, kanal Pazaryeri (e-ticaret), kampanyasız — platform kampanyaları platformda yönetilir) → stok kartının 1. fiyatı. Motorun ve kartın fiyatı KDV hariçtir; Platform fiyatları KDV dahil açıksa net × (1 + KDV/100) gönderilir. Tablodaki Fiyat kaynağı sütunu hangisinin kullanıldığını gösterir.

Stok ve fiyat sekmesi her eşleme için Mevcut, Rezerv, Serbest, Pay / tampon, HNR stok, Platform stok, HNR fiyat, Platform fiyat ve Fiyat kaynağı sütunlarını gösterir; farklı satırlar vurgulanır. Platform değeri normalde son gönderilendir; Platformdaki güncel değeri sorgula işaretlenirse platformdan okunur (bugün Trendyol ve Simülasyon destekler, ötekilerde son gönderilen gösterilir). Değişenleri gönder yalnız son gönderilenden farklı olanları yollar; Hepsini yeniden gönder hepsini zorla gönderir. Sonuç "… ürün gönderildi, … ürün değişmediği için atlandı, … hata." diye özetlenir; hatalı satırın nedeni eşlemede ve hata kuyruğunda görünür.

8. İadeler

Platform iadeleri sipariş çekimiyle birlikte iner (geriye en az 14 gün bakılır); aynı iade numarası bir kez işlenir. İade gelince sipariş İade olur, kalemlerde iade miktarı ve siparişte iade tutarı görünür, kartın İadeler bölümüne platform iade numarası, neden ve tutar yazılır.

HNR'de satış iade faturası kendiliğinden yazılmaz. Sipariş faturalanmışsa hata kuyruğunda "İade faturası bekliyor" görünür — iade faturasını her zamanki gibi belge girişinden kesin. Faturalanmamışsa "Platformda iade; HNR siparişi açık" görünür — kartta HNR siparişini sil ile açık siparişi kapatın. İade tutarı Hakediş'ten düşülür.

9. Hakediş

Pazaryeri hakedişi sekmesi seçilen dönemde (varsayılan bu ay) bağlantı başına bir satır gösterir; iptal edilen siparişler hariçtir:
beklenen hakediş = brüt satış − komisyon − kargo kesintisi − hizmet bedeli − iade
Brüt satış müşterinin ödediği KDV dahil tutardır. Komisyon Trendyol'da kalem komisyon oranından, Shopee'de platformun ödeme (escrow) ayrıntısından, Tokopedia'da bağlantıdaki Tahmini komisyon oranı'ndan, Simülasyon'da ayardaki orandan gelir; sipariş kartında kalem ve sipariş bazında görünür.

Pazaryeri hakedişi sekmesini yalnız pazaryeri yönetimi yetkisi olanlar görür; ötekilerde "Hakediş için pazaryeri yönetimi yetkisi gerekir." yazar.

10. Günlük ve hatalar

Günlük ve hatalar sekmesinin üstünde hata kuyruğu vardır: hata kodu taşıyan siparişler, gönderimi hata veren eşlemeler ve hata durumundaki bağlantılar ("… ardışık hata"). Altında bağlantı başına Son sipariş çekimi, Son stok gönderimi ve otomatik eşitlemenin açık/kapalı olduğu, en altta günlük tablosu (Zaman, Bağlantı, İşlem, Durum, Alınan, Yeni, Güncellenen, Gönderilen, Mükerrer, Mesaj) durur. Kuyruk boşsa "Hata kuyruğu boş." yazar.

HNR'ye yeniden yaz yalnız HNR karşılığı olmayan siparişte görünür ve entegrasyondan önce kargolanmış siparişi de yazar; iptal edilmiş sipariş HNR'ye yazılmaz. Bağlantı düzeyindeki hatalar sınıfıyla gösterilir: Kimlik bilgileri reddedildi, Servis ya da yetki bu hesapta açık değil, Bağlantı ayarları eksik (bu üçünde otomatik deneme durur, sistem yöneticisinin düzeltmesi gerekir), Ağ ya da zaman aşımı, Pazaryeri servisi geçici olarak yanıt vermiyor, Pazaryeri beklenmeyen veri döndürdü (bunlarda otomatik deneme aralığı her hatada ikiye katlanır, en çok 6 saat).

11. Otomatik eşitleme

Otomatik eşitleme varsayılan olarak kapalıdır (HNR platforma kendiliğinden gitmez). Açmak için sistem yöneticisi sunucunun .env dosyasına PAZARYERI_GOREV=1 yazar ve Node servisini yeniden başlatır. Kapalıyken pencere "Otomatik eşitleme kapalı (sunucu ayarı PAZARYERI_GOREV); eşitleme elle yapılır." der ve her şey Şimdi eşitle ile yürür.

• Görev dakikada bir yoklar; her bağlantı kendi Sipariş çekim aralığında sipariş ve iade çeker, Stok gönderim aralığında stok ve fiyat gönderir. Yalnız Otomatik eşitleme işaretli ve kimliği kayıtlı bağlantılar katılır.
• Sunucunun ana firması (HNR_FIRMA) zamanlayıcıyla taranır; bunun için .env'de yazma yetkili servis kullanıcısı (HNR_B2B_KULLANICI) tanımlı olmalıdır. Öteki firmalar, yazma yetkili bir kullanıcı Pazaryeri penceresini ya da Nabız'ı açtığında o kullanıcının kendi oturumuyla arka planda eşitlenir. Hangi firmaların katılacağı PAZARYERI_FIRMALAR (yoksa HNR_FIRMALAR) ile sınırlanabilir.
• Görev yeni sipariş aldığında bağlantıyı kuran yöneticiye "…: … yeni pazaryeri siparişi alındı." mesajı gider; bağlantı üç kez üst üste hata verirse bir kez "… pazaryeri bağlantısı hata veriyor: …" uyarısı gönderilir.

Şimdi eşitle (pencerenin üstünde, bağlantı seçiciyle) görev açık olsun ya da olmasın seçilen bağlantılarda sipariş, iade ve stok/fiyat eşitlemesini hemen yapar ve "Eşitleme bitti: … yeni sipariş, … ürünün stok ve fiyatı gönderildi." der. Aynı bağlantı aynı anda iki kez eşitlenmez ("Bu bağlantı şu an eşitleniyor; biraz sonra yeniden deneyin.").

12. Telefonda (Bahçe + Adım)

7 inçten küçük ekranda Pazaryeri penceresi depo elemanı için sadeleşir: üstte Paketlenecek, Kargoya verilecek ve Hatalı sekmeleri sayılarıyla, "Sipariş no ya da müşteri ara" kutusu ve Yeni siparişleri çek düğmesi; altta büyük dokunma alanlı sipariş kartları (müşteri, il/ilçe, tutar, son kargo).

1. Sipariş — kalemler, son müşteri ve teslim bilgisi.
2. Paketle — tek dokunuşla paketlendi bildirimi.
3. Kargola — takip numarasını yazın ya da boş bırakın (sevkiyattan ya da platformdan alınır) ve kargoya verin.

Sistem yöneticisi bağlantıyı telefondan da kurabilir: Ayarlar'daki form telefonda üç adımlıdır (Pazaryeri · Kimlik ve ayarlar · Test). Ayrıntılar için Mobil rehberine bakın.

13. Yetkiler

Ayarlar › Kullanıcılar'da Pazaryeri grubunda iki yetki vardır: Pazaryeri siparişleri: eşitle, paketle, kargoya ver, iptal; stok ve fiyat gönder (kısaca pazaryeri) ve Ürün eşleme, hakediş ve son müşteri kimliğinin tamamı (pazaryeri_yonet; ilkini de kapsar). Kural sunucuda uygulanır.

Salt okunur kullanıcı pazaryeri kaydı değiştiremez; HNR yazma kapısı kapalıysa hiçbir yazma işlemi yapılmaz. Bağlantı, eşleme, kimlik görüntüleme ve her elle işlem sunucudaki denetim izine (kim, ne zaman, ne) yazılır.

14. Nabız ve Patron Panosu

Telefondaki Nabız ana ekranında Sırada listesine iki satırdan biri düşer: "… yeni pazaryeri siparişi paketlenmeyi bekliyor." ya da "Pazaryeri hata kuyruğunda … kayıt var."; satıra dokunmak Pazaryeri penceresini ilgili sekmede açar. Patron Panosu'nun ciro kutusunda "Pazaryeri: … siparişte … ciro (KDV dahil), platform komisyonu ve kesintileri …." dipnotu görünür; tıklayınca Pazaryeri hakedişi sekmesi açılır.

15. Bu sürümde olmayanlar

Platformda yeni ürün açmak (listeleme, görsel, açıklama — bugün yalnız var olan ürünün stok ve fiyatı gönderilir), satış iade faturasının iadeden kendiliğinden kesilmesi, son müşteri kimliğinin e-Arşiv faturasına kendiliğinden aktarılması (veri hazır, bağlantı noktası kurulu), eşleme ekranında fiyat listesi seçimi, platform kampanya ve kuponlarının yönetimi ile platform faturasının otomatik içe alınması ayrı iş olarak planlanmıştır.

İlgili rehberler: Sevkiyat ve Lojistik · Fiyat ve Kampanya · Canlı banka bağlantısı · Ayarlar · Mobil · Tüm modüller.