Bantuan › Marketplace

Integrasi Marketplace — Panduan dari Nol

Perusahaan yang berjualan di Trendyol, Hepsiburada, Tokopedia, atau Shopee biasanya menyalin pesanan dari panel penjual secara manual, membetulkan stok satu per satu di setiap platform tiap sore, dan tidak tahu mengapa dana yang dicairkan platform di akhir bulan kurang. Jendela Marketplace menghubungkan pekerjaan ini ke HNR: pesanan platform masuk ke HNR sebagai pesanan penjualan, info pengemasan dan pengiriman dilaporkan kembali ke platform, stok bebas dan harga di HNR dikirim ke platform, retur dan potongan platform dipantau, dan perkiraan pencairan dana untuk periode itu dihitung.

1. Gambaran umum: platform dan kematangan

Ada empat platform sungguhan dan satu driver uji. Untuk Turki Trendyol dan Hepsiburada, untuk Indonesia Tokopedia dan Shopee; Simulasi memungkinkan Anda melatih alur yang sama dengan pesanan contoh tanpa terhubung ke marketplace sungguhan. Satu perusahaan dapat membuka beberapa koneksi (bahkan dua toko di platform yang sama).

Kredensial dienkripsi dengan kunci yang sama (HNR_BANKA_KIMLIK_ANAHTARI) seperti koneksi bank langsung. Jika kunci belum ditetapkan, peringatan merah muncul di jendela dan tidak ada platform yang dapat dihubungkan; administrator sistem memberikan kunci ke peluncur Node.

2. Alur sekilas

1. Koneksi — administrator sistem memilih platform di Pengaturan, memasukkan kredensial, menentukan kontak platform dan interval, lalu menguji koneksi.
2. Pemetaan produk — setiap produk platform dihubungkan ke satu kartu stok (manual, CSV/XLSX, atau dari saran barcode).
3. Pengambilan pesanan — pesanan baru diambil; pesanan yang semua produknya sudah dipetakan dicatat ke HNR sebagai pesanan penjualan seri PZ dan memesan stok.
4. Kemas → Kirim → Terkirim — setiap langkah dilaporkan ke platform; nomor resi berasal dari pengiriman, dari platform, atau diisi manual.
5. Stok dan harga — stok bebas di HNR dikirim ke platform setelah porsi platform dan penyangga diterapkan; harga dikirim termasuk PPN. Hanya yang berubah yang dikirim.
6. Retur dan pencairan dana — retur platform masuk dan menunjukkan pekerjaan yang harus dilakukan di antrean kesalahan; tab Pencairan dana mengurangkan komisi, potongan ongkir, biaya layanan, dan retur dari penjualan bruto periode itu.

3. Membuat koneksi dan kredensial

Koneksi ada di Pengaturan › Informasi Perusahaan › Koneksi marketplace dan hanya dapat dilihat serta dikelola oleh administrator sistem (pengguna dengan izin marketplace pun tidak dapat membuka layar koneksi dan kredensial). Untuk koneksi baru tekan Koneksi baru; formulirnya terdiri dari tiga langkah.

1. Marketplace — pilih platform. Kotak menampilkan judul dokumen platform, catatan kematangan, dan daftar Yang perlu diperoleh dari platform; kumpulkan datanya dari panel penjual lebih dulu.
2. Kredensial dan pengaturan — nama koneksi, kontak platform, gudang, kolom platform, interval; lalu Simpan.
3. Uji — Uji koneksi: HNR mencoba terhubung ke platform dengan kredensial. Jika berhasil muncul "Uji koneksi berhasil" dan status menjadi Berjalan; jika tidak, kelas kesalahan ditampilkan.

Kolom yang diminta per platform (yang bertanda bintang wajib; 🔒 = kolom kredensial rahasia). Nama kolom tampil di layar dengan label driver itu sendiri:

