Impor & Ekspor Produk (CSV)
1. Ringkasan
Mengelola katalog produk dengan ratusan item membutuhkan waktu yang tidak sedikit jika dilakukan satu per satu. Fitur Impor & Ekspor CSV memungkinkan Anda untuk menambahkan, memperbarui, atau mencadangkan seluruh data katalog secara massal dalam hitungan detik. Fungsionalitas ini sangat berguna saat Anda baru berpindah dari platform lain, melakukan pembaruan harga serentak, atau menyinkronkan stok dengan sistem Point of Sales (POS) internal.

Gambar 1.1: Tabel katalog produk utama tempat fitur impor dan ekspor berada.
2. Konsep Dasar
Format Comma-Separated Values (CSV) dan Excel Spreadsheet (XLSX) adalah standar industri untuk pertukaran data tabular. Sistem DagangBot menggunakan arsitektur pemetaan header adaptif untuk menerima berkas CSV berbatas koma murni (.csv) maupun berkas Excel biner (.xlsx).
2.1 Struktur Kolom & Alias (Smart Header Mapping)
Mesin parser DagangBot dilengkapi dengan pengenalan alias. Anda tidak harus selalu menggunakan header berbahasa Inggris; sistem secara mandiri menerjemahkan beberapa istilah umum ke dalam format standar internal toko.
name(Wajib): Kolom utama penamaan produk. Alias yang diterima:nama,nama produk,product name,title,judul.price(Wajib): Harga dasar jual satu satuan, dikirim dalam bentuk angka tanpa pemisah desimal/ribuan. Sistem akan membersihkan awalan "Rp", koma, dan titik. Alias:harga,harga jual,selling price,unit price.stock(Wajib): Kuantitas persediaan fisik. Angka negatif akan ditolak oleh sistem. Alias:stok,qty,quantity,jumlah,persediaan.sku(Opsional): Stock Keeping Unit, pengenal unik inventaris untuk mencocokkan barang atau menghindari duplikasi. Alias:kode,kode produk,product code,item code.description(Opsional): Teks penjabaran spesifikasi barang. Alias:deskripsi,detail,keterangan,catatan.image_url(Opsional): Tautan absolut yang menunjuk ke lokasi gambar publik (contoh: hosting S3 atau penyedia pihak ketiga). Alias:image url,gambar,foto,url gambar,product image.
2.2 Mekanisme Pencocokan Duplikat (Upsert Mode)
Saat baris data disuntikkan, sistem menjalankan logika Upsert ( Update or Insert ). Logika pembedanya berurutan:
Pencarian via SKU: Sistem mengecek apakah SKU dalam fail sama persis dengan SKU yang ada di dalam pangkalan data. Jika ya, data produk lama akan ditimpa (update).
Pencarian via Nama: Jika SKU kosong, sistem mengecek apakah ada produk dengan nama teks (case-insensitive) yang persis. Jika ada, data ditimpa.
Penyisipan Baru: Jika kedua pemeriksaan di atas gagal, sistem menciptakan objek katalog baru (insert).
Metode pembaruan upsert ini beroperasi secara sebagian ( partial update ). Jika baris CSV Anda hanya memuat kolom name dan price tanpa deskripsi baru, deskripsi lama yang sudah tersimpan di sistem tidak akan dihapus.
3. Prasyarat & Konfigurasi
Sebelum melakukan unggah data, pastikan Anda memenuhi kriteria berikut:
3.1 Penjelasan Batasan (Rate Limiting & Kuota)
Mengingat pemrosesan fail biner atau parsing CSV dapat mengonsumsi sumber daya komputasi (CPU & memori) secara intensif, sistem memberlakukan batasan eksekusi untuk menjaga stabilitas peladen utama:
Batas Ukuran Fail (Payload Limit): Maksimal 10 Megabita (MB) untuk berkas CSV murni, dan 64 MB untuk hasil dekompresi biner XLSX. Fail di atas ukuran ini secara otomatis ditolak pada lapisan proksi peladen (gateway HTTP 413 Payload Too Large).
Batas Baris Data: Direkomendasikan maksimal mengunggah 2.000 baris produk dalam satu kali proses (batch). Angka ini memastikan proses penulisan database (transaction commit) tidak mengalami timeout. Jika katalog Anda memiliki lebih dari 2.000 barang, harap pecah (split) fail unggahan Anda menjadi beberapa batch.
Batasan Permintaan (Rate Limit): Sebuah toko dibatasi maksimal melakukan pemanggilan ke endpoint API
/api/products/importsebanyak 10 kali per jam.
3.2 Pembersihan Data (Data Sanitization)
Sistem secara otomatis akan melakukan pembersihan ( sanitization ) terhadap karakter pengganggu untuk menghindarkan database dari data "kotor" dan celah keamanan:
Menghapus Whitespace: Spasi kosong di awal dan di akhir string (
trim).Menyaring Simbol Mata Uang: Karakter non-digit dalam kolom
pricedanstockselain koma atau titik akan disingkirkan.Validasi Angka Nol atau Negatif: Harga yang diatur di bawah Rp0 (negatif) dihentikan.
4. Panduan Penggunaan
4.1 Mengunduh Template Standar
Jika Anda baru pertama kali melakukan impor, kami sarankan menggunakan template resmi untuk menghindari masalah pemetaan kolom.
Akses menu Katalog → Produk pada sidebar utama dasbor.
Klik dropdown aksi di samping tombol tambah produk, lalu pilih Impor CSV / Excel.
Klik tombol Unduh Template (
/api/products/import/template).Buka template tersebut melalui Google Sheets atau Microsoft Excel.
4.2 Mengunggah Data Produk Baru
Siapkan data Anda sesuai format kolom atau alias yang dipersyaratkan. Pastikan tidak ada kolom tersembunyi.
Simpan fail tersebut, baik dalam format .xlsx reguler, atau jika memilih .csv, pastikan formatnya UTF-8 (Comma delimited).
Kembali ke layar Impor CSV, unggah berkas Anda.
Sistem akan merender pratinjau yang berisi laporan pemetaan alias, misalnya "Kolom Harga Jual dipetakan ke price". Kolom asing yang tidak dikenali akan diklasifikasikan sebagai Peringatan (Warning) dan diabaikan dari alur impor.
Klik Konfirmasi Impor untuk mulai mengirim ke peladen.
Sistem akan memunculkan dialog ringkasan hasil yang merangkum nilai
imported(sukses),skipped(gagal terimpor), beserta matriks kesalahan (errors) jika baris tertentu bermasalah.
4.3 Mengekspor Katalog
Fungsi ekspor berguna untuk audit atau backup.
Pada halaman daftar Produk, pilih opsi Ekspor CSV.
Sistem akan menyusun file CSV secara seketika (real-time) memuat seluruh produk dari semua halaman.
File akan otomatis terunduh ke perangkat Anda.
5. Skenario Lanjutan
5.1 Pembaruan Harga Massal (Bulk Price Update)
Alih-alih mengedit harga satu demi satu saat ada penyesuaian promo besar:
Lakukan Ekspor CSV dari katalog saat ini.
Buka berkas tersebut di aplikasi spreadsheet.
Sesuaikan angka pada kolom
price. Biarkan kolom SKU dan Nama tetap utuh.Simpan dan unggah. Sistem akan memanfaatkan logika pencocokan upsert untuk memperbarui harga tanpa menggandakan katalog.
5.2 Keamanan Parser Berkas Excel (XLSX)
Fail XLSX pada dasarnya adalah kompresi ZIP biner XML. Untuk mencegah risiko sistemik kelebihan memori ( OOM - Out of Memory atau eksploitasi serangan Zip-bomb ), sistem DagangBot menerapkan batas aman pada mesin baca XLSX (komponen M-09 arsitektur backend):
Batas dekompresi file maksimum dipatok ketat pada 64 Megabita (MB).
Tidak boleh terdapat lebih dari 512 entri sub-fail di dalam bungkusan berkas XLSX. Jika limit keamanan di atas terlanggar, peladen akan menolak berkas sebelum pemrosesan data dilakukan.
5.3 Sinkronisasi Impor Parsial (Fail-Safe Batching)
Mekanisme impor massal memproses baris demi baris dan mengisolasi kegagalan per item. Artinya, dalam tabel 1.000 baris, jika baris ke-450 gagal validasi karena salah ketik price "150.OOO" (memakai huruf O), 999 baris produk lainnya tetap akan diproses atau diperbarui dengan aman. Baris yang gagal dilaporkan pada larik (array) keluaran Errors untuk Anda perbaiki kelak.
6. Referensi Teknis
Proses ini sepenuhnya berinteraksi dengan antarmuka program aplikasi (endpoint API) yang dilindungi otorisasi lapisan penyewa (merchant):
GET /api/products/import/template: Menghasilkan file CSV kosong dengan baris tajuk standar Inggris.POST /api/products/import/preview: Rutinitas parser internal (parseProductImport) untuk membaca tata letak multipart form data tanpa melakukan interaksi tulis ke pangkalan data. Merangkum nilai pratinjau matriks pemetaan.POST /api/products/import: Mengeksekusi penulisan dengan pemanggilanItemService.ImportParsedProducts. Mengembalikan struktur objekCSVImportResultberisikan propertiimported(angka masuk),skipped(angka terlewati), serta daftarerrors(larik string kegagalan per baris).
6.1 Struktur Respons Pratinjau (Preview Payload)
Sebagai referensi bagi pengembang sistem terpadu, pemanggilan ke antarmuka /api/products/import/preview akan menghasilkan objek JSON berformat ProductImportParseResult:
Nama Properti | Tipe Data | Deskripsi |
|---|---|---|
|
| Daftar seluruh baris yang berhasil diurai dari sumber data. |
|
| Hasil pemetaan (mapping) dinamis antara nama header wajib dengan nama kolom aktual di dalam fail pengunggah. |
|
| Larik pesan peringatan, misalnya informasi tentang kolom tidak dikenal (unknown header) yang diabaikan. |
|
| Larik pesan kesalahan pemblokir (blocking error) jika terdapat ketidaksesuaian kritis (misalnya header 'name' sama sekali tidak ada). |
6.2 Antarmuka Metrik Hasil Impor (Execution Payload)
Ketika proses tulis /api/products/import terselesaikan, backend akan menyebarkan antarmuka struktur balasan sebagai berikut:
Nama Properti | Tipe Data | Deskripsi |
|---|---|---|
|
| Total penghitungan (counter) baris baru yang sukses dibuat (inserted) maupun yang sukses diperbarui (updated). |
|
| Total baris yang dilewati (bypassed) akibat gagal validasi. |
|
| Log terperinci per baris yang mengalami galat, menggunakan rujukan baris asli (misal: "Baris 24: harga tidak valid"). |
7. Pemecahan Masalah
Berikut daftar kendala yang mungkin terjadi saat mengeksekusi impor beserta panduan penyelesaiannya.
Masalah | Penyebab | Solusi |
|---|---|---|
Pesan Error "CSV missing required column 'name'" | Berkas yang diunggah tidak memiliki header name, nama, atau alias lain yang diizinkan untuk kolom utama. | Sesuaikan nama kolom baris pertama agar sama persis dengan aturan tabel prasyarat, atau unduh ulang templat standar platform. |
Gagal membaca CSV (file is empty / malformed row) | Berkas sama sekali tidak memiliki struktur data, encoding tidak menggunakan standar UTF-8, atau delimiter di luar format koma. | Buka file menggunakan Google Sheets, lalu pilih menu File → Download → Comma-separated values (.csv). |
Pesan Kesalahan "Baris X: harga tidak valid" | Terdapat karakter tipografi non-numerik tak dikenal yang membingungkan fungsi baca float pengurai pada kolom angka. | Hindari menggunakan karakter khusus asing. Pastikan sistem pembersih angka mampu membacanya (sistem bisa membuang "Rp", ",", dan ".", namun bukan abjad atau simbol mata uang lain). |
Pesan "xlsx terlalu besar setelah dekompresi" atau "xlsx memiliki terlalu banyak entri" | Berkas .xlsx Anda terinfeksi malware zip-bomb atau ukuran selubung memori melebihi 64 MB (batas mesin baca backend). | Salin ( Copy ) blok teks khusus baris dan kolom yang Anda butuhkan (jangan copy seluruh worksheet), lalu tempel ( Paste ) sebagai Values Only ke fail kosong baru. |
Akses ditolak (HTTP 403 / RBAC Error) | Akun pengguna saat ini kehilangan hak | Hubungi administrator toko/penyewa (merchant owner) untuk memperbarui peran pembatasan RBAC pada identitas masuk Anda. |
