Format Respons

Tipe konten

Setiap endpoint mengembalikan application/json yang dikodekan sebagai UTF-8, apa pun header Accept-nya. Kirim Content-Type: application/json pada permintaan yang membawa body.

Dua bentuk, sengaja

Endpoint koleksi membungkus payload-nya dalam data; endpoint objek tunggal mengembalikan field-nya di tingkat atas. Ini bukan kebetulan, dan perlu Anda ketahui sebelum menulis parser:

{ "data": [ { "id": 47, "slug": "wavalid-realtime" } ] }

{ "balance": "5.230000" }

GET /v1/products adalah kasus koleksi; GET /v1/balance dan GET /v1/api-key adalah kasus objek tunggal. Endpoint realtime mengembalikan objek milik panggilan itu sendiri — request_id, status, results — di tingkat atas.

Error

Error menggunakan objek dua field yang tetap:

{
  "code": "invalid_realtime_request",
  "message": "A realtime request cannot mix phone and email products."
}

Field	Arti
code	Pengenal machine-readable yang stabil. Lakukan percabangan berdasarkan ini.
message	Detail yang dapat dibaca manusia. Kata-katanya bisa berubah; jangan di-parse.

Nilai code didokumentasikan per endpoint, bersama status HTTP yang menyertainya — lihat Kode error untuk daftar lengkapnya.

Uang

Uang muncul dalam dua bentuk, dan perbedaannya penting saat Anda melakukan parsing:

Di mana	Tipe	Contoh
balance di GET /v1/balance	string	"5.230000"
total_charged, charged_amount, refunded_amount dalam respons realtime	number	0.004000

Saldo dikeluarkan sebagai string desimal berpresisi tetap agar tidak ada klien yang melihat artefak pembulatan pada nilai yang akan dibandingkan dengan ambang batas. Nominal realtime adalah angka yang dibulatkan ke enam tempat desimal — anggap perkiraan jika melebihi enam desimal.

Nominal dinyatakan dalam USD. Simbol mata uang tidak disertakan dalam payload.

Stempel waktu

Stempel waktu menggunakan ISO 8601 dalam UTC, dengan akhiran Z:

2026-09-13T10:00:00Z

checked_at pada hasil realtime, dan stempel waktu tugas pada respons bulk, mengikuti aturan ini.

Status HTTP bukan hasil akhir

Ada dua pola dan keduanya disengaja:

• Realtime: HTTP 200 berarti panggilan dieksekusi, bukan berarti setiap produk menjawab. Baca status dan billing_status tiap entri.
• Bulk: pengiriman mengembalikan penerimaan tugas bergaya 202; pekerjaan berlanjut secara asinkron dan hasilnya baru ada setelah tugas mencapai status terminal.

Aturannya pada kedua kasus: kode status memberi tahu apakah Anda harus mencoba ulang, body memberi tahu apa yang terjadi.

Berikutnya

• Kode error — setiap code, per endpoint
• Batas laju — header yang dikembalikan bersama 429