• Trendyol: Satıcı ID* (ID penjual), Ortam (lingkungan: canli = langsung / test), Kendi kargo anlaşması (kontrak ekspedisi sendiri: hayir = tidak / evet = ya — jika ya, nomor resi dikirim dari HNR ke Trendyol), API Key* 🔒, API Secret* 🔒.
• Hepsiburada: Merchant ID*, Entegratör adı (User-Agent) (nama integrator), Ortam (lingkungan), Kendi kargo anlaşması (kontrak ekspedisi sendiri), API kullanıcı adı* 🔒 (nama pengguna API), Servis anahtarı* 🔒 (kunci layanan).
• Tokopedia: fs_id (App ID)*, Shop ID*, Tahmini komisyon oranı (%) (perkiraan tarif komisi — daftar pesanan Tokopedia tidak memuat komisi, jadi perkiraan pencairan dana memakai tarif ini), Client ID* 🔒, Client Secret* 🔒.
• Shopee: Partner ID*, Shop ID*, Ortam (lingkungan), Kargoya teslim (serah ke ekspedisi — dropoff: paket diantar ke cabang · pickup: kurir menjemput), Partner Key* 🔒, Access token* 🔒, Refresh token 🔒.
• Simulasi: Tohum (seed — seed yang sama menghasilkan pesanan yang sama), Ürünler* (produk, satu per baris: kode produk platform|harga|nama), Günlük sipariş sayısı (pesanan per hari), Komisyon oranı (%) (tarif komisi), Kargodan teslime (dk) (menit dari kirim sampai diterima), İade edilecek sipariş numaraları (nomor pesanan yang diretur), Platformda iptal edilecek sipariş numaraları (nomor pesanan yang dibatalkan di platform), Para birimi (mata uang), Kullanıcı adı* 🔒 (demo), Parola* 🔒 (kata sandi).

Kolom umum sama di setiap platform:

Status kartu koneksi: Menunggu uji (tersimpan, belum diuji atau pengaturan berubah), Berjalan (uji atau sinkronisasi terakhir berhasil), Kesalahan. Koneksi yang memiliki pesanan tidak dapat dihapus dan marketplace-nya tidak dapat diubah — nonaktifkan (matikan sinkronisasi otomatis) atau buat koneksi baru. Menghapus koneksi tanpa pesanan juga menghapus kredensial tersimpan dan pemetaan produknya.

4. Pemetaan produk

Platform mengenali produk dengan kodenya sendiri; HNR dengan kartu stok. Tab Pemetaan produk menghubungkan keduanya. Kunci pemetaan adalah kode produk platform + varian; jika baris pesanan memuat barcode, pemetaan juga ditemukan lewat barcode. Jika satu baris saja belum dipetakan, pesanan masuk tetapi tidak dicatat ke HNR (ESLEME_YOK); setelah menambah pemetaan, tekan Catat ulang ke HNR pada pesanan.

• Manual — di baris atas isi Kartu stok, Kode produk platform / barcode, Varian, Porsi stok %, Penyangga, Harga tetap lalu tekan Petakan. Jika produk platform sudah dipetakan, pemetaannya diperbarui.
• Produk platform belum dipetakan yang terlihat di pesanan — produk tanpa pemetaan di pesanan masuk tercantum di kotak kuning beserta jumlahnya; klik salah satu untuk membawa kodenya ke formulir, lalu cukup pilih kartu stok.
• Sarankan dari barcode — menampilkan kartu stok berbarcode yang belum dipetakan sebagai saran (barcode format GTIN 8/12/13/14 digit lebih dulu; kartu biaya, jasa, dan tenaga kerja dikecualikan). Trendyol dan Simulasi mengenali produk dari barcode, jadi saran dapat langsung dipakai. Hepsiburada, Tokopedia, dan Shopee mengenali produk dengan ID-nya sendiri: saran dari barcode hanya pasti untuk produk yang sudah terlihat di pesanan; untuk yang lain Anda mengisi kode produk platform.
• Impor CSV / XLSX — berkas yang baris pertamanya judul kolom: stok, urun (atau barkod), varyant, sku, fiyat, pay, tampon. Pratinjau muncul dulu: "Pratinjau impor: … baru, … akan diperbarui, … baris salah" beserta nomor baris yang salah; Terapkan mencatat, Batal membatalkan. Paling banyak 5.000 baris per berkas; produk platform yang sama tidak boleh muncul dua kali; baris yang kartu stoknya tidak ditemukan dilewati.

