Versi & Penghentian

Di mana versi berada

Versi adalah segmen jalur, dan itu satu-satunya tempat versi muncul:

https://api.zelnum.com/api/v1

Hanya ada satu versi aktif. Identitasnya dalam dokumen OpenAPI adalah 1.0.0; segmen jalur v1 adalah yang Anda tuju. Body respons sengaja tidak mengulang versi, jadi tidak ada field kedua yang perlu disinkronkan.

Bagaimana perubahan diklasifikasikan

Kelas	Contoh	Dampak bagi Anda
Aditif	Endpoint baru, field permintaan opsional baru, field respons baru, produk baru di katalog	Tidak ada. Tidak ada kenaikan versi, tidak ada tindakan.
Perilaku	Nilai baru di dalam enum yang sudah ada seperti error_code atau billing_status; nilai default yang berubah	Biasanya tidak ada, tetapi dapat merusak pencocokan ekshaustif.
Breaking	Menghapus atau mengganti nama field, mengubah tipe, mengubah makna sebuah status, mewajibkan header baru	Memerlukan versi baru.
Kontrak	Dokumentasi keliru tentang apa yang dilakukan API	Tidak ada — tetapi lihat di bawah.

Toleransi terhadap nilai enum yang tidak dikenal

Perubahan aditif mencakup anggota baru pada enum yang sudah ada. Klien yang melakukan percabangan ekshaustif atas status, error_code atau billing_status dan gagal pada nilai yang tidak dikenali akan rusak akibat perubahan yang secara kebijakan tidak merusak.

Perlakukan nilai yang tidak dikenal sebagai kasus tersendiri yang tetap valid: catat di log, lalu jatuh ke penanganan generik untuk kelas hasil tersebut. Default teraman untuk error_code yang tidak dikenal adalah yang diberikan dokumentasi ini untuk internal_error — hasilnya tidak pasti, jadi coba lagi dengan Idempotency-Key yang sama.

Saat dokumentasi berubah

Dokumentasi dikoreksi di tempat ketika perilaku API dijelaskan secara keliru. Itu adalah perubahan dokumentasi, bukan perubahan kontrak: API tidak berubah, deskripsinya yang berubah. Karena koreksi justru merupakan peristiwa yang tidak dapat Anda lihat pada entri changelog berbentuk “tidak ada yang berubah”, koreksi dicantumkan secara eksplisit di Catatan Perubahan.

Jika sebuah koreksi mengubah sesuatu yang menjadi dasar integrasi Anda, koreksi itu muncul di sana sebagai catatan, bukan sebagai suntingan diam-diam.

Kebijakan penghentian

Saat sebuah operasi dihentikan penggunaannya, operasi itu ditandai deprecated: true di dokumen OpenAPI, dan situs ini mendokumentasikan penggantinya. Operasi tersebut tetap berfungsi selama masa pemberitahuan, dan masa pemberitahuan dinyatakan di tempat penghentian diumumkan.

Penghentian tidak pernah berada pada rilis yang sama dengan pengenalan penggantinya. Keduanya aktif bersamaan, sehingga Anda dapat bermigrasi sesuai jadwal Anda sendiri, bukan saat terjadi insiden.

Satu-satunya penghentian saat ini

POST /v1/realtime/detect dipertahankan untuk klien pra-rilis dan ditandai deprecated dalam kontrak. Integrasi baru sebaiknya menggunakan endpoint khusus seri.

Ini penggantian nama, bukan perancangan ulang — body permintaan dan responsnya berbentuk sama:

	Lama	Saat ini
Endpoint	POST /v1/realtime/detect	POST /v1/realtime/check/phone atau POST /v1/realtime/check/email
Seri	Tersirat dari produk yang Anda kirim	Eksplisit di jalur, dan harus cocok dengan produknya
Field produk	products (alias)	product_ids
Idempotency-Key	Wajib	Wajib

Migrasi hanya perlu perubahan dua baris:

# Before
curl -X POST "https://api.zelnum.com/api/v1/realtime/detect" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"+8613800138000","products":[47]}'

# After — the series moves into the path and the field is renamed
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","product_ids":[47]}'

Mengirim product_ids dan products sekaligus dalam satu permintaan ditolak sebagai 400 invalid_realtime_request, jadi keduanya tidak boleh dicampur selama peluncuran bertahap.

Tidak ada tanggal penghentian yang diterbitkan

Kontrak menandai endpoint ini deprecated tetapi belum mencantumkan tanggal penghapusan, sehingga dokumentasi ini tidak dapat menyebutkannya. Bermigrasilah sekarang — perubahannya hanya jalur dan nama field, dan tidak ada perilaku yang perlu diuji ulang.

Berikutnya

• OpenAPI — kontrak yang dapat dibaca mesin, termasuk flag deprecated
• Catatan Perubahan — apa yang berubah, dan kapan