Penanganan status "sedang diproses" saat memeriksa pesanan melalui API

Apa arti processing dalam respons API

Status processing, in_progress, atau keadaan setara lainnya berarti penyedia telah menerima pesanan untuk diproses, tetapi belum menetapkan hasil akhirnya. Untuk layanan promosi, ini bisa berupa pemeriksaan tautan, menunggu antrean, memulai tugas, atau pemberian volume pesanan secara bertahap.

Processing tidak mengonfirmasi keberhasilan penyelesaian dan bukan berarti kesalahan. Setelahnya, pesanan dapat berubah menjadi completed, partial, canceled, atau failed. Selama penyedia masih mengembalikan status antara, jangan buat permintaan ulang untuk tautan dan volume yang sama.

HTTP 200 dengan status processing berarti respons API berhasil, bukan pesanan selesai dengan sukses. Kedua peristiwa ini harus disimpan dan ditangani secara terpisah.

Data apa yang diperlukan untuk memeriksa pesanan

Untuk polling, diperlukan ID pesanan eksternal yang dikembalikan penyedia saat pembuatan. Simpan ID tersebut bersama ID internal, volume awal, parameter layanan, tautan, waktu pembuatan, dan respons API awal. Mencari pesanan berdasarkan nama kanal, tautan, atau volume tidak dapat diandalkan: nilai tersebut bisa sama pada beberapa permintaan.

Jika setelah pembuatan muncul timeout, jangan kirim ulang permintaan secara otomatis. Penyedia mungkin telah menerima permintaan, tetapi responsnya hilang di tengah jalan. Gunakan dulu metode pencarian pesanan jika tersedia dalam dokumentasi, atau serahkan kasusnya untuk diperiksa.

Kekurangan hanya menyimpan status saat ini adalah saat terjadi sengketa, tidak mungkin memulihkan kapan pesanan beralih ke processing, apakah ada kemajuan, dan respons apa yang diterima sebelumnya.

Contoh permintaan status melalui curl

Alamat persis, metode otorisasi, dan nama field harus diambil dari dokumentasi penyedia. Di bawah ini ditunjukkan templat: nilai dalam tanda kurung siku harus diganti dengan data API tertentu.

Permintaan GET untuk satu pesanan

curl -X GET "https:///orders//status" \

-H "Authorization: Bearer " \

-H "Accept: application/json"

Contoh respons:

{

"order_id": "",

"status": "processing",

"completed_quantity": 250,

"remains": 750,

"updated_at": "nilai_waktu"

}

Field completed_quantity dan remains hanya ditampilkan sebagai contoh struktur. Penyedia mungkin menggunakan progress, start_count, balance, atau nama lain. Kekurangan pendekatan GET adalah sebagian API hanya menerima pemeriksaan status melalui POST.

Contoh permintaan POST dan pemeriksaan batch

Permintaan POST status satu pesanan

curl -X POST "https:///orders/status" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_id":""}'

Jangan kirim kunci API di string URL. Alamat permintaan masuk ke log proxy, sistem analitik, riwayat browser, dan log teknis. Kekurangan POST adalah lebih sulit diperiksa secara manual melalui address bar, tetapi itu bukan alasan untuk memindahkan rahasia ke URL.

Permintaan batch pesanan aktif

Jika API mendukung pemeriksaan batch, kirim beberapa ID dalam satu permintaan:

curl -X POST "https:///orders/statuses" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_ids":["",""]}'

Cocokkan respons dengan pesanan internal berdasarkan ID eksternal, bukan berdasarkan posisi elemen dalam array. Kekurangan pemeriksaan batch: penyedia mungkin tidak mengembalikan semua pesanan, membatasi ukuran daftar, atau melaporkan kesalahan hanya untuk satu ID.

Cara menetapkan polling untuk processing

Setelah respons processing pertama, masukkan pemeriksaan berikutnya ke antrean. Pilih interval berdasarkan dokumentasi API, batasan laju, dan karakter layanan. Untuk tugas yang statusnya berubah cepat, pemeriksaan lebih sering di awal masih dapat diterima. Untuk promosi bertahap, permintaan pendek yang terus-menerus biasanya tidak memberikan informasi baru.

Skema yang praktis adalah memperpanjang jeda setelah respons processing yang sama. Pemeriksaan pertama dilakukan setelah penundaan awal, lalu interval bertambah hingga batas maksimum yang ditetapkan. Jika API mengembalikan kemajuan atau waktu pembaruan baru, penghitungan dapat dimulai dari perubahan tersebut.

• Setelah membuat pesanan, jangan periksa status segera berkali-kali berturut-turut: layanan mungkin memerlukan waktu untuk memasukkan ke antrean.
• Saat processing berulang, perpanjang interval antarpermintaan, jangan pertahankan frekuensi tetap.
• Tambahkan sedikit variasi acak pada waktu mulai tugas agar pesanan tidak memanggil API secara bersamaan.
• Jika penyedia mengirimkan Retry-After atau rekomendasi serupa, gunakan itu sebagai prioritas.
• Untuk pesanan dengan webhook, tetap lakukan polling kontrol: notifikasi mungkin tidak sampai.

