Cara mengatur notifikasi penyelesaian pesanan API

Peristiwa apa yang dianggap sebagai penyelesaian pesanan

Pertama, tentukan status mana di API yang berarti pesanan benar-benar selesai. Pada penyedia yang berbeda, ini bisa berupa pesanan yang telah dipenuhi, terkirim, dibatalkan, ditolak, dikembalikan, atau dipenuhi sebagian. Jangan mengaitkan otomatisasi hanya pada kata "sukses": pesanan dapat melewati beberapa keadaan perantara, lalu berhenti karena batas, pemeriksaan, atau pembatalan.

Yang perlu ditangani bukan hanya hasil positif. Jika layanan mengirim notifikasi tentang kesalahan, pembatalan, pengembalian, atau pemenuhan sebagian, hal itu juga harus dicatat ke sistem internal. Jika tidak, di panel, CRM, atau bot, pesanan akan tetap dalam status menunggu padahal pelaksanaan selanjutnya tidak akan terjadi.

Buat tabel pemetaan status

Jangan meneruskan status API ke antarmuka tanpa diproses. Nama dan logika penyedia dapat berubah, dan satu status internal yang sama terkadang menggabungkan beberapa status eksternal. Simpan nilai asli secara terpisah: nilai ini akan berguna untuk menelusuri kesalahan dan mencocokkan dengan dokumentasi.

• pending, created, queued — pesanan baru atau menunggu diproses.
• processing, in_progress, running — pesanan sedang diproses.
• completed, delivered, success — pesanan selesai.
• partial, partially_completed — pesanan dipenuhi sebagian.
• cancelled, rejected, failed — pesanan dibatalkan atau berakhir dengan kesalahan.
• refunded, returned — pesanan memerlukan pengembalian dana atau penyesuaian.
• Status tidak dikenal — tidak mengubah kartu secara otomatis dan diteruskan untuk pemeriksaan.

Nama-nama di atas diberikan sebagai contoh skema. Tabel final harus dibuat berdasarkan status API tertentu. Kekurangan pemetaan manual adalah setelah API diperbarui, pemetaan tersebut harus dipelihara: status baru bisa masuk ke handler sebelum ada aturan untuknya.

Pilih webhook, polling API, atau kedua skema

Webhook adalah permintaan dari layanan ke URL Anda saat status pesanan berubah. Polling API bekerja sebaliknya: sistem Anda meminta informasi pesanan secara berkala. Untuk notifikasi penyelesaian, biasanya webhook lebih praktis karena pembaruan datang tanpa permintaan terus-menerus ke metode pemeriksaan status.

• Webhook cocok untuk reaksi cepat: memperbarui kartu, memulai tahap berikutnya, atau mengirim pesan kepada penanggung jawab.
• Polling cocok jika penyedia tidak mendukung notifikasi callback atau server tidak menerima permintaan eksternal.
• Skema gabungan menggunakan webhook sebagai kanal utama, dan polling untuk mencari pesanan yang terlewat atau macet.

Kekurangan polling adalah keterlambatan dan beban tambahan pada API. Kekurangan webhook adalah endpoint harus diamankan, duplikat harus diperhitungkan, dan jangan mengandalkan urutan pengiriman peristiwa.

Siapkan endpoint untuk menerima peristiwa

Untuk notifikasi, diperlukan alamat HTTPS publik yang dapat diakses dari sisi layanan API. Dalam pengaturan integrasi biasanya ditentukan URL handler, secret tanda tangan, dan daftar peristiwa: perubahan status, penyelesaian, pembatalan, kesalahan, atau pemenuhan sebagian.

Sediakan rute terpisah khusus untuk peristiwa API. Dengan begitu lebih mudah mengatur pencatatan log, membatasi akses, menetapkan batas permintaan, dan tidak mencampur lalu lintas layanan dengan formulir situs. Jangan gunakan alamat lingkungan pengujian untuk pesanan produksi: setelah lingkungan diperbarui, penyedia akan terus mengirim peristiwa ke URL yang tersimpan.

Sebelum peluncuran, periksa metode permintaan dan format body sesuai dokumentasi. Paling sering ini adalah POST dengan JSON, tetapi ada juga form-data, parameter query, atau skema serialisasi tersendiri. Kesalahan parsing harus dicatat ke log, jika tidak akan sulit membedakan payload yang salah dari kegagalan aplikasi.

