OpenAPI

Setiap endpoint dalam dokumentasi ini juga diterbitkan sebagai dokumen OpenAPI 3.1 yang dapat dibaca mesin, sehingga Anda dapat menggerakkan perkakas dari kontrak alih-alih menulis ulang tabel secara manual.

Salin	URL	Catatan
Dokumentasi	https://docs.zelnum.com/openapi.yaml	Stabil, di domain ini. Kanonis bagi pembaca situs ini.
Platform	https://app.zelnum.com/docs/openapi.yaml	Hulu. Salinan dokumentasi adalah cermin yang identik byte dengannya.

Kedua berkas adalah dokumen yang sama. Cermin ini ada agar spesifikasi berada di host yang sedang Anda baca, di jalur yang dapat ditemukan perkakas.

Isi dokumen

Bagian	Jumlah	Isi
Servers	1	https://api.zelnum.com/api/v1
Paths	10	Sembilan endpoint yang didokumentasikan ditambah alias realtime lama
Tags	3	Common, Realtime, Bulk — pembagian yang sama seperti yang dipakai navigasi
Schemas	9	Body permintaan dan respons, termasuk envelope error
Skema keamanan	2	X-API-Key dan Authorization: Bearer

Detail tingkat operasi ada di dalam dokumen itu sendiri: header yang wajib, minItems/maxItems pada array, enum untuk series, mode, status dan billing_status, serta flag deprecated: true pada POST /v1/realtime/detect.

Impor ke perkakas API

Postman — Import → File → openapi.yaml. Postman membuat collection dengan variabel lingkungan untuk base URL; setel kunci Anda sebagai header X-API-Key tingkat collection agar setiap permintaan mewarisinya.

Insomnia — Create → Import From → File, lalu tambahkan X-API-Key sebagai header collection.

Generator Bruno / HTTPie / curl — semuanya mengonsumsi OpenAPI 3.1 secara langsung:

curl -fsSL https://docs.zelnum.com/openapi.yaml -o zelnum.yaml

Hasilkan klien bertipe

Tidak ada SDK pihak pertama — API ini adalah JSON biasa melalui HTTPS, dan klien yang dihasilkan biasanya lebih cocok daripada klien yang ditulis tangan, karena klien tersebut mengikuti konvensi bahasa Anda.

# Pick your generator: python, typescript-fetch, php, go, java, csharp, ruby, …
npx @openapitools/openapi-generator-cli generate \
  -i https://docs.zelnum.com/openapi.yaml \
  -g python \
  -o ./zelnum-client

Klien yang dihasilkan membaca base URL dan skema keamanan dari dokumen, sehingga satu-satunya hal yang Anda sediakan saat runtime adalah kunci API Anda.

Realtime memerlukan header yang tidak dapat diciptakan generator

Idempotency-Key adalah header wajib pada endpoint realtime, dan klien yang dihasilkan akan menampilkannya sebagai parameter metode yang harus Anda setel. Nilainya harus unik per pengiriman — lihat Idempotensi & Percobaan Ulang.

Menjaga cermin tetap akurat

Cermin ini mengikuti hulu; cermin tidak pernah disunting di sini. Karena perbedaan antara kontrak yang diterbitkan dan dokumentasinya adalah kegagalan yang ingin dicegah halaman ini, salinannya diperiksa terhadap hulu, bukan sekadar dipercaya:

npm run openapi:check   # fetch upstream and fail if the bytes differ
npm run openapi:sync    # re-vendor, printing which operations changed

openapi:check memerlukan akses jaringan dan sengaja tidak menjadi bagian dari build situs — proses deploy tidak boleh gagal hanya karena host platform mengalami gangguan sesaat. Yang ditegakkan oleh build adalah separuh luring dari invarian tersebut: setiap endpoint yang dijelaskan dokumentasi ini harus ada di dokumen yang di-vendor, sehingga sebuah halaman tidak dapat mendokumentasikan operasi yang tidak dimiliki kontrak.

Berikutnya

• Versi & Penghentian — apa arti flag deprecated pada endpoint lama bagi Anda
• Format Respons — envelope yang dipakai bersama oleh setiap endpoint