Kekurangan polling yang jarang adalah antarmuka dapat menampilkan status lama setelah penyelesaian sebenarnya. Kekurangan polling yang terlalu sering adalah risiko menabrak batas API, menerima 429, dan menimbulkan beban berlebih.

Waktu apa yang perlu disimpan untuk mengontrol processing

Untuk membedakan penyelesaian normal dari kemacetan, satu status saat ini tidak cukup. Untuk setiap pesanan aktif, simpan waktu pembuatan, penerimaan processing pertama, respons API sukses terakhir, perubahan terakhir status eksternal, dan perubahan terakhir kemajuan.

Berguna juga menyimpan volume awal, volume terkonfirmasi yang telah dikerjakan, sisa, dan status asli dari penyedia. Jika API tidak memberikan kemajuan, itu bukan alasan untuk menganggap pesanan macet: berpedoman pada waktu respons terakhir dan perkiraan periode pemrosesan jika tercantum dalam ketentuan layanan.

Waktu tunggu maksimum tidak boleh ditetapkan dengan satu angka untuk semua layanan. Gunakan tenggat yang ditetapkan penyedia untuk layanan tertentu, dengan cadangan internal untuk antrean dan pembaruan data. Jika tenggat tidak dicantumkan, tetapkan aturan terpisah untuk setiap kategori layanan dan tinjau kembali berdasarkan riwayat pemrosesan aktual.

Apa yang harus dilakukan jika processing tidak berubah

Processing yang lama tidak membuktikan adanya kesalahan. Pertama, periksa apakah respons API sukses masih diterima, apakah completed_quantity atau remains berubah, apakah ada webhook, dan apakah aturan layanan berubah. Tidak adanya pertumbuhan yang terlihat bisa disebabkan oleh keterlambatan statistik platform atau karena penyedia hanya memperbarui kemajuan di akhir.

Ketika tenggat tunggu internal terlampaui, jangan batalkan pesanan secara otomatis. Lakukan pemeriksaan status di luar jadwal, minta data melalui metode terpisah jika tersedia, dan periksa riwayat notifikasi. Jika penyedia masih mengonfirmasi processing, ubah pesanan ke status internal "perlu pemeriksaan", tetapi pertahankan status eksternal tanpa menggantinya.

• Catat waktu respons terkonfirmasi terakhir dan seluruh respons API.
• Periksa apakah kemajuan berubah sejak polling sebelumnya.
• Kurangi frekuensi permintaan otomatis setelah mencapai ambang internal.
• Serahkan ke dukungan ID eksternal, tautan, parameter layanan, riwayat status, dan kesalahan teknis.
• Jangan jalankan ulang sisa sebelum ada respons dari penyedia atau status akhir yang jelas.

Kekurangan pemeriksaan manual adalah pesanan memerlukan perhatian dukungan. Namun pembatalan otomatis atau duplikasi lebih berbahaya: pemrosesan mungkin masih berlanjut di penyedia.

Cara memisahkan kegagalan permintaan dari status pesanan

Kesalahan jaringan, timeout, HTTP 429, dan respons 5xx tidak menunjukkan keadaan pesanan itu sendiri. Semua itu hanya berarti status baru yang valid tidak berhasil diperoleh. Dalam situasi seperti ini, pertahankan status terkonfirmasi terakhir, catat kesalahan teknis, dan jadwalkan pemeriksaan baru.

Pada 429, perhatikan Retry-After jika header dikirimkan. Pada kesalahan jaringan sementara dan 5xx, perpanjang jeda antarpercobaan. Pada kesalahan otorisasi, tanda tangan, atau hak akses, jangan lakukan retry sering: perlu memeriksa kunci, masa berlaku token, batasan IP, dan pengaturan akses.

Jika API mengembalikan HTTP 200 tetapi JSON tidak dapat diurai atau respons tidak berisi order_id dan status, simpan seluruh isi respons dan tandai pemeriksaan sebagai tidak valid. Jangan mengganti ketiadaan status dengan completed, canceled, atau processing.

Kapan menghentikan permintaan ulang otomatis

Polling tidak boleh berlangsung tanpa batas. Batasi jumlah percobaan teknis untuk kesalahan sementara dan pantau secara terpisah total waktu pesanan berada dalam processing. Setelah batas retry habis, pindahkan tugas pemeriksaan ke antrean peninjauan, jangan buat permintaan baru setiap menit tanpa hasil.

Mengulang permintaan status biasanya aman jika metode hanya membaca data. Metode pembuatan, pembatalan, pengisian ulang, restart, dan pengembalian tidak boleh diulang secara mekanis setelah timeout. Tanpa kunci idempoten atau konfirmasi eksplisit dari penyedia, pengulangan seperti itu dapat mengubah pesanan dua kali.

Kekurangan pembatasan retry adalah sebagian pembaruan menjadi tugas manual. Retry tanpa batas lebih buruk: menyamarkan kegagalan, menghabiskan kuota, dan mempersulit analisis log.

Cara menerima status akhir setelah processing

