Pemeriksaan saldo melalui API sebelum peluncuran massal pesanan

Mengapa perlu meminta saldo sebelum meluncurkan antrean

Peluncuran massal pesanan tanpa pemeriksaan saldo terbaru menyebabkan penolakan sebagian: pesanan pertama dibuat, lalu pesanan berikutnya mendapat kesalahan dana tidak cukup. Situasi ini paling sulit ditangani saat pengiriman paralel, layanan berbeda, dan beberapa proses bekerja dengan satu akun.

Untuk peluncuran, yang penting bukan total volume top-up atau saldo akuntansi di dasbor. Yang dibutuhkan adalah jumlah yang diizinkan layanan untuk didebit saat pesanan baru dibuat. Dana untuk pesanan aktif mungkin sudah berada dalam cadangan, meskipun debit final belum tercatat dalam riwayat transaksi.

Bandingkan anggaran antrean dengan kolom saldo tersedia, bukan dengan total dana di akun.

Bagaimana bentuk respons metode saldo

Nama kolom ditentukan oleh dokumentasi platform masing-masing, tetapi kontrak metode saldo yang nyaman biasanya mengembalikan total, available, reserved, currency, dan updated_at. Di bawah ini adalah contoh struktur yang dapat digunakan sebagai acuan saat integrasi. Ini bukan respons universal untuk setiap layanan, melainkan contoh skema data yang jelas.

Permintaan dapat terlihat seperti ini:

curl -X GET "https://api.example.com/v1/balance" \
-H "Authorization: Bearer API_TOKEN" \
-H "Accept: application/json"

Respons:

{
"total": "125.80",
"available": "84.50",
"reserved": "41.30",
"currency": "USD",
"updated_at": "2025-01-15T10:42:18Z"
}

Dalam contoh ini total adalah seluruh dana akun, available adalah dana untuk pesanan baru, reserved adalah jumlah untuk operasi yang dibuat sebelumnya. Pemeriksaan cocok: 125.80 dikurangi 41.30 sama dengan 84.50. Kolom currency menentukan satuan perhitungan, dan updated_at membantu memahami seberapa baru datanya.

Cara membaca available dan reserved

Kolom available digunakan untuk memutuskan peluncuran. Jika antrean bernilai 80.00 dan available adalah 84.50, dana cukup hanya dengan syarat API tidak menambahkan komisi terpisah atau menghitung ulang harga saat pesanan dibuat. Kolom reserved tidak ditambahkan ke saldo tersedia: jumlah itu sudah terpakai.

reserved dapat mencakup biaya pesanan dengan status processing, pending, atau review — kumpulan pastinya bergantung pada aturan platform. Terkadang cadangan dilepaskan setelah pembatalan, penyelesaian sebagian, atau pemeriksaan manual. Karena itu, menghitungnya sendiri berdasarkan daftar pesanan hanya dapat dilakukan sebagai pencocokan tambahan.

• total cocok untuk mencocokkan dengan riwayat top-up dan debit;
• available cocok untuk mengizinkan antrean baru diluncurkan;
• reserved menunjukkan berapa dana yang sudah diblokir untuk operasi aktif;
• currency tidak boleh diabaikan bahkan saat hanya bekerja dengan satu akun;
• updated_at berguna untuk log dan diagnosis respons yang sudah usang.

Respons yang hanya berisi kolom balance lebih mudah diproses, tetapi memiliki kekurangan: tidak dapat diketahui apakah dana tersebut tersedia segera atau sebagian sudah ditahan untuk pesanan lain.

Periksa format jumlah dalam dokumentasi API

Dalam contoh, jumlah dikirim sebagai string: "84.50", bukan angka 84.5. Format ini mempertahankan nilai persis yang dikembalikan layanan. Jika API menggunakan string dengan titik desimal, sebaiknya jangan langsung mengubahnya menjadi angka floating point dan melakukan perbandingan melalui float.