Porsi stok % adalah persentase stok bebas yang dibuka untuk platform ini (bawaan 100). Penyangga adalah jumlah pengaman yang dikurangkan setelah porsi (bawaan 0) — agar beberapa barang terakhir tidak terjual di dua platform sekaligus. Jika Harga tetap diisi, harga itu dikirim ke platform apa adanya. Daripada menghapus pemetaan, Anda dapat Nonaktifkan: stok dan harganya tidak dikirim lagi, tetapi pesanan lama tetap utuh.

5. Pesanan: pengambilan dan pesanan HNR

Di bagian atas tab Pesanan ada empat kotak: Menunggu dikemas, Akan dikirim, Dalam pengiriman, Antrean kesalahan; mengklik kotak menyaring daftar ke status itu. Filter platform dan status, kotak "Cari no. pesanan, pelanggan, atau no. HNR", dan kolom (Tanggal, Platform, No. pesanan, Pelanggan, Produk, Jumlah, Status, Pesanan HNR) ada di sini. Klik baris untuk membuka kartu pesanan.

Pengambilan tidak pernah ganda. Pesanan dikenali dari nomor platform dan nomor paketnya; jika pesanan yang sama datang lagi, tidak dibuat catatan baru, hanya status, nomor resi, dan potongannya yang diperbarui. Pesanan marketplace tidak pernah dihapus dari HNR; pembatalan juga sebuah status dan riwayat tetap tersimpan.

Pesanan HNR. Pesanan baru yang semua produknya sudah dipetakan dan koneksinya punya kontak platform dicatat ke HNR sebagai pesanan penjualan: kontak = kontak platform, seri dokumen PZ (mis. PZ2026000001, saluran "pazaryeri"; nomor diberikan sekali dan tidak dipakai ulang), keterangan "Tokopedia siparişi 123456 … [PZ#…]", tanggal kirim = batas kirim platform, nama pelanggan akhir di kolom Up. (dikatinkan). Harga baris adalah harga jual platform; karena termasuk PPN, dicatat ke HNR sebagai harga = bruto ÷ (1 + PPN/100). Jika pencatatan terputus, pesanan ditemukan lagi lewat penanda di keterangan; pesanan yang sama tidak pernah dicatat dua kali. Konfirmasi platform: di Tokopedia pesanan dikonfirmasi di platform setelah dicatat ke HNR; di platform lain langkah kemas adalah konfirmasinya.

Data pelanggan akhir. Nama, e-mail, telepon, nomor identitas/pajak (TCKN/VKN, NIK/NPWP), kantor pajak, alamat faktur dan alamat pengantaran pembeli disimpan di catatan marketplace (kontak pesanan HNR adalah kontak platform; data pelanggan akhir untuk faktur e-Arsip). Di daftar dan kartu, nomor identitas disamarkan (mis. *******1234), e-mail a***@…, telepon hanya empat digit terakhir; alamat disembunyikan. Nilai lengkap hanya terlihat oleh pengguna dengan izin pengelolaan marketplace, dan setiap tampilan dicatat ke jejak audit.

Mesin status. Pesanan hanya bergerak maju: Baru → Disetujui → Dikemas → Dalam pengiriman → Terkirim. Batal terjadi sebelum diterima; Retur setelah dikirim atau diterima. Langkah mundur dari platform (halaman tertunda atau lama) diabaikan; pembatalan dan retur selalu diterapkan. Jika perpindahan yang tidak diizinkan dicoba dari HNR, muncul peringatan "Pesanan tidak dapat berpindah dari status … ke …."

Kolom Pesanan HNR menunjukkan keadaan padanannya: Belum dicatat ke HNR, Sedang dicatat ke HNR, Pesanan HNR terbuka, Sudah difakturkan (otomatis setelah pesanan difakturkan di HNR), Pesanan HNR dihapus. Dua peringatan bukan kesalahan, tetapi patut dilihat: "Stok bebas kurang, pesanan menjadi backorder: …" (pesanan tetap dicatat) dan "Pesanan sudah dikirim sebelum integrasi. Pesanan HNR tidak dicatat (dapat dicatat dengan coba ulang)." (pesanan lama yang dikirim sebelum koneksi dibuat tidak dicatat otomatis).

6. Kemas, kirim, terkirim

