Versionado y obsolescencia

Dónde vive la versión

La versión es un segmento de ruta, y es el único lugar donde aparece:

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

Hay una única versión activa. Su identidad en el documento OpenAPI es 1.0.0; el segmento de ruta v1 es el que usas como destino. Los cuerpos de respuesta deliberadamente no repiten una versión, así que no hay un segundo campo que mantener sincronizado.

Cómo se clasifican los cambios

Clase	Ejemplos	Efecto sobre ti
Aditivo	Un endpoint nuevo, un campo de solicitud opcional nuevo, un campo de respuesta nuevo, un producto nuevo en el catálogo	Ninguno. Sin subida de versión, sin acción.
De comportamiento	Un valor nuevo dentro de una enumeración existente, como error_code o billing_status; un valor predeterminado cambiado	Normalmente ninguno, pero puede romper la coincidencia exhaustiva.
Incompatible	Eliminar o renombrar un campo, cambiar un tipo, cambiar lo que significa un estado, exigir un encabezado nuevo	Requiere una versión nueva.
Contrato	La documentación se equivocaba sobre lo que hace la API	Ninguno — pero consulta a continuación.

Tolera valores de enumeración desconocidos

Los cambios aditivos incluyen miembros nuevos de enumeraciones existentes. Un cliente que ramifica exhaustivamente según status, error_code o billing_status y lanza una excepción ante un valor no reconocido se romperá con un cambio que, por política, no era incompatible.

Trata un valor desconocido como un caso distinto pero válido: regístralo y recurre al tratamiento genérico para esa clase de resultado. El valor predeterminado más seguro para un error_code desconocido es el que esta documentación asigna a internal_error — el resultado es incierto, así que reintenta con la misma Idempotency-Key.

Cuando cambia la documentación

La documentación se corrige en el mismo lugar cuando el comportamiento de la API estaba mal descrito. Ese es un cambio de documentación, no un cambio de contrato: la API no se movió, la descripción sí. Como una corrección es justo el suceso que no puedes ver en una entrada de registro de cambios del tipo «nada cambió», las correcciones se enumeran explícitamente en el registro de cambios.

Si una corrección cambia algo sobre lo que habías construido, aparece allí como una nota en lugar de una edición silenciosa.

Política de obsolescencia

Cuando una operación queda obsoleta, se marca deprecated: true en el documento OpenAPI y este sitio documenta el reemplazo. La operación sigue funcionando durante el periodo de aviso, y el periodo de aviso se indica donde se anuncia la obsolescencia.

Una obsolescencia nunca coincide con la versión en que se introduce su reemplazo. Ambas están activas a la vez, así que puedes migrar según tu propio calendario y no durante un incidente.

La única obsolescencia actual

POST /v1/realtime/detect se mantiene para clientes de prelanzamiento y está marcado como obsoleto en el contrato. Las integraciones nuevas deberían usar los endpoints específicos de cada serie.

Es un cambio de nombre, no un rediseño — el cuerpo de la solicitud y la respuesta tienen la misma forma:

	Heredado	Actual
Endpoint	POST /v1/realtime/detect	POST /v1/realtime/check/phone o POST /v1/realtime/check/email
Serie	Implícita en los productos que envías	Explícita en la ruta, y debe coincidir con ellos
Campo de productos	products (alias)	product_ids
Idempotency-Key	Obligatorio	Obligatorio

Migrar es un cambio de dos líneas:

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

Enviar product_ids y products a la vez en una misma solicitud se rechaza como 400 invalid_realtime_request, así que los dos no deben mezclarse durante un despliegue por etapas.

No se publica fecha de retirada

El contrato marca el endpoint como obsoleto, pero todavía no incluye una fecha de retirada, así que esta documentación no puede indicarla. Migra ahora — el cambio es una ruta y un nombre de campo, y no hay comportamiento que volver a probar.

Siguiente

• OpenAPI — el contrato legible por máquina, incluida la marca deprecated
• Registro de cambios — qué cambió y cuándo