Dukungan Idempotency Key

Dalam lingkungan jaringan yang terdistribusi, kegagalan koneksi dapat terjadi sewaktu-waktu. Misalnya, klien Anda mengirim pesan ke Kirem, sistem Kirem memproses dan berhasil mengirimkannya ke Meta, namun koneksi internet klien terputus sebelum menerima respons dari Kirem.

Jika klien mengirim ulang permintaan tersebut, hal ini berisiko mengirimkan pesan ganda (SPAM) kepada pelanggan dan menambah biaya pemakaian Meta API Anda secara sia-sia. Untuk mengatasi masalah ini, Kirem mendukung fitur kunci idempotensi (Idempotency Key).

⚙️ 1. Cara Kerja Idempotensi di Kirem

Idempotensi menjamin bahwa sebuah operasi API dapat dipanggil berulang kali dengan hasil yang sama tanpa mengubah keadaan (state) sistem lebih lanjut setelah pemanggilan pertama.

1. Pengiriman Header: Klien menyertakan header khusus Idempotency-Key dengan nilai unik (direkomendasikan menggunakan format UUID v4).
2. Pemeriksaan Cache: Kirem akan mendeteksi header tersebut dan memeriksa apakah kunci idempotensi tersebut sudah pernah digunakan untuk proyek terkait (ProjectID) dalam kurun waktu 24 jam terakhir.
3. Pengembalian Respons Instan:
   • Jika Kunci Ditemukan (Cache Hit): Kirem tidak akan mengirimkan request ulang ke Meta API. Kirem akan langsung mengembalikan respons yang sama persis seperti respons pada pengiriman pertama, lengkap dengan HTTP status code yang sama.
   • Jika Kunci Tidak Ditemukan (Cache Miss): Kirem akan memproses pengiriman pesan ke Meta API, menyimpan hasilnya ke cache idempotensi, dan mengembalikan respons ke klien.

🛜 2. Cara Menggunakan Idempotency Key

Cukup sertakan header Idempotency-Key saat mengirimkan pesan via endpoint POST /v1/messages.

Contoh cURL Request:

curl -X POST https://api.kirem.id/v1/messages \
  -H "Authorization: Bearer kirem_live_xxx" \
  -H "Idempotency-Key: e7b2a95c-9c2f-4b0d-9ea1-df3d686bc456" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "62812345678",
    "type": "text",
    "text": { "body": "Halo Budi, tagihan Anda sebesar Rp 150.000 telah terbit." }
  }'

Respons Pertama (201 Created):

{
  "status": 201,
  "message": "Message sent successfully",
  "data": {
    "messaging_product": "whatsapp",
    "contacts": [{"input": "62812345678", "wa_id": "62812345678"}],
    "messages": [{"id": "wamid.HBgLNjI4MTIzNDU..."}]
  }
}

Respons Kedua (Mengirim ulang dengan Idempotency-Key yang sama):

Kirem akan mengembalikan isi body yang sama secara instan dalam hitungan milidetik, tanpa mengirim ulang pesan ke nomor tujuan pelanggan.

🚨 3. Aturan & Batasan Penting

• Lingkup Kunci: Keunikan kunci idempotensi dipisahkan per ProjectID. Proyek yang berbeda dapat menggunakan nilai kunci yang sama tanpa saling mengintervensi.
• Masa Kedaluwarsa: Cache idempotensi otomatis dihapus setelah 24 jam. Setelah 24 jam, pengiriman dengan kunci yang sama akan dianggap sebagai request baru.
• Perubahan Payload: Jika Anda mengirim ulang request dengan Idempotency-Key yang sama tetapi mengubah isi payload body (misal nomor tujuan berbeda atau pesan berbeda), Kirem akan mendeteksi ketidakcocokan tersebut dan mengembalikan error 400 Bad Request untuk mencegah penyalahgunaan kunci.