IOSOR

IOSOR Panduan

Idempotensi API hantar: pendua, cuba semula dan wang

Panduan pembangun untuk API hantar prabayar — kunci idempotensi, cuba semula selamat, cegah pendua dan korelasi mesra lejar supaya kesilapan kejuruteraan tidak jadi insiden kewangan.

Tamat masa berlaku. Penyeimbang beban cuba semula. Klien mudah alih ketik dua kali. Tanpa idempotensi, produk "hantar sekali" jadi debit prabayar berganda dan UX OTP pendua. Panduan ini untuk kejuruteraan dan produk teknikal yang mengintegrasi API pemesejan prabayar white-label — setiap pendua kelihatan dalam dompet. IOSOR mengharapkan integrasi sedar wang: panggilan diautentikasi, debit yang boleh dikorelasi, dan ralat klien yang tidak mencampak muatan jenama asing.

Mengapa pendua menjadi masalah wang

Mod kegagalan Pengguna nampak Dompet nampak
Tamat masa klien + cuba semula buta Dua OTP / dua amaran Dua debit
Pengendali webhook bukan idempoten Kesan sampingan berganda Kekeliruan pada kejayaan
Hantar semula pengguna di atas auto-retry Pengguna jengkel Unit terkumpul
Tiada korelasi Tiket "gagal" Baris lejar tidak sepadan

Demo memaafkan. Kewangan produksi tidak. Pada keamatan prabayar, hujung minggu cuba semula buta jadi projek penyesuaian, bukan nota kaki log.

Kunci idempotensi yang tahan cuba semula

Laluan hantar yang serius menerima kunci dijana klien yang unik bagi niat perniagaan, bukan per cuba TCP. Semasa main semula dalam tetingkap TTL, ia mesti mengembalikan hasil accepted yang sama. Ini menghalang debit kedua bagi niat yang sama. Kunci mesti dilog bersama ID mesej dan rujukan prabayar. Ia mesti berfungsi merentas tamat masa, cuba semula gerbang dan redrive sokongan.

Bajet cuba semula vs hantar semula pengguna

Cuba semula automatik perlukan bajet: maksima percubaan, undur, dan kelas ralat mana yang boleh dicuba semula. Hantar semula pengguna ialah tindakan produk lain dengan had dan kos prabayar sendiri. Mencampurnya mengubah rangkaian yang tidak stabil jadi peristiwa dompet hujung minggu. Ikat kedua-duanya dengan berhenti pada baki rendah dan alasan penolakan yang jelas.

Senarai semak pembeli / kejuruteraan

  1. Dokumentasi semantik kunci idempotensi dan TTL.
  2. Ujian main semula yang membuktikan satu debit bagi satu niat.
  3. Pemisahan bajet cuba semula automatik daripada logik hantar semula pengguna.
  4. Correlation ID merentas request, status dan lejar.
  5. Staging yang melatih koridor sebenar, bukan mock.
  6. Kebersihan kunci dan hak akses minimum untuk kredensial.
  7. Pengendalian 429 dan 503 tanpa kehilangan kunci niat asal.
  8. Amaran automatik bagi kadar penolakan kunci pendua yang tinggi.

Bendera merah

  • "Cuba semula sehingga 200" tanpa kunci idempotensi.
  • Pengendali webhook bukan idempoten yang mencetuskan kesan sampingan dua kali.
  • Kunci rahsia atau token dalam log atau tiket sokongan.
  • Ralat yang memaparkan muatan jenama upstream kepada pengguna.
  • Tiada pemantauan perbezaan antara lejar dan rangkaian.

Mulakan dengan IOSOR

Dalam konsol hantar, lepaskan satu OTP atau amaran dengan kunci keidempotenan yang dijana klien. Paksa tamat masa klien, kemudian main semula permintaan yang sama dalam TTL kunci. Buka ledger prepaid: niat itu mesti tunjuk satu debit dan satu mesej yang pengguna nampak. Dua baris bermakna kunci tidak hidup semula cubaan — baiki TTL dan pengendali sebelum koridor kekal Live.

Inti IOSOR

Buat: anggap setiap hantaran sebagai peristiwa ledger dahulu. Kunci unik bagi niat perniagaan, bukan cubaan TCP. Cubaan semula automatik ada belanjawan; ketukan hantar semula pengguna ialah tindakan produk lain dengan kos prepaid sendiri.

Jangan: tukul hingga 200 tanpa kunci, atau biar webhook tidak keidempotenan mencetak kesan sampingan kedua. Dua OTP untuk satu ketukan ialah pepijat wang, bukan cerita rangkaian.

Adakah panduan ini membantu?

Panduan berkaitan