Dokumentasi API — Yuanext Enterprise Inquiry Gateway

Pengantar Protokol

Yuanext Gateway menyediakan antarmuka REST API berlatensi sangat rendah untuk memeriksa nama terdaftar pemilik rekening bank umum, bank syariah, bank digital, dan akun dompet digital di Indonesia.

Base URL Produksi:

https://api.yuanext.com

Autentikasi (API Key)

Setiap permintaan ke endpoint dilindungi wajib menyertakan API Key resmi berawalan prefix shz_live_. Anda dapat menyematkan kunci melalui header HTTP (direkomendasikan) atau parameter URL.

Header HTTP (Rekomendasi)

Sertakan pada setiap outbound request header

X-API-Key: shz_live_xxxxxxxxxxxxxxxx

Query Parameter (Alternatif)

Bisa digunakan jika lingkungan klien tidak mendukung custom header

?api_key=shz_live_xxxxxxxxxxxxxxxx

Proteksi Idempotensi (Zero-Leak Retry)

Fitur Unggulan

Ketika klien mengalami koneksi timeout di tengah jalan dan melakukan retry otomatis, header X-Idempotency-Key menjamin bahwa permintaan tidak akan memotong kuota harian dua kali dan tidak menembak upstream berulang.

Format Header:

X-Idempotency-Key: <UUID-v4-unik>

Server menyimpan hasil respons di kluster memori berkecepatan tinggi selama 120 detik.
Respons dengan kunci identik akan menghasilkan header X-Idempotency-Status: HIT dan waktu pemrosesan 0ms.

Rate Limiting & Kuota Header

Setiap respons HTTP dari gateway menyertakan informasi kuota dan alokasi kecepatan transaksi terkini:

Header Response	Tipe	Deskripsi
`X-RateLimit-Limit`	Integer	Total batas kuota harian paket Anda
`X-RateLimit-Remaining`	Integer	Sisa alokasi kuota harian hari ini
`X-RateLimit-Reset`	Timestamp	Waktu Unix Epoch saat kuota harian diperbarui
`X-RateLimit-RPM-Limit`	Integer	Batas kecepatan permintaan per menit

GET

/api/v1/inquiry

Melakukan pemeriksaan nama resmi rekening bank atau dompet digital secara real-time.

Query Parameters

Parameter	Wajib	Tipe	Contoh & Keterangan
`code`	Ya	String	`dana` atau kode BI `014` atau slug bank `bca`
`accountNumber`	Ya	String	Nomor rekening bank atau nomor HP e-wallet (`08123456789`)
`pretty`	Tidak	Boolean	Set `true` untuk format JSON berindentasi rapi

Contoh Pemanggilan (Code Samples)

Contoh Respons Sukses (HTTP 200)

{
  "success": true,
  "message": "ok",
  "data": {
    "account_name": "BUDI SANTOSO",
    "account_number": "081234567890",
    "account_type": "wallet_account",
    "bank_code": "dana",
    "bank_name": "DANA"
  },
  "response_time_seconds": 0.412
}

Katalog Kode Bank & E-Wallet

Gunakan salah satu dari kode di bawah untuk parameter code:

E-Wallet

DANAdana

GoPaygopay

OVOovo

ShopeePayshopeepay

LinkAjalinkaja

Bank Nasional (Kode BI / Slug)

BCA014 / bca

BRI002 / bri

Mandiri008 / mandiri

BNI009 / bni

BSI451 / bsi

SeaBank535 / seabank

Kamus Kode Error

Daftar error_code resmi yang dihasilkan gateway:

HTTP	Kode Error	Penjelasan Tindakan Klien
400	`MISSING_PARAMS`	Parameter wajib tidak dikirim atau kosong.
401	`INVALID_API_KEY`	API key salah, tidak aktif, atau tidak terdaftar.
403	`IP_NOT_ALLOWED`	IP server Anda belum dimasukkan ke whitelist API key.
404	`NOT_FOUND`	Nomor rekening atau nomor HP tidak terdaftar pada vendor tujuan.
429	`QUOTA_EXCEEDED`	Kuota harian akun Anda telah habis untuk hari ini.
429	`RATE_LIMIT_EXCEEDED`	Batas frekuensi RPM terlampaui. Tunggu beberapa detik sebelum retry.

Dokumentasi API Pengembang