Simpan keterkaitan antara pesanan dan peristiwa

Saat membuat pesanan melalui API, simpan pengenal yang dikembalikan penyedia. Di sampingnya, simpan nomor pesanan internal, jenis layanan, status asli, waktu perubahan terakhir, dan respons API asli dalam bentuk yang aman. Cocokkan webhook masuk berdasarkan ID penyedia, bukan berdasarkan tautan ke kanal, nama layanan, atau nama klien.

Jika API mengizinkan pengiriman pengenal eksternal saat pembuatan, tambahkan nomor pesanan Anda ke bidang seperti external_id atau client_reference. Ini memudahkan pencarian di log dan penelusuran situasi yang diperdebatkan. Namun jangan jadikan nomor eksternal sebagai satu-satunya kunci: sebagian penyedia tidak mengembalikannya di setiap notifikasi.

Jangan membuat pesanan baru berdasarkan ID tidak dikenal dari webhook. Peristiwa yang tidak dikenal harus disimpan di log dan diperiksa secara terpisah. Pembuatan catatan otomatis dapat menyebabkan data yang salah atau pemrosesan permintaan palsu.

Gunakan struktur payload yang jelas

Nama bidang yang tepat bergantung pada API. Berikut ini bukan kontrak layanan tertentu, melainkan contoh peristiwa JSON yang dapat menjadi acuan saat merancang handler internal. Yang penting adalah pengenal peristiwa, ID pesanan pada penyedia, status, waktu perubahan, dan data untuk diagnosis.

{

  "event_id": "evt_7f31",

  "event_type": "order.status_changed",

  "created_at": "2025-01-15T12:40:00Z",

  "data": {

    "order_id": "provider_order_4815",

    "external_id": "internal_order_9021",

    "status": "completed",

    "completed_quantity": 1000,

    "requested_quantity": 1000

  }

}

Jangan gunakan jumlah unit yang telah dipenuhi sebagai tanda penyelesaian tanpa status. Pesanan dapat dipenuhi sebagian, dan angka dalam payload bisa dibulatkan, diperbarui dengan keterlambatan, atau tidak dikirim sama sekali. Kekurangan menyimpan seluruh body peristiwa adalah di dalamnya mungkin terdapat data pribadi atau bidang layanan, sehingga catatan tersebut perlu disamarkan dan dibatasi masa simpannya.

Verifikasi tanda tangan berdasarkan body permintaan asli

URL handler yang terbuka dapat menerima permintaan bukan hanya dari layanan API. Jika penyedia mengirim tanda tangan, secret, atau token, verifikasi semuanya sebelum mengubah pesanan. Skema yang umum adalah HMAC-SHA256: penyedia menghitung tanda tangan dari byte body permintaan dan secret bersama, lalu mengirimkan hasilnya di header HTTP.

Prinsip perhitungannya seperti ini: diambil body permintaan asli, misalnya byte JSON tanpa perubahan, dan secret integrasi. Kemudian dihitung HMAC-SHA256. Jika hasil dalam bentuk heksadesimal sama dengan nilai header, body tidak berubah setelah ditandatangani dan permintaan kemungkinan dikirim oleh pihak yang mengetahui secret.

Contoh bersyarat: HMAC_SHA256(secret, raw_body) = tanda tangan dari header X-Signature. Nama header, algoritme, dan format hasil harus diambil hanya dari dokumentasi API. Sebagian layanan menambahkan stempel waktu atau ID peristiwa ke dalam string untuk tanda tangan. Dalam hal ini, tidak boleh hanya memverifikasi body JSON.

Jangan mengubah JSON sebelum memverifikasi tanda tangan

Tanda tangan diverifikasi berdasarkan byte permintaan asli, bukan berdasarkan objek JSON yang sudah diurai dan disusun ulang oleh aplikasi. Saat serialisasi ulang, urutan bidang, spasi, escaping karakter, baris baru, atau pengodean dapat berubah. Bagi manusia JSON tetap sama, tetapi kumpulan byte berubah, dan HMAC tidak akan cocok lagi.

Untuk menghindari hal ini, pertama dapatkan raw body sebagai bytes atau buffer, simpan di memori, hitung tanda tangan, dan hanya setelah verifikasi berhasil uraikan JSON. Jangan menerapkan trim, konversi pengodean, pengurutan kunci, dan pemformatan pada body. Pada middleware framework, periksa apakah JSON diurai secara otomatis sebelum akses ke body asli.