Tombol di kartu pesanan menjalankan langkah berikutnya dan melapor ke platform lebih dulu, lalu mencatat status; jika platform menolak, status tidak berubah dan kesalahannya ditampilkan. Di daftar, tombol Kemas / Kirim pada baris melakukan hal yang sama.

• Kemas — "sedang disiapkan/dikemas" dilaporkan ke platform (Trendyol Picking/Invoiced; di Hepsiburada paket dibuat dan nomornya dicatat ke pesanan). Status Dikemas.
• Kirim — kotak Nomor resi dan Ekspedisi bersifat opsional. Jika kosong, nomor resi lebih dulu dibaca dari Pengiriman (jika pesanan HNR atau fakturnya ada dalam suatu pengiriman, nomor resi dan ekspedisi pengiriman itu), dan jika tidak ada, berasal dari ekspedisi rekanan platform. Di Trendyol dan Hepsiburada, jika Kendi kargo anlaşması = evet (kontrak ekspedisi sendiri = ya), nomor resi dikirim dari HNR ke platform; di Shopee dipakai pengaturan dropoff/pickup. Status Dalam pengiriman.
• Terkirim — biasanya dilaporkan platform. Jika Anda mengirim dengan ekspedisi sendiri, pesanan otomatis menjadi Terkirim setelah bukti serah terima (POD) diambil di Pengiriman; bila perlu, tandai manual dengan tombol Terkirim di kartu.
• Batalkan — membatalkan pesanan di platform; tidak dapat dibatalkan kembali dan meminta konfirmasi. Jika pesanan HNR terbuka, "Batal di platform, pesanan HNR terbuka" masuk ke antrean kesalahan: tutup dengan Hapus pesanan HNR di kartu (memakai izin hapus pesanan HNR Anda sendiri).

Di bagian bawah kartu pesanan ada bagian Retur dan Riwayat perubahan: setiap perubahan status dicatat beserta pelakunya (atau "sistem") dan sumbernya (manual, platform, POD pengiriman).

7. Pengiriman stok dan harga

Stok yang dikirim dihitung sebagai berikut (aturan yang sama dengan ATP):
bebas = stok − tidak dapat dipakai (gudang karantina / subkontrak / nonaktif) − sisa pesanan penjualan terbuka (dipesan)
dikirim = minimal 0, bulatkan ke bawah(bebas × porsi stok / 100) − penyangga
Contoh: stok 120, 10 di karantina, 30 di pesanan terbuka → bebas 80; porsi 50% → 40; penyangga 5 → 35 dikirim ke platform.

Begitu pesanan marketplace dicatat ke HNR, pesanan itu menjadi pesanan penjualan terbuka dan dikurangkan sebagai pesanan; di platform pun sudah berkurang — tidak dihitung dua kali. Beberapa platform masing-masing mengambil porsinya dari stok bebas yang sama; total porsi boleh lebih dari 100 (keputusan sadar pengelola: setiap platform melihat barang yang sama, yang menjual lebih dulu mendapatkannya).

Harga dicari dengan urutan ini: Harga tetap pada pemetaan (dikirim apa adanya) → daftar harga yang terkait pemetaan → mesin harga (kontak = kontak platform, saluran Marketplace (e-commerce), tanpa kampanye — kampanye platform dikelola di platform) → harga 1 kartu stok. Harga mesin dan kartu belum termasuk PPN; jika Harga platform termasuk PPN aktif, yang dikirim neto × (1 + PPN/100). Kolom Sumber harga di tabel menunjukkan mana yang dipakai.

Tab Stok dan harga menampilkan, untuk setiap pemetaan, kolom Stok, Reservasi, Bebas, Porsi / penyangga, Stok HNR, Stok platform, Harga HNR, Harga platform, dan Sumber harga; baris yang berbeda disorot. Nilai platform biasanya nilai terakhir dikirim; jika Tanyakan nilai terkini di platform dicentang, nilai dibaca dari platform (saat ini Trendyol dan Simulasi mendukung; untuk yang lain ditampilkan nilai terakhir dikirim). Kirim yang berubah hanya mengirim yang berbeda dari nilai terakhir; Kirim ulang semua memaksa semuanya. Hasilnya diringkas sebagai "… produk dikirim, … dilewati karena tidak berubah, … gagal."; alasan baris yang gagal tampil di pemetaan dan di antrean kesalahan.

