Otomatisasi Dokumen Pengiriman Internasional dengan Kode

Dokumen pengiriman internasional seperti commercial invoice dan packing list bisa dibuat otomatis dari data pesanan, asalkan datanya sudah rapi sejak di katalog produk. Bagian yang paling menentukan bukan template PDF-nya, tetapi tiga hal di belakangnya: deskripsi barang yang jelas, kode HS yang ditetapkan dengan benar, dan angka nilai serta berat yang konsisten. Kode yang baik menolak membuat dokumen bila salah satunya belum terpenuhi.

Ketentuan dokumen berbeda menurut kurir dan negara tujuan, dan bisa berubah. Artikel ini hanya membahas prinsip teknis membangun otomatisasinya. Untuk isi wajib, bahasa, jumlah salinan, dan batasan barang, selalu cek ketentuan kurir yang Anda pakai dan aturan negara tujuan.

Dokumen apa saja yang biasanya dibutuhkan

Dokumen Fungsi umum Data utama
Commercial invoice Menyatakan isi dan nilai barang untuk pemeriksaan kepabeanan Pengirim, penerima, deskripsi, jumlah, nilai, mata uang, negara asal barang, kode HS
Packing list Merinci isi setiap koli atau kotak Nomor koli, isi per koli, berat, dimensi
Label pengiriman Identitas paket untuk kurir Nomor resi, alamat, kode rute

Label biasanya dibuat oleh API kurir. Commercial invoice dan packing list sering perlu Anda siapkan sendiri, atau dikirim sebagai data terstruktur ke API kurir yang kemudian membuat dokumennya.

Mulai dari model data

Jangan langsung mengisi template dari tabel pesanan. Buat model data khusus dokumen yang menjadi “foto” kondisi saat dokumen diterbitkan. Produk bisa berganti nama dan harga, tetapi dokumen yang sudah dikirim harus tetap bisa direproduksi persis.

{
  "invoiceNumber": "CI-2026-000123",
  "issuedAt": "2026-10-26",
  "currency": "USD",
  "exporter": { "name": "...", "address": "...", "country": "ID" },
  "consignee": { "name": "...", "address": "...", "country": "SG", "phone": "+65..." },
  "lines": [
    {
      "description": "Men's short sleeve T-shirt, 100% cotton, printed",
      "hsCode": "610910",
      "originCountry": "ID",
      "quantity": 3,
      "unitValue": "12.00",
      "netWeightGrams": 180
    }
  ],
  "packages": [ { "no": 1, "grossWeightGrams": 750, "dimensionsCm": [30, 25, 5] } ]
}

Nilai uang disimpan sebagai string desimal atau BigDecimal, bukan double, agar tidak ada selisih pembulatan di total. Kode negara memakai ISO 3166-1 dua huruf.

Deskripsi barang yang jelas

Petugas yang membaca dokumen harus bisa membayangkan barangnya tanpa membuka paket. Deskripsi yang samar adalah salah satu penyebab umum paket tertahan untuk pemeriksaan tambahan. Pola yang bisa dipakai: apa barangnya, terbuat dari apa, untuk apa.

Terlalu umum Lebih jelas
Hadiah Kaus katun lengan pendek pria, bersablon
Aksesoris Gantungan kunci logam berlapis enamel
Makanan Keripik singkong dalam kemasan plastik, 200 g
Spare part Rantai sepeda baja, 116 mata rantai

Simpan deskripsi untuk dokumen sebagai field terpisah di master produk, karena judul produk di toko ditulis untuk pemasaran, bukan untuk petugas. Banyak kurir meminta deskripsi dalam bahasa Inggris; ikuti ketentuan kurir Anda.

Kode HS: tetapkan di master produk, jangan ditebak

Kode HS (Harmonized System) adalah sistem klasifikasi barang yang dikelola World Customs Organization. Enam digit pertama dipakai bersama secara internasional, lalu tiap negara bisa menambahkan digit untuk keperluan tarif dan statistik nasionalnya. Sistem ini juga direvisi secara berkala, sehingga kode yang dulu benar bisa perlu ditinjau ulang.

Prinsip teknisnya sederhana:

  • Kode HS disimpan per produk atau per varian di master data, bersama tanggal tinjau dan siapa yang menetapkan.
  • Penetapan dilakukan orang yang paham, atau dikonfirmasi ke kurir, broker kepabeanan, atau sumber resmi. Saran otomatis dari nama produk boleh dipakai sebagai usulan, tetapi selalu lewat review manusia.
  • Produk tanpa kode HS yang sudah ditinjau tidak boleh masuk dokumen internasional. Lebih baik pesanan tertahan di sistem Anda daripada di negara tujuan.

Validasi sebelum dokumen terbit

Pemeriksaan otomatis menangkap kesalahan yang paling sering: total tidak cocok, field kosong, dan deskripsi terlalu umum.

