Pemeriksaan satu nomor secara realtime

POST/v1/realtime/check/phone

Periksa satu nomor secara sinkron. Satu permintaan dapat memilih beberapa produk realtime berdasarkan ID; jangan gunakan slug produk massal.

Parameter

Field	Tipe	Wajib	Deskripsi
`identifier`	string	Ya	Satu nomor E.164, misalnya +8613800138000.
`country`	string	Tidak	Opsional untuk E.164 lengkap; nomor lokal membutuhkan kode negara ISO yang sesuai. — Kode Negara
`product_ids`	array	Ya	Daftar 1 sampai 10 ID produk realtime.

Memilih produk yang diperiksa

ID produk tidak perlu ditebak: ambil id dari entri yang mode-nya realtime pada GET /v1/products. Produk massal dialamatkan lewat slug, jadi slug tidak pernah berlaku di endpoint ini. Halaman daftar produk menampilkan ID realtime dengan awalan # justru karena alasan ini.

Daftar Produk

Satu panggilan memeriksa satu nomor terhadap maksimal sepuluh produk realtime. Anda menerima satu request_id, satu entri per produk di results, dan setiap entri ditagih terpisah sehingga status bisa bernilai partial_succeeded. Lebih dari sepuluh ID dalam satu panggilan ditolak; konsol memakai batas yang sama.

Contoh Respons

{
  "request_id": "8c1e4f91-7bd8-4d7e-a3ae-3d7e5b0c6c11",
  "identifier": "+8613800138000",
  "series": "phone",
  "status": "succeeded",
  "request_status": "completed",
  "replayed": false,
  "total_reserved": 0.004000,
  "total_charged": 0.004000,
  "total_refunded": 0.000000,
  "charged_amount": 0.004000,
  "refunded_amount": 0.000000,
  "results": [
    {
      "product_id": 47,
      "product": "wavalid-realtime",
      "result": "valid",
      "cached": false,
      "billing_status": "charged",
      "charged_amount": 0.002000,
      "refunded_amount": 0.000000,
      "checked_at": "2026-09-05T10:00:00Z",
      "error_code": null
    },
    {
      "product_id": 50,
      "product": "tgValid-rt",
      "result": "invalid",
      "cached": false,
      "billing_status": "charged",
      "charged_amount": 0.002000,
      "refunded_amount": 0.000000,
      "checked_at": "2026-09-05T10:00:01Z",
      "error_code": null
    }
  ]
}

Bidang Respons

Field	Tipe	Deskripsi
`request_id`	string (UUID)	UUID yang mengidentifikasi pengiriman ini. Sertakan dalam permintaan dukungan.
`identifier`	string	Identifier yang diperiksa, dikembalikan apa adanya.
`series`	string	`phone` atau `email`.
`status`	string	`succeeded`, `partial_succeeded` atau `failed` — diturunkan dari berapa banyak hasil yang ditagih.
`request_status`	string	Status siklus hidup internal permintaan.
`total_reserved`	number	Jumlah yang dicadangkan sebelum pemeriksaan dijalankan.
`total_charged`	number	Total yang ditagih di seluruh produk dalam kombinasi.
`total_refunded`	number	Total yang dikembalikan untuk item yang tidak dapat diselesaikan.
`charged_amount`	number	Tagihan bersih. Selalu sama dengan `total_charged`.
`refunded_amount`	number	Pengembalian bersih. Selalu sama dengan `total_refunded`.
`replayed`	boolean	`true` jika pemutaran ulang Idempotency-Key mengembalikan hasil yang tersimpan.
`results`	array	Satu entri per produk yang diminta, sesuai urutan permintaan produk.

`results[]`

Field	Tipe	Deskripsi
`product_id`	integer	ID produk realtime dari katalog.
`product`	string	Slug produk yang dirujuk oleh ID tersebut.
`result`	string	`valid`, `invalid` atau `unknown` — apakah identifier terdaftar.
`cached`	boolean	`true` jika putusan berasal dari cache. Pengambilan dari cache tetap ditagih.
`billing_status`	string	`charged` atau `refunded`.
`charged_amount`	number	Jumlah yang ditagih untuk produk ini.
`refunded_amount`	number	Jumlah yang dikembalikan untuk produk ini.
`checked_at`	string (ISO 8601)	Kapan putusan dihasilkan, dalam UTC.
`error_code`	string \| null	Alasan item tidak dapat diselesaikan, atau `null` jika berhasil.

Contoh cURL

curl -X POST "https://api.zelnum.com/api/v1/realtime/check/phone" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"+8613800138000","country":"CN","product_ids":[47,50]}'

Penagihan & semantik

Setiap produk memakai harga per pemeriksaan yang dikunci untuk permintaan, termasuk hasil cache. valid dan invalid ditagih; unknown, timeout, dan item sibuk dikembalikan.

Kombinasi yang berhasil sebagian mengembalikan HTTP 200 dengan status=partial_succeeded; semua gagal memakai status=failed. Periksa billing_status dan error_code tiap item.

Idempotency-Key maksimal 191 byte dan berlaku per pengguna. Setelah timeout atau error 500, ulangi isi asli dengan kunci asli. Hasil disimpan 30 hari secara default.

error_code menunjukkan kegagalan penyedia, kapasitas kanal, tenggat, cache, atau perlindungan konkurensi. Item gagal tidak ditagih.

Kesalahan

Endpoint	Arti / tindakan
`400`	Perbaiki nomor, produk, atau kunci; tidak ada biaya yang dicadangkan.
`401`	Periksa kunci, status akun, dan akses realtime; tidak ada biaya yang dicadangkan.
`402`	Saldo tidak cukup; tidak ada item yang dijalankan.
`409`	Ulangi sesuai Retry-After; isi berbeda tidak dapat memakai kunci yang sama.
`429`	Tunggu sesuai Retry-After; tidak ada biaya yang dicadangkan.
`500`	Hasil belum pasti. Ulangi dengan kunci asli dan jangan membuat kunci baru.
`503`	Rute, cache, atau pembatas tidak tersedia; coba lagi nanti.