Misalnya, perhitungan Anda dapat menghasilkan 84.499999 alih-alih 84.50 yang diharapkan. Di batas anggaran, ini dapat keliru melewatkan antrean atau sebaliknya menghentikannya. Untuk operasi dengan nilai desimal string, gunakan tipe data desimal yang mendukung presisi pecahan tetap.

Kontrak lain yang umum adalah satuan minimum bilangan bulat. Maka respons dapat berisi "available_minor": 8450 dan "currency": "USD", sedangkan harga pesanan — "price_minor": 1250. Di dalam API seperti itu, 8450 berarti 84.50 jika aturan mata uang mengasumsikan dua posisi pecahan. Membagi nilai dengan 100 hanya boleh dilakukan jika dinyatakan secara eksplisit dalam dokumentasi.

Jangan mencampur mata uang dan format harga

Sebelum menghitung antrean, bandingkan currency dari saldo dengan mata uang metode harga atau respons saat membuat pesanan. Jika saldo mengembalikan satu mata uang dan katalog layanan mengembalikan mata uang lain, angka tidak boleh dimasukkan secara langsung. Diperlukan要么 perhitungan yang disediakan platform itu sendiri, atau metode konversi terpisah yang telah dikonfirmasi.

Konversi awal di sisi Anda nyaman untuk perencanaan, tetapi memiliki kekurangan: layanan dapat menerapkan kurs, komisi, atau aturan pembulatan yang berbeda saat debit. Lebih andal mengirim pesanan dengan parameter yang API kembalikan biaya akhirnya dalam mata uang saldo, atau mendapatkan perhitungan harga tepat sebelum pembuatan.

Jika metode harga merespons "price": "12.345", sedangkan saldo menyimpan nilai dengan dua digit, perjelas aturan pembulatan. Jangan membulatkan ke bawah secara otomatis: debit aktual bisa lebih tinggi. Untuk mengizinkan antrean, gunakan jumlah yang API sebut sebagai biaya akhir pesanan.

Hitung anggaran antrean sebelum permintaan pertama

Sebelum peluncuran, kumpulkan semua pesanan dan hitung biayanya dengan mempertimbangkan volume, layanan yang dipilih, wilayah, opsi tambahan, dan komisi jika dikirim terpisah. Jangan membandingkan available dengan harga dasar dari antarmuka: dalam API, total dapat bergantung pada parameter pesanan tertentu.

Misalkan ada tiga pesanan dalam antrean. API perhitungan harga mengembalikan 18.40, 27.15, dan 31.60 dalam mata uang yang sama dengan balance.currency. Anggarannya adalah 77.15. Jika balance.available adalah 84.50, setelah peluncuran terjadwal tersisa 7.35. Jika available adalah 76.90, seluruh antrean tidak boleh diluncurkan.

1. Dapatkan harga berdasarkan parameter aktual setiap pesanan.
2. Jumlahkan biaya akhir tanpa mengubah format dan mata uangnya.
3. Bandingkan anggaran dengan available dari respons saldo terbaru.
4. Jika saldo cukup, catat jumlahnya sebagai cadangan peluncuran lokal.
5. Setelah setiap pesanan dibuat, kurangi cadangan lokal dengan biaya yang dikonfirmasi.

Margin mengurangi risiko penolakan akibat debit tambahan, tetapi memiliki kekurangan: sebagian dana tersedia akan tetap tidak terpakai, padahal antrean bisa saja lolos sepenuhnya.

Lakukan pemeriksaan kedua tepat sebelum pengiriman

Saldo yang diperoleh saat persiapan kampanye cepat menjadi usang. Selama waktu antara perhitungan dan peluncuran, operator lain, otomatisasi, atau pesanan aktif dapat mengubah available dan reserved. Permintaan ulang diperlukan setelah antrean terbentuk dan tepat sebelum pesanan pertama.