public record InvoiceLine(String description, String hsCode, String originCountry,
                          int quantity, BigDecimal unitValue, long netWeightGrams) {}

public record CommercialInvoice(String invoiceNumber, String currency,
                                List<InvoiceLine> lines, long grossWeightGrams) {}

public final class InvoiceValidator {
    private static final Set<String> VAGUE = Set.of(
            "gift", "hadiah", "sample", "sampel", "barang", "parts", "accessories");

    public static List<String> validate(CommercialInvoice invoice) {
        List<String> errors = new ArrayList<>();
        if (invoice.lines().isEmpty()) {
            errors.add("Invoice tidak memiliki baris barang");
        }
        long netTotal = 0;
        for (InvoiceLine line : invoice.lines()) {
            String desc = line.description() == null ? "" : line.description().strip();
            if (desc.length() < 10 || VAGUE.contains(desc.toLowerCase(Locale.ROOT))) {
                errors.add("Deskripsi terlalu umum: " + desc);
            }
            if (line.hsCode() == null || !line.hsCode().matches("\d{6,10}")) {
                errors.add("Kode HS kosong atau formatnya salah: " + desc);
            }
            if (line.originCountry() == null || line.originCountry().length() != 2) {
                errors.add("Negara asal belum diisi: " + desc);
            }
            if (line.quantity() <= 0 || line.unitValue().signum() <= 0) {
                errors.add("Jumlah atau nilai tidak valid: " + desc);
            }
            netTotal += line.netWeightGrams() * line.quantity();
        }
        if (netTotal > invoice.grossWeightGrams()) {
            errors.add("Berat bersih melebihi berat kotor paket");
        }
        return errors;
    }

    public static BigDecimal total(CommercialInvoice invoice) {
        return invoice.lines().stream()
                .map(l -> l.unitValue().multiply(BigDecimal.valueOf(l.quantity())))
                .reduce(BigDecimal.ZERO, BigDecimal::add);
    }
}

Total di dokumen selalu dihitung dari baris, tidak diketik terpisah. Dengan begitu tidak mungkin ada invoice yang jumlah barisnya berbeda dengan totalnya. Data alamat dan telepon penerima juga harus lolos pemeriksaan seperti di artikel validasi alamat penerima sebelum kirim.

Menghasilkan dokumen

Ada dua jalur umum. Bila API kurir menerima data dokumen secara elektronik, kirim model data di atas dalam format yang diminta dan biarkan kurir membuat dokumennya. Bila Anda harus mencetak sendiri, buat template HTML lalu ubah ke PDF dengan library seperti OpenPDF atau Apache PDFBox, atau pustaka konversi HTML ke PDF yang Anda percaya. Beberapa kebiasaan yang membantu:

  • Nomor dokumen dibuat berurutan dan unik, tidak pernah dipakai ulang.
  • Simpan PDF beserta salinan data JSON yang dipakai untuk membuatnya.
  • Koreksi menghasilkan versi baru dengan catatan alasan, bukan menimpa file lama.
  • Uji template dengan nama panjang, alamat panjang, dan banyak baris barang agar tidak ada teks yang terpotong.

Menyambungkan ke alur pesanan

Pembuatan dokumen cocok dijalankan sebagai consumer di antrean pesan. Saat event pesanan internasional siap dikirim muncul, consumer menyusun model data, menjalankan validasi, membuat dokumen, menyimpannya, lalu melampirkannya ke order pengiriman. Pesanan yang gagal validasi masuk ke antrean review manual bersama daftar errornya, sehingga tim gudang tahu persis apa yang perlu dilengkapi. Pola event untuk alur ini dibahas di artikel arsitektur event-driven untuk toko online.

FAQ

Bolehkah nilai barang di invoice diatur agar lebih rendah?

Tidak. Isi nilai transaksi yang sebenarnya. Kode Anda cukup mengambil nilai dari data pesanan; jangan sediakan fitur untuk mengubahnya secara bebas.

Perlukah tanda tangan basah?

Tergantung kurir dan negara tujuan. Sebagian menerima dokumen elektronik, sebagian meminta cetakan bertanda tangan. Jadikan ini konfigurasi per rute.

Bagaimana dengan barang yang dibatasi atau dilarang?

Simpan daftar pembatasan sebagai data yang dikelola tim operasional berdasarkan ketentuan kurir dan negara tujuan, lalu blokir checkout untuk kombinasi produk dan negara yang tidak diizinkan. Jangan menulis aturan itu langsung di kode, karena aturannya bisa berubah.

Hendra Kurniawan

Oleh Hendra Kurniawan

Pengembang backend Java yang lama menangani integrasi sistem dan message broker. Menulis catatan praktis tentang JMS, API, dan arsitektur aplikasi.