8. Retur

Retur platform diambil bersama pesanan (melihat ke belakang minimal 14 hari); nomor retur yang sama diproses sekali. Saat retur masuk, pesanan menjadi Retur, jumlah retur tampil di baris dan nilai retur di pesanan, serta nomor retur platform, alasan, dan nilainya dicatat di bagian Retur pada kartu.

Di HNR faktur retur penjualan tidak dibuat otomatis. Jika pesanan sudah difakturkan, di antrean kesalahan muncul "Menunggu faktur retur" — buat faktur retur dari input dokumen seperti biasa. Jika belum difakturkan, muncul "Retur di platform, pesanan HNR terbuka" — tutup pesanan terbuka itu dengan Hapus pesanan HNR di kartu. Nilai retur dikurangkan dari pencairan dana.

9. Pencairan dana

Tab Pencairan dana menampilkan satu baris per koneksi untuk periode terpilih (bawaan bulan ini); pesanan yang dibatalkan tidak dihitung:
perkiraan pencairan dana = penjualan bruto − komisi − potongan ongkir − biaya layanan − retur
Penjualan bruto adalah jumlah termasuk PPN yang dibayar pelanggan. Komisi berasal dari tarif komisi baris di Trendyol, dari rincian pembayaran (escrow) platform di Shopee, dari Tahmini komisyon oranı (perkiraan tarif komisi) koneksi di Tokopedia, dan dari tarif di pengaturan pada Simulasi; tampil per baris dan per pesanan di kartu pesanan.

Tab Pencairan dana hanya terlihat oleh pengguna dengan izin pengelolaan marketplace; yang lain melihat "Pencairan dana memerlukan izin pengelolaan marketplace."

10. Log dan kesalahan

Di bagian atas tab Log dan kesalahan ada antrean kesalahan: pesanan yang membawa kode kesalahan, pemetaan yang gagal dikirim, dan koneksi yang berstatus kesalahan ("… kesalahan berturut-turut"). Di bawahnya, per koneksi, Pengambilan pesanan terakhir, Pengiriman stok terakhir, dan apakah sinkronisasi otomatis aktif; paling bawah tabel log (Waktu, Koneksi, Tindakan, Status, Diterima, Baru, Diperbarui, Terkirim, Duplikat, Pesan). Jika antrean kosong tertulis "Antrean kesalahan kosong."

Catat ulang ke HNR hanya muncul pada pesanan tanpa padanan HNR dan juga mencatat pesanan yang sudah dikirim sebelum integrasi; pesanan yang dibatalkan tidak dicatat ke HNR. Kesalahan tingkat koneksi ditampilkan menurut kelasnya: Kredensial ditolak, Layanan atau izin belum aktif di akun ini, Pengaturan koneksi belum lengkap (untuk ketiganya percobaan otomatis berhenti dan administrator sistem harus memperbaiki penyebabnya), Kesalahan jaringan atau waktu habis, Layanan marketplace untuk sementara tidak merespons, Marketplace mengembalikan data yang tidak terduga (untuk ini interval percobaan otomatis berlipat dua setiap kesalahan, paling lama 6 jam).

11. Sinkronisasi otomatis

Sinkronisasi otomatis nonaktif secara bawaan (HNR tidak menghubungi platform dengan sendirinya). Untuk mengaktifkannya, administrator sistem menulis PAZARYERI_GOREV=1 di berkas .env server lalu memulai ulang layanan Node. Selama nonaktif, jendela menampilkan "Sinkronisasi otomatis nonaktif (pengaturan server PAZARYERI_GOREV). Sinkronisasi dilakukan manual." dan semuanya berjalan lewat Sinkronkan sekarang.