Skema kerja terdiri dari dua tahap: pertama dapatkan harga dan perkirakan anggaran, lalu minta balance sekali lagi. Jika nilai available menurun dan menjadi di bawah jumlah perhitungan, antrean tidak dikirim seluruhnya. Antara pemeriksaan akhir dan peluncuran, jangan melakukan debit lain dari akun yang sama.

Satu permintaan untuk seluruh peluncuran mengurangi beban pada API, tetapi kekurangannya adalah saldo tersedia dapat berubah saat antrean panjang masih diproses.

Cara meluncurkan antrean saat dana tidak cukup

Jika available kurang dari anggaran, jangan kirim semua permintaan dengan harapan sebagian akan lolos. Bagi antrean menjadi paket yang biayanya sesuai dengan batas tersedia. Dalam contoh dengan saldo 76.90, dua pesanan pertama senilai 45.55 dapat dikirim, lalu berhenti: pesanan ketiga senilai 31.60 memerlukan pemeriksaan ulang.

Tentukan urutan pesanan saat batching secara eksplisit. Anda dapat mengirim pesanan prioritas terlebih dahulu, atau membentuk paket dengan biaya yang berdekatan. Setiap opsi memiliki kekurangan: urutan prioritas akan menunda item yang kurang penting, sedangkan pengurutan berdasarkan harga dapat mengganggu rencana kampanye awal.

• Bentuk paket dengan jumlah tidak melebihi available saat ini.
• Buat pesanan dari paket dan simpan ID-nya.
• Tunggu respons atau periksa status operasi setelah timeout.
• Lakukan jeda jika batas API atau aturan layanan mengharuskannya.
• Minta balance lagi sebelum paket berikutnya.

Setelah setiap paket, berpedoman pada respons API baru, bukan hanya pada pengurangan lokal dari saldo sebelumnya. Perhitungan lokal berguna untuk kontrol, tetapi tidak melihat pengembalian dana, debit eksternal, dan perhitungan ulang cadangan.

Lindungi anggaran saat pengiriman paralel

Pada pemrosesan berurutan, cukup mengurangi batas lokal setelah pesanan dikonfirmasi. Pada model paralel, dua worker dapat secara bersamaan melihat available 84.50 dan masing-masing merencanakan pengeluaran 60.00. Kedua keputusan tampak valid secara terpisah, tetapi bersama-sama melebihi saldo tersedia.

Untuk perlindungan, diperlukan penghitung cadangan lokal bersama atau antrean yang aksesnya dilakukan secara atomik. Sebelum mengirim, worker mencoba mengambil jumlah pesanan dari penghitung ini. Jika batas bebas tidak cukup, pesanan tetap menunggu pemeriksaan saldo ulang.

• Antrean berurutan lebih mudah dikendalikan, tetapi peluncurannya lebih lambat.
• Pengiriman paralel mempersingkat waktu peluncuran, tetapi memerlukan penguncian anggaran bersama.
• Reservasi lokal mengurangi konflik, tetapi dapat macet setelah kegagalan worker.
• Reservasi di sisi API lebih andal, tetapi tidak tersedia di setiap platform.

Jika proses berakhir sebelum menerima respons, cadangan lokal tidak dapat langsung dianggap terpakai atau bebas. Pertama periksa apakah pesanan sudah dibuat, melalui ID eksternalnya atau metode pencarian operasi.

Gunakan cadangan API jika tersedia

Beberapa API memungkinkan pembuatan cadangan untuk sekumpulan operasi atau melakukan pesanan dalam dua langkah: perhitungan, pemblokiran jumlah, konfirmasi. Dalam skema seperti itu, jendela antara pemeriksaan dan debit lebih kecil, di mana proses lain dapat menghabiskan dana akun.

Jika metode tersebut tersedia, simpan ID cadangan, jumlahnya, mata uang, masa berlaku, dan statusnya. Kemudian kirimkan ID ini saat membuat pesanan jika kontrak API mengharuskannya. Setelah antrean selesai, cocokkan bagian yang tidak terpakai dan fakta pelepasan blokir.

