バージョニングと非推奨化

バージョンが存在する場所

バージョンはパスセグメントであり、それが現れる唯一の場所です：

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

稼働中のバージョンは1つです。OpenAPI ドキュメントにおけるその識別子は 1.0.0 で、ターゲットとするのはパスセグメント v1 です。レスポンスボディは意図的にバージョンを繰り返さないため、同期させる2つ目のフィールドはありません。

変更の分類

分類	例	あなたへの影響
追加的	新しいエンドポイント、新しい任意のリクエストフィールド、新しいレスポンスフィールド、カタログの新しいプロダクト	なし。バージョンアップも対応も不要です。
挙動的	error_code や billing_status など既存の enum 内の新しい値、またはデフォルト値の変更	通常はなしですが、網羅的な分岐を壊す可能性があります。
破壊的	フィールドの削除や名前変更、型の変更、ステータスの意味の変更、新しいヘッダーの必須化	新しいバージョンが必要です。
コントラクト	API の動作についてドキュメントが誤っていた	なし — ただし以下を参照してください。

未知の enum 値を許容する

追加的な変更には、既存の enum に新しいメンバーが加わる場合が含まれます。status、error_code、billing_status を網羅的に分岐し、認識できない値で例外を投げるクライアントは、方針上は非破壊的だった変更で壊れてしまいます。

未知の値は、別個だが有効なケースとして扱ってください。ログに記録し、その種の結果に対する汎用的な処理にフォールバックします。未知の error_code に対する最も安全な既定は、このドキュメントが internal_error に与えているものです — 結果が不確実なので、同じ Idempotency-Key で再試行してください。

ドキュメントが変更されるとき

API の挙動が誤って記述されていた場合、ドキュメントはその場で修正されます。これはドキュメントの変更であり、コントラクトの変更ではありません。API は動いておらず、記述が動いたのです。「変更なし」という形式のチェンジログ項目では見ることのできない出来事こそが訂正であるため、訂正は チェンジログ に明示的に記載されます。

訂正が、あなたが依存して構築したものを変える場合、それは黙った編集ではなく注記としてそこに現れます。

非推奨ポリシー

オペレーションが非推奨になると、OpenAPI ドキュメントで deprecated: true が付けられ、このサイトが代替を説明します。そのオペレーションは告知期間中は動作し続け、告知期間は非推奨が告知された場所に記載されます。

非推奨化が、その代替の導入と同じリリースになることはありません。両方が同時に稼働するため、障害対応の最中ではなく自分のスケジュールで移行できます。

現在の唯一の非推奨

POST /v1/realtime/detect はリリース前のクライアント向けに残されており、コントラクトでは非推奨としてマークされています。新しい統合では、シリーズ固有のエンドポイントを使用してください。

これは再設計ではなく名前変更です — リクエストボディとレスポンスは同じ形です：

	レガシー	現行
エンドポイント	POST /v1/realtime/detect	POST /v1/realtime/check/phone または POST /v1/realtime/check/email
シリーズ	送信するプロダクトによって暗黙に決まる	パスで明示され、送信するプロダクトと一致している必要があります
プロダクトのフィールド	products（別名）	product_ids
Idempotency-Key	必須	必須

移行はほんの数行の変更です：

# 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]}'

同じリクエストで product_ids と products の両方を送信すると 400 invalid_realtime_request として拒否されるため、段階的なロールアウト中に両者を混在させてはいけません。

提供終了日は公開されていない

コントラクトはこのエンドポイントを非推奨としてマークしていますが、まだ削除日を含んでいないため、このドキュメントでは記載できません。今すぐ移行してください — 変更はパスとフィールド名だけで、再テストすべき挙動はありません。

次のページ

• OpenAPI — deprecated フラグを含む機械可読なコントラクト
• チェンジログ — 何が、いつ変更されたか