Komplain
Beri pelanggan Anda tombol “ajukan komplain” yang langsung terhubung ke tim Bisadagang, tanpa membuka dashboard.
Ringkasan
Komplain lewat API dan lewat dashboard masuk ke antrean yang sama di tim Bisadagang dan tampil bersama di menu Komplain. Perubahan statusnya dikirim ke webhook Anda.
- Autentikasi dan signature sama dengan endpoint lain; lihat Autentikasi & signature. Request POST membawa body JSON yang ikut diberi signature. Tidak perlu
Idempotency-Key: komplain yang sama tidak bisa dibuat dua kali (lihatCOMPLAINT_EXISTS). - Key production hanya melihat komplain production, key sandbox hanya komplain sandbox.
- Respons sukses memakai
200 OKdan format yang sama dengan endpoint lain; lihat Format respons & kode error.
Aturan komplain
- Pending bisa dikomplain langsung, tanpa menunggu lama. Anda yang menilai kapan pelanggan sudah menunggu terlalu lama.
- Sukses tetapi belum masuk ke pelanggan juga bisa dikomplain (pulsa belum masuk, SN atau token tidak valid).
- Gagal tidak bisa dikomplain. Saldo sudah dikembalikan otomatis.
- Batas pengajuan H+7: 7 × 24 jam sejak transaksi dibuat (
created_attransaksi). Setelahnya komplain ditolak. - Satu komplain aktif per transaksi. Selama komplain berstatus
openatauprocessing, mengajukan lagi dijawabCOMPLAINT_EXISTS. Setelahresolved, Anda boleh mengajukan lagi selama masih dalam batas H+7.
pending_too_long (pending terlalu lama) atau other.success_not_received (sukses tapi belum masuk), invalid_sn (SN atau token tidak valid), atau other.Buat komplain
Body
ref_id atau transaction_id, tidak keduanya dan tidak kosong. ref_id adalah referensi dari sistem Anda saat membuat transaksi.data.transaction_id di respons transaksi). Gunakan ini atau ref_id.pending_too_long, success_not_received, invalid_sn, atau other. Harus cocok dengan status transaksi; lihat Aturan komplain.reason adalah other. Jadi pesan pertama di percakapan.Request
# BISADAGANG_API_KEY dan BISADAGANG_API_SECRET diisi di environment
REQ_PATH="/h2h/v1/complaints"
BODY='{"ref_id":"INV-20261119-0001","reason":"pending_too_long","note":"Pelanggan sudah menunggu lebih dari 2 jam."}'
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 | awk '{print $NF}')
CANONICAL=$(printf '%s\n%s\n%s\n%s\n%s' "POST" "$REQ_PATH" "$TS" "$NONCE" "$BODY_HASH")
SIGNATURE=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -hmac "$BISADAGANG_API_SECRET" | awk '{print $NF}')
curl -X POST "https://api.bisadagang.com$REQ_PATH" \
-H "Content-Type: application/json" \
-H "X-Bisadagang-Key: $BISADAGANG_API_KEY" \
-H "X-Bisadagang-Timestamp: $TS" \
-H "X-Bisadagang-Nonce: $NONCE" \
-H "X-Bisadagang-Signature: $SIGNATURE" \
--data "$BODY"Respons
Komplain langsung berstatus open dan masuk antrean tim.
{
"success": true,
"data": {
"complaint_id": "KMP1763527331A1K7",
"transaction_id": "PL1763522142AB12",
"ref_id": "INV-20261119-0001",
"product_code": "TSEL10",
"product_name": "Telkomsel 10.000",
"customer_no": "081200000001",
"price": 10450,
"reason": "pending_too_long",
"status": "open",
"result": null,
"source": "api",
"environment": "production",
"created_at": "2026-11-19T05:20:00.000Z",
"messages": [
{
"from": "partner",
"text": "Pelanggan sudah menunggu lebih dari 2 jam.",
"created_at": "2026-11-19T05:20:00.000Z"
}
]
},
"request_id": "a1b2c3d4e5"
}{
"success": false,
"error": {
"code": "COMPLAINT_EXISTS",
"message": "Transaksi ini masih punya komplain yang belum selesai.",
"details": { "complaint_id": "KMP1763527331A1K7" }
},
"request_id": "a1b2c3d4e5"
}{
"success": false,
"error": {
"code": "COMPLAINT_WINDOW_CLOSED",
"message": "Batas pengajuan komplain (7 hari sejak transaksi) sudah lewat.",
"details": { "deadline": "2026-11-12T09:15:30.000Z" }
},
"request_id": "a1b2c3d4e5"
}{
"success": false,
"error": {
"code": "COMPLAINT_NOT_ALLOWED",
"message": "Transaksi gagal tidak perlu dikomplain. Saldo sudah dikembalikan.",
"details": { "status": "failed", "allowed_reasons": [] }
},
"request_id": "a1b2c3d4e5"
}Objek komplain
Semua endpoint komplain mengembalikan objek ini (atau daftarnya) di dalam data.
Cek komplain
# BISADAGANG_API_KEY dan BISADAGANG_API_SECRET diisi di environment
REQ_PATH="/h2h/v1/complaints/KMP1763527331A1K7"
BODY=""
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 | awk '{print $NF}')
CANONICAL=$(printf '%s\n%s\n%s\n%s\n%s' "GET" "$REQ_PATH" "$TS" "$NONCE" "$BODY_HASH")
SIGNATURE=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -hmac "$BISADAGANG_API_SECRET" | awk '{print $NF}')
curl "https://api.bisadagang.com$REQ_PATH" \
-H "X-Bisadagang-Key: $BISADAGANG_API_KEY" \
-H "X-Bisadagang-Timestamp: $TS" \
-H "X-Bisadagang-Nonce: $NONCE" \
-H "X-Bisadagang-Signature: $SIGNATURE"{
"success": true,
"data": {
"complaint_id": "KMP1763527331A1K7",
"transaction_id": "PL1763522142AB12",
"ref_id": "INV-20261119-0001",
"product_code": "TSEL10",
"product_name": "Telkomsel 10.000",
"customer_no": "081200000001",
"price": 10450,
"reason": "pending_too_long",
"status": "resolved",
"result": "success",
"source": "api",
"environment": "production",
"created_at": "2026-11-19T05:20:00.000Z",
"messages": [
{
"from": "partner",
"text": "Pelanggan sudah menunggu lebih dari 2 jam.",
"created_at": "2026-11-19T05:20:00.000Z"
},
{
"from": "team",
"text": "Sudah kami cek ke penyedia, pulsa masuk.",
"created_at": "2026-11-19T05:41:12.000Z"
},
{
"from": "system",
"text": "Komplain selesai. Transaksi berstatus sukses.",
"created_at": "2026-11-19T05:41:13.000Z"
}
]
},
"request_id": "a1b2c3d4e5"
}Komplain yang tidak ada atau milik Mitra Bisnis lain dijawab 404 NOT_FOUND.
Daftar komplain
Komplain dari API dan dashboard muncul bersama, terbaru dulu.
open, processing, atau resolved.next_cursor dari respons sebelumnya untuk halaman berikutnya.# BISADAGANG_API_KEY dan BISADAGANG_API_SECRET diisi di environment
REQ_PATH="/h2h/v1/complaints?status=open&limit=20"
BODY=""
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 | awk '{print $NF}')
CANONICAL=$(printf '%s\n%s\n%s\n%s\n%s' "GET" "$REQ_PATH" "$TS" "$NONCE" "$BODY_HASH")
SIGNATURE=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -hmac "$BISADAGANG_API_SECRET" | awk '{print $NF}')
curl "https://api.bisadagang.com$REQ_PATH" \
-H "X-Bisadagang-Key: $BISADAGANG_API_KEY" \
-H "X-Bisadagang-Timestamp: $TS" \
-H "X-Bisadagang-Nonce: $NONCE" \
-H "X-Bisadagang-Signature: $SIGNATURE"{
"success": true,
"data": {
"complaints": [
{
"complaint_id": "KMP1763527331A1K7",
"transaction_id": "PL1763522142AB12",
"ref_id": "INV-20261119-0001",
"product_code": "TSEL10",
"product_name": "Telkomsel 10.000",
"customer_no": "081200000001",
"price": 10450,
"reason": "pending_too_long",
"status": "open",
"result": null,
"source": "api",
"environment": "production",
"created_at": "2026-11-19T05:20:00.000Z",
"messages": [
{
"from": "partner",
"text": "Pelanggan sudah menunggu lebih dari 2 jam.",
"created_at": "2026-11-19T05:20:00.000Z"
}
]
}
],
"next_cursor": null
},
"request_id": "a1b2c3d4e5"
}next_cursor bernilai null di halaman terakhir. Jangan menyusun isinya sendiri.
Balas komplain
Kirim info tambahan atau jawaban untuk tim, misalnya bukti dari pelanggan. Balasan hanya diterima selama komplain open atau processing.
# BISADAGANG_API_KEY dan BISADAGANG_API_SECRET diisi di environment
REQ_PATH="/h2h/v1/complaints/KMP1763527331A1K7/messages"
BODY='{"text":"Pelanggan mengirim bukti struk, bisa kami lampirkan?"}'
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 | awk '{print $NF}')
CANONICAL=$(printf '%s\n%s\n%s\n%s\n%s' "POST" "$REQ_PATH" "$TS" "$NONCE" "$BODY_HASH")
SIGNATURE=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -hmac "$BISADAGANG_API_SECRET" | awk '{print $NF}')
curl -X POST "https://api.bisadagang.com$REQ_PATH" \
-H "Content-Type: application/json" \
-H "X-Bisadagang-Key: $BISADAGANG_API_KEY" \
-H "X-Bisadagang-Timestamp: $TS" \
-H "X-Bisadagang-Nonce: $NONCE" \
-H "X-Bisadagang-Signature: $SIGNATURE" \
--data "$BODY"Respons 200 OK berisi objek komplain lengkap dengan balasan Anda di messages. Komplain yang sudah resolved dijawab 422 COMPLAINT_CLOSED; ajukan komplain baru jika masalahnya muncul lagi dan masih dalam batas H+7.
Status
result mengikuti status akhir transaksi: success jika transaksi sukses, atau failed jika transaksi gagal dan saldo sudah dikembalikan. Komplain pada transaksi yang masih pending baru bisa selesai setelah transaksinya final. Pesan penutup dari system menyebut hasilnya. Pantau juga transaction.updated.Webhook complaint.updated
Event complaint.updated dikirim setiap status komplain berubah dan setiap kali tim atau sistem menambah pesan. Komplain yang Anda ajukan dan balasan yang Anda kirim sendiri tidak memicu event. Event ini tidak selalu aktif: pilih di menu Webhook di dashboard. Signature, retry, dan idempotensi sama dengan event lain; lihat Webhook untuk tabel field-nya.
{
"event_id": "whd_Rk3Lm9Pa",
"event": "complaint.updated",
"environment": "production",
"created_at": "2026-11-19T05:41:13Z",
"data": {
"complaint_id": "KMP1763527331A1K7",
"transaction_id": "PL1763522142AB12",
"ref_id": "INV-20261119-0001",
"status": "resolved",
"result": "success",
"message": {
"from": "system",
"text": "Komplain selesai. Transaksi berstatus sukses.",
"created_at": "2026-11-19T05:41:13.000Z"
}
}
}Sandbox
- Key sandbox bisa mengajukan komplain untuk transaksi sandbox dengan aturan dan format yang sama.
- Komplain sandbox tidak diteruskan ke tim. Sekitar 30 detik setelah dibuat, sistem otomatis menyelesaikannya (
resolved,resultsuccess) dan mengirimcomplaint.updatedke URL webhook sandbox Anda.
Kode error
ref_id dan transaction_id keduanya diisi atau keduanya kosong, reason tidak dikenal, note atau text lebih dari 1000 karakter, note kurang dari 10 karakter untuk other, atau text kosong.open atau processing. ID-nya ada di details.complaint_id.reason tidak cocok dengan status transaksi. details.status berisi status transaksi dan details.allowed_reasons daftar alasan yang boleh.details.deadline.RATE_LIMITED, INTERNAL_ERROR) ada di Format respons & kode error. Tangani kode yang belum Anda kenal berdasarkan status HTTP-nya.