• Tugas memeriksa setiap menit; setiap koneksi mengambil pesanan dan retur pada Interval pengambilan pesanan-nya sendiri dan mengirim stok serta harga pada Interval pengiriman stok-nya. Hanya koneksi yang Sinkronisasi otomatis-nya dicentang dan kredensialnya tersimpan yang ikut.
• Perusahaan utama server (HNR_FIRMA) dipindai oleh penjadwal; untuk itu pengguna layanan dengan izin tulis (HNR_B2B_KULLANICI) harus ditetapkan di .env. Perusahaan lain disinkronkan di latar belakang dengan sesi pengguna itu sendiri saat pengguna berizin tulis membuka jendela Marketplace atau Nabız. Perusahaan yang ikut dapat dibatasi dengan PAZARYERI_FIRMALAR (atau HNR_FIRMALAR).
• Saat tugas menerima pesanan baru, administrator yang membuat koneksi menerima pesan "…: … pesanan marketplace baru diterima."; jika koneksi gagal tiga kali berturut-turut, peringatan "Koneksi marketplace … mengalami kesalahan: …" dikirim sekali.

Sinkronkan sekarang (di bagian atas jendela, bersama pemilih koneksi) langsung menjalankan sinkronisasi pesanan, retur, dan stok/harga pada koneksi terpilih, baik tugas aktif maupun tidak, lalu menampilkan "Sinkronisasi selesai: … pesanan baru, stok dan harga … produk dikirim." Koneksi yang sama tidak pernah disinkronkan dua kali bersamaan ("Koneksi ini sedang disinkronkan. Coba lagi sebentar lagi.").

12. Di ponsel (Taman + Langkah)

Di layar lebih kecil dari 7 inci, jendela Marketplace disederhanakan untuk petugas gudang: di atas tab Akan dikemas, Akan dikirim, dan Gagal beserta jumlahnya, kotak "Cari no. pesanan atau pelanggan", dan tombol Ambil pesanan baru; di bawahnya kartu pesanan dengan area sentuh besar (pelanggan, kota/kecamatan, jumlah, batas kirim).

1. Pesanan — baris, pelanggan akhir, dan info pengantaran.
2. Kemas — laporan dikemas dengan sekali sentuh.
3. Kirim — ketik nomor resi atau biarkan kosong (diambil dari pengiriman atau platform) lalu kirim.

Administrator sistem juga dapat membuat koneksi dari ponsel: formulir di Pengaturan terdiri dari tiga langkah di ponsel (Marketplace · Kredensial dan pengaturan · Uji). Lihat panduan Seluler untuk rinciannya.

13. Izin

Di Pengaturan › Pengguna, grup Marketplace memiliki dua izin: Pesanan marketplace: sinkronkan, kemas, kirim, batalkan, kirim stok dan harga (singkatnya pazaryeri) dan Pemetaan produk, pencairan dana, dan identitas lengkap pelanggan akhir (pazaryeri_yonet; mencakup yang pertama). Aturannya diterapkan di server.

Pengguna hanya-baca tidak dapat mengubah catatan marketplace; jika gerbang tulis HNR ditutup, tidak ada operasi tulis yang dijalankan. Koneksi, pemetaan, tampilan identitas, dan setiap tindakan manual dicatat ke jejak audit server (siapa, kapan, apa).

14. Nabız dan Dasbor Pemilik

Di layar utama Nabız pada ponsel, salah satu dari dua baris muncul di daftar Berikutnya: "… pesanan marketplace baru menunggu dikemas." atau "Ada … catatan di antrean kesalahan marketplace."; menyentuh baris membuka jendela Marketplace pada tab terkait. Kotak omzet Dasbor Pemilik menampilkan catatan kaki "Marketplace: omzet … (termasuk PPN) dari … pesanan, komisi dan potongan platform …."; mengkliknya membuka tab Pencairan dana.

15. Belum ada di versi ini

Membuat produk baru di platform (listing, gambar, deskripsi — saat ini hanya stok dan harga produk yang sudah ada yang dikirim), membuat faktur retur penjualan otomatis dari retur, meneruskan identitas pelanggan akhir ke faktur e-Arsip secara otomatis (datanya siap dan titik sambungnya tersedia), memilih daftar harga di layar pemetaan, mengelola kampanye dan kupon platform, serta mengimpor faktur platform secara otomatis direncanakan sebagai pekerjaan terpisah.

Panduan terkait: Pengiriman dan Logistik · Harga dan Kampanye · Koneksi bank langsung · Pengaturan · Seluler · Semua modul.