Cadangan API tidak menyelesaikan semua masalah: masa berlakunya bisa singkat, tidak mencakup komisi, atau dilepaskan setelah kesalahan konfirmasi. Cadangan lokal lebih mudah diterapkan, tetapi kekurangannya adalah tidak melindungi dari pengeluaran yang dibuat di luar aplikasi Anda.

Pisahkan kesalahan saldo dari saldo nol

Respons dengan kode kesalahan, timeout, atau pembatasan laju permintaan tidak berarti available sama dengan nol. Jangan memasukkan nilai terakhir yang diketahui secara otomatis jika peluncuran besar bergantung padanya. Jika saldo terbaru tidak dapat diperoleh, antrean harus dijeda.

Tangani penolakan saat membuat pesanan secara terpisah. Penolakan dapat disebabkan oleh dana tidak cukup, tetapi juga oleh ID layanan yang salah, volume yang tidak diizinkan, batasan pada kanal, atau pengulangan satu operasi. Simpan kode dan teks kesalahan bersama ID eksternal pesanan.

• Pada kesalahan otorisasi, perbarui akses dan baru kemudian ulangi permintaan.
• Pada batas permintaan, tunggu sesuai aturan API.
• Pada timeout pembuatan, periksa dulu apakah operasi benar-benar muncul.
• Pada kesalahan dana tidak cukup, hentikan paket dan minta balance lagi.

Jangan membuat duplikat setelah timeout

Timeout berarti klien Anda tidak menerima respons, bukan bahwa server tidak memproses permintaan. Pengiriman ulang tanpa pemeriksaan dapat membuat pesanan kedua dan kembali mengambil dana. Ini sangat berbahaya dalam antrean di mana pengulangan otomatis diatur untuk beberapa percobaan.

Kirimkan ID eksternal pesanan yang unik jika API mendukung kolom client_order_id, external_id, atau idempotency_key. Simpan sebelum mengirim permintaan. Setelah timeout, temukan operasi berdasarkan nilai ini atau minta status berdasarkan ID yang diperoleh sebelumnya.

Pengulangan tanpa pemeriksaan lebih cepat, tetapi kekurangannya langsung: duplikat pesanan, reservasi ganda, dan ketidaksesuaian antara perhitungan anggaran Anda dan debit aktual mungkin terjadi.

Apa yang harus disimpan dalam log peluncuran

Log membantu memulihkan jalannya operasi massal dan menjelaskan mengapa paket tertentu berhenti. Untuk setiap peluncuran, simpan waktu dua pemeriksaan, total, available, reserved, currency, anggaran yang dihitung, ukuran cadangan lokal, dan daftar ID eksternal pesanan.

Untuk setiap percobaan pembuatan, catat biaya, kode respons, ID teknis operasi, dan status akhir. Rahasia tidak masuk ke log: token otorisasi, kunci API, header permintaan lengkap, dan data pribadi harus dimasking atau dikecualikan sebelum pencatatan.

Logging lengkap nyaman saat debugging, tetapi memiliki kekurangan: tanpa penyaringan, data akses dan informasi pelanggan dapat masuk ke penyimpanan.

Uji skema pada antrean kecil

Sebelum peluncuran besar, jalankan skenario singkat: dapatkan balance, minta harga akhir, buat paket terbatas, minta balance lagi, dan bandingkan perubahan available dan reserved yang diharapkan dengan respons aktual. Dengan begitu dapat diketahui kapan layanan mencadangkan jumlah dan kapan mendebitnya secara final.

Paket uji tidak menjamin perilaku yang sama di bawah beban besar: batas, proses paralel, atau batasan layanan tertentu dapat berlaku. Karena itu, dalam antrean massal, terus bagi peluncuran menjadi paket, periksa saldo tersedia di antaranya, dan tangani setiap penolakan secara terpisah.