Payload invoice biasanya memiliki satu header dan banyak item. Menulis header terlebih dahulu lalu melakukan loop item tampak sederhana, tetapi kegagalan pada item terakhir dapat meninggalkan invoice setengah jadi. Desain yang baik dimulai dari kontrak nested, key yang stabil, aturan uang, dan boundary transaksi yang benar-benar didukung database.
Definisikan kontrak nested sebelum mapping
Header umumnya membawa nomor invoice, customer, tanggal, currency, dan total. Array item membawa nomor baris, produk, kuantitas, harga, pajak, serta subtotal. Tetapkan field wajib, nullable, panjang, precision, timezone, dan batas jumlah item. Bedakan field dari pengirim dengan nilai yang dibuat destination seperti primary key atau timestamp generated.
| Bagian | Contoh aturan | Risiko bila kabur |
|---|---|---|
| Invoice ID | Unik per source/tenant | Duplicate atau collision |
| Currency | Kode yang disepakati | Nilai tidak dapat dibandingkan |
| Amount | Decimal presisi dan skala | Pembulatan berbeda |
| Items | Array object, minimal satu | Header tanpa detail |
| Line key | Unik dalam invoice | Item ganda saat retry |
Jangan menerima object bebas lalu berharap mapping memperbaiki data. Validasi child path harus menghasilkan error yang menunjuk lokasi seperti items[2].quantity. Respons ini membantu pengirim memperbaiki record tanpa membagikan struktur database internal.
Pisahkan primary key database dari idempotency key
Database dapat membuat ID internal, tetapi integrasi tetap memerlukan identitas dari source untuk mengenali retry. Kombinasikan source system, tenant atau organisasi, dan invoice number/version sesuai aturan bisnis. Item membutuhkan line ID stabil; posisi array saja berisiko berubah ketika item disisipkan.
- Tentukan apakah nomor invoice dapat dipakai ulang antar-company atau periode.
- Simpan external ID dan correlation ID bersama record atau tabel integrasi.
- Gunakan unique constraint sebagai pertahanan terakhir, bukan satu-satunya desain dedup.
- Putuskan apakah retry mengembalikan hasil sebelumnya, melakukan upsert, atau konflik 409.
- Bedakan revisi invoice dari pengiriman ulang payload yang sama.
Validasi struktur dan aturan bisnis
Validasi schema memeriksa tipe dan keberadaan field. Validasi bisnis memastikan customer ada, produk aktif, currency diizinkan, tanggal berada pada periode yang sesuai, dan total konsisten dengan item menurut aturan pembulatan. Jangan gunakan binary floating point untuk nilai uang ketika presisi desimal diperlukan.
Pisahkan kalkulasi dari authority. Workflow dapat menghitung subtotal atau membandingkan total, tetapi aturan pajak, approval, serta posting akuntansi harus berasal dari pemilik proses dan sistem berwenang. Mismatch dapat ditolak atau diarahkan ke review; jangan diam-diam mengganti angka pengirim tanpa jejak.
Pahami batas transaksi atomic
Jika header dan semua item ditulis pada satu koneksi database yang sama, kirim sebagai satu batch dalam transaksi: begin, insert header, insert items, commit. Bila item gagal karena constraint, rollback menghapus header yang belum committed. Ini mencegah partial invoice pada database tersebut.
Atomisitas ACID tidak meluas otomatis ke database kedua atau API eksternal. Untuk multi-database, NitroNet memakai Saga dengan jurnal dan kompensasi; kompensasi dapat gagal dan perlu recovery. Aksi HTTP/email bersifat at-least-once dan tidak dapat di-rollback bersama database. Desain status seperti pending_external dan rekonsiliasi sering lebih jujur daripada mengklaim semua langkah satu transaksi.
Buat respons error yang membantu pengirim
- 400/422 kontrak.
Berikan path field dan alasan aman tanpa SQL atau secret.
- 409 duplicate.
Tunjukkan bahwa key sudah diproses dan apakah hasil lama dapat diambil.
- 404 referensi.
Gunakan bila customer/product wajib tidak ditemukan sesuai kontrak API.
- 500 sementara.
Bedakan kegagalan internal yang aman di-retry dari error permanen.
- Correlation.
Kembalikan ID penelusuran yang dapat dicocokkan operator dengan log.
Blueprint header–item di NitroNet
Penambahan discount, unit conversion, lot, atau dimensi pajak dapat mengubah grain item dan unique key. Perlakukan sebagai perubahan kontrak, bukan sekadar kolom baru. Uji payload lama, payload baru, campuran versi yang memang didukung, dan data historis yang perlu tetap terbaca. Tentukan apakah destination menerima null/default atau membutuhkan backfill sebelum workflow baru diaktifkan.
Data Masuk NitroNet dapat memodelkan root object dengan array object item. Mapping header disusun sekali; Untuk Setiap membawa field induk yang dipilih ke setiap item. Tulis DB header dan detail pada agent/database yang sama dapat dikumpulkan sebagai batch atomic. Jalur berhasil, duplikat, gagal, Tangkap Error, dan Respons mengembalikan status berdasarkan hasil database nyata.
Uji kasus satu item, banyak item, duplicate line, referensi hilang, precision, serta kegagalan item terakhir di Sandbox dan database uji. Pastikan rollback seluruh batch terverifikasi. Baca pola ERP–sistem pajak dan workflow order-to-fulfillment. NitroNet merangkai mekanismenya; schema dan aturan invoice tetap harus diikat ke sistem nyata.