Cegah transisi balik dari completed ke processing akibat respons polling yang terlambat atau webhook lama. Pada setiap pembaruan, bandingkan waktu peristiwa dari penyedia, nomor versi urutan jika ada, dan status internal saat ini.

• new dan pending dapat beralih ke processing, canceled, atau failed.
• processing dapat beralih ke completed, partial, canceled, atau failed.
• partial tidak boleh otomatis dianggap completed.
• completed, canceled, dan failed biasanya dianggap final dan memblokir pengembalian otomatis ke belakang.
• Status tidak dikenal atau transisi yang tidak valid memerlukan pemeriksaan terpisah.

Tabel transisi yang kaku juga memiliki kekurangan: penyedia dapat menambahkan keadaan baru yang valid. Karena itu, simpan status asli dan jangan menimpanya dengan klasifikasi internal.

Cara menangani partial dan sisa pesanan

Partial berarti hanya sebagian dari volume awal yang terkonfirmasi. Respons API dapat berisi jumlah yang benar-benar dikerjakan, sisa, alasan, dan data kompensasi. Simpan nilai-nilai ini secara terpisah: volume awal pesanan tidak boleh diganti dengan jumlah yang telah dikerjakan.

Contoh respons akhir dapat terlihat seperti ini:

{

"order_id": "",

"status": "partial",

"completed_quantity": 700,

"remains": 300,

"refund": "nilai_atau_tidak_ada_field"

}

Pertama, tentukan apa yang sebenarnya dikonfirmasi API: pengembalian sudah diproses, pengembalian baru direncanakan, sisa dibatalkan, atau perlu menghubungi dukungan. Jika tidak ada field tentang pengembalian, jangan anggap sisa sudah dikompensasi secara otomatis.

Jangan jalankan ulang bagian yang belum dikerjakan tanpa keputusan terpisah. Penyedia mungkin masih menyelesaikan perhitungan, statistik platform mungkin diperbarui dengan jeda, dan permintaan ulang dapat menciptakan promosi ganda. Kekurangan menunggu konfirmasi adalah sisa tidak akan ditutup seketika, tetapi tidak akan muncul pesanan tambahan.

Webhook tidak menggantikan pemeriksaan kontrol

Webhook memungkinkan pembaruan kartu pesanan segera setelah peristiwa, tanpa menunggu polling berikutnya. Di handler, temukan pesanan berdasarkan ID eksternal, verifikasi tanda tangan atau rahasia, simpan ID peristiwa, dan terapkan transisi hanya setelah memeriksa validitasnya.

Pengiriman ulang webhook harus aman: peristiwa yang sama tidak boleh dianggap sebagai perubahan baru. Peristiwa juga dapat datang tidak berurutan, jadi jangan kembalikan pesanan final ke belakang hanya berdasarkan processing yang terlambat.

Polling kontrol tetap diperlukan meskipun webhook stabil. Kekurangan webhook adalah pengaturan yang lebih rumit: diperlukan handler yang dapat diakses, perlindungan dari permintaan palsu, deduplikasi, dan log peristiwa.

Apa yang ditampilkan kepada klien saat processing dan macet

Di antarmuka, tidak perlu menampilkan seluruh JSON teknis. Untuk processing, cukup tampilkan keadaan "pesanan sedang diproses". Jika API mengirimkan kemajuan yang valid, tampilkan volume terkonfirmasi secara terpisah dari volume awal dan jangan menyajikannya sebagai hasil akhir.

Untuk pesanan yang melewati tenggat kontrol internal, gunakan keadaan yang mudah dipahami seperti "sedang memeriksa penyelesaian". Jangan informasikan pembatalan, pengembalian, atau penyelesaian penuh sampai hal itu dikonfirmasi oleh respons penyedia.

Notifikasi berguna saat pesanan diterima, penyelesaian akhir, partial, pembatalan, kesalahan, dan kebutuhan pemeriksaan. Pesan setelah setiap polling menimbulkan kebisingan dan tidak membantu klien memahami keadaan permintaan yang sebenarnya.

Catatan apa yang diperlukan dalam log pemrosesan

Riwayat respons membantu menganalisis processing yang macet, webhook yang hilang, sengketa atas penyelesaian sebagian, dan perbedaan antara antarmuka dan API. Untuk setiap panggilan, simpan ID eksternal, sumber pembaruan, waktu permintaan dan respons, kode HTTP, status asli, status ternormalisasi, kemajuan, sisa, dan teks kesalahan teknis.

Jangan tulis kunci API, token, tanda tangan, dan rahasia lain ke log biasa. Batasi akses ke respons mentah: di dalamnya mungkin terdapat data yang tidak boleh ada di antarmuka dukungan.

Sebelum peluncuran, uji skenario dengan processing berulang, tidak ada kemajuan, timeout, 429, kesalahan 5xx, JSON tidak valid, webhook terlambat, webhook duplikat, partial, canceled, dan status tidak dikenal. Mode uji berguna untuk struktur integrasi, tetapi kekurangannya adalah mode ini mungkin tidak mereproduksi antrean dan jeda API produksi yang sebenarnya.