Kekurangan skema ini adalah handler menjadi bergantung pada urutan middleware. Jika salah konfigurasi, aplikasi hanya akan melihat objek yang telah diubah, dan notifikasi yang sah akan mulai ditolak.

Contoh handler dengan verifikasi HMAC

Berikut adalah contoh bersyarat dalam Python. Ini menunjukkan urutan tindakan, bukan integrasi siap pakai: header, algoritme, format tanda tangan, dan bidang payload harus diganti dengan nilai dari dokumentasi penyedia.

import hmac

import hashlib

import json

from hmac import compare_digest

def handle_webhook(request):

  raw_body = request.body

  received_signature = request.headers.get("X-Signature", "")

  secret = get_webhook_secret()

  expected_signature = hmac.new(

    secret.encode("utf-8"), raw_body, hashlib.sha256

  ).hexdigest()

  if not compare_digest(expected_signature, received_signature):

    log_invalid_signature(request)

    return response(status=401)

  payload = json.loads(raw_body.decode("utf-8"))

  return process_event(payload)

Untuk perbandingan, gunakan fungsi yang tidak berhenti pada karakter pertama yang tidak cocok. Ini mengurangi risiko kebocoran data tentang tanda tangan melalui waktu respons. Jangan kirim secret ke kode klien, jangan tambahkan ke URL, dan jangan catat seluruhnya di log.

Buat pemrosesan peristiwa menjadi idempoten

Penyedia dapat mengirim peristiwa yang sama beberapa kali. Penyebabnya biasa: server Anda merespons terlalu lama, koneksi terputus setelah data disimpan, endpoint sementara mengembalikan kesalahan, atau layanan memulai pengiriman ulang sesuai aturannya sendiri. Pengulangan tidak berarti API membuat pesanan baru.

Idempotensi berarti peristiwa yang sama hanya mengubah hasil satu kali. Jika aturan ini diabaikan, duplikat akan mengirim ulang pesan ke klien, membuat beberapa tugas untuk manajer, memberikan kompensasi, atau memulai operasi berulang.

Cara terbaik adalah menggunakan event_id dari payload. Simpan di tabel terpisah atau log peristiwa yang telah diproses dengan batasan unik. Jika tidak ada ID terpisah, bentuk kunci dari bidang yang stabil: ID pesanan penyedia, jenis peristiwa, status, dan waktu perubahan. Opsi ini lebih buruk: jika stempel waktu tidak akurat, peristiwa berbeda dapat terlihat sama.

Simpan peristiwa dan status dalam satu operasi

Pemeriksaan "apakah peristiwa sudah diproses" dan pencatatan hasil harus dilakukan secara atomik. Jika tidak, dua permintaan identik yang datang bersamaan akan sama-sama melihat tidak ada catatan dan menjalankan tindakan dua kali. Opsi praktisnya adalah indeks unik pada event_id dan transaksi basis data.

Kelanjutan handler secara bersyarat terlihat seperti ini:

def process_event(payload):

  event_id = payload["event_id"]

  provider_order_id = payload["data"]["order_id"]

  new_status = map_status(payload["data"]["status"])

  with database_transaction():

    if event_exists(event_id):

      return response(status=200)

    order = find_order_by_provider_id(provider_order_id)

    if order is None:

      save_unmatched_event(event_id, payload)

      return response(status=200)

    apply_status_if_allowed(order, new_status, payload)

    save_processed_event(event_id, provider_order_id)

  enqueue_follow_up_actions(event_id)

  return response(status=200)

Kekurangan merespons dengan kode sukses untuk pesanan yang tidak dikenal adalah penyedia mungkin tidak mengulang pengiriman. Karena itu, peristiwa yang tidak dikenal harus dipantau secara terpisah dan segera ditelusuri. Jika dokumentasi API menyarankan kode respons lain untuk kasus seperti ini, ikuti dokumentasi tersebut.

Perhitungkan pelanggaran urutan peristiwa

Webhook tidak selalu datang sesuai urutan waktu perubahan status. Pertama bisa masuk peristiwa tentang penyelesaian, lalu notifikasi tertunda tentang status "sedang diproses". Jika hanya mencatat nilai terakhir yang diterima, pesanan yang sudah selesai akan kembali menjadi aktif.

Tentukan transisi yang diizinkan. Misalnya, status perantara tidak boleh menimpa status final, dan pesanan yang dibatalkan tidak diubah menjadi selesai tanpa pemeriksaan terpisah. Jika API mengizinkan penyesuaian status final, simpan alasan, nilai asli, dan sumber perubahan.

Jika payload berisi waktu perubahan pesanan, bandingkan waktu itu, bukan waktu penerimaan webhook. Ketika API tidak mengirimkan penanda tersebut, gunakan prioritas keadaan dan rekonsiliasi melalui metode pengambilan pesanan. Kekurangan prioritas adalah prioritas tidak menggantikan urutan sebenarnya, terutama jika penyedia mengizinkan pengembalian dari status final.

Konfirmasi pengiriman dengan cepat dan pindahkan tindakan ke antrean

Jangan lakukan operasi yang lama sebelum merespons penyedia. Verifikasi tanda tangan, pencarian pesanan, pencatatan peristiwa, dan pembaruan status biasanya dapat diselesaikan dengan cepat. Pengiriman pesan, sinkronisasi dengan CRM, pembuatan laporan, atau permintaan ke sistem pihak ketiga sebaiknya diteruskan ke antrean tugas.

Urutan kerja yang tepat: verifikasi tanda tangan, simpan peristiwa dan perubahan status secara atomik, kembalikan respons sukses, lalu lakukan tindakan sekunder. Jika merespons sebelum menyimpan, data akan hilang saat terjadi kegagalan. Jika merespons setelah pengiriman notifikasi yang lama, penyedia dapat menganggap pengiriman tidak berhasil dan mengirim duplikat.

Kekurangan antrean adalah munculnya komponen terpisah yang perlu dipantau: kesalahan tugas, keterlambatan, dan eksekusi ulang. Namun kegagalan dalam notifikasi manajer tidak menghalangi penerimaan status pesanan.

Atur notifikasi untuk tim dan klien

Setelah perubahan status, tidak semua pihak perlu diberi tahu dengan cara yang sama. Manajer biasanya perlu mengetahui pembatalan, kesalahan, pemenuhan sebagian, dan pesanan yang lama tidak berubah. Bagi klien, biasanya cukup hasil akhir yang jelas: pesanan selesai, dibatalkan, atau memerlukan klarifikasi.

• Pesanan selesai — pembaruan di akun pribadi atau pesan singkat kepada klien.
• Kesalahan pelaksanaan — notifikasi kepada penanggung jawab dengan alasan yang dikirim API.
• Pemenuhan sebagian — tugas untuk memeriksa penyesuaian, pengembalian dana, atau tindakan berikutnya.
• Status tidak dikenal — catatan di log dan pesan kepada spesialis teknis.
• ID pesanan tidak dikenal — pemeriksaan terpisah atas keterkaitan antara sistem Anda dan penyedia.

Jangan kirim pesan pada setiap transisi teknis. Feed akan cepat menjadi bising, dan masalah penting akan terlewat. Notifikasi internal harus berisi nomor pesanan, layanan, status saat ini, ID eksternal, dan tautan ke kartu.

Catat log dan rekonsiliasi pesanan yang belum selesai

Log diperlukan untuk memahami apakah layanan mengirim peristiwa, body apa yang datang, mengapa tanda tangan gagal, dan pada tahap mana pemrosesan berhenti. Simpan waktu penerimaan, ID peristiwa, ID pesanan, jenis peristiwa, hasil verifikasi tanda tangan, status internal, dan kode respons. Samarkan secret, token, dan data pribadi.

Pantau secara terpisah kesalahan pengiriman, tanda tangan tidak valid, pesanan tidak dikenal, status yang tidak didukung, duplikat, dan peristiwa yang tidak dapat diterapkan karena urutan keadaan. Pertumbuhan catatan seperti ini dapat berarti perubahan skema API, secret kedaluwarsa, kegagalan rute, atau kesalahan dalam logika handler.

Secara berkala, rekonsiliasi pesanan dalam status perantara melalui metode pengambilan data API. Pemeriksaan ini tidak menggantikan webhook, tetapi membantu menemukan peristiwa yang terlewat, kegagalan antrean, atau kasus ketika status eksternal berubah tanpa notifikasi yang benar.