Versionamento e Descontinuação

Onde a versão fica

A versão é um segmento de caminho, e é o único lugar onde ela aparece:

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

Há uma única versão ativa. Sua identidade no documento OpenAPI é 1.0.0; o segmento de caminho v1 é o que você usa como alvo. Os corpos de resposta deliberadamente não repetem uma versão, então não há um segundo campo para manter em sincronia.

Como as mudanças são classificadas

Classe	Exemplos	Efeito para você
Aditiva	Um novo endpoint, um novo campo de requisição opcional, um novo campo de resposta, um novo produto no catálogo	Nenhum. Sem incremento de versão, sem ação.
Comportamental	Um novo valor dentro de um enum existente, como error_code ou billing_status; um padrão alterado	Normalmente nenhum, mas pode quebrar a correspondência exaustiva.
Incompatível	Remover ou renomear um campo, alterar um tipo, alterar o significado de um status, exigir um novo cabeçalho	Exige uma nova versão.
Contrato	A documentação estava errada sobre o que a API faz	Nenhum — mas veja abaixo.

Tolere valores de enum desconhecidos

Mudanças aditivas incluem novos membros de enums existentes. Um cliente que faz uma verificação exaustiva sobre status, error_code ou billing_status e lança um erro em um valor não reconhecido vai quebrar em uma mudança que, por política, não era incompatível.

Trate um valor desconhecido como um caso distinto, porém válido: registre-o no log e recorra ao tratamento genérico para essa classe de desfecho. O padrão mais seguro para um error_code desconhecido é o que esta documentação atribui a internal_error — o desfecho é incerto, então repita com a mesma Idempotency-Key.

Quando a documentação muda

A documentação é corrigida no local quando o comportamento da API foi descrito incorretamente. Isso é uma mudança de documentação, não de contrato: a API não mudou, a descrição sim. Como uma correção é exatamente o evento que você não consegue ver em uma entrada de changelog do tipo “nada mudou”, as correções são listadas explicitamente no changelog.

Se uma correção altera algo que você tinha usado como base, ela aparece lá como uma nota, e não como uma edição silenciosa.

Política de descontinuação

Quando uma operação é descontinuada, ela é marcada com deprecated: true no documento OpenAPI, e este site documenta a substituta. A operação continua funcionando durante o período de aviso, e o período de aviso é informado onde a descontinuação é anunciada.

Uma descontinuação nunca acontece na mesma versão que a introdução de sua substituta. Ambas ficam ativas ao mesmo tempo, para que você migre no seu próprio ritmo, e não durante um incidente.

A única descontinuação atual

POST /v1/realtime/detect é mantido para clientes de pré-lançamento e está marcado como descontinuado no contrato. Novas integrações devem usar os endpoints específicos de cada série.

É uma renomeação, não um redesenho — o corpo da requisição e a resposta têm o mesmo formato:

	Legado	Atual
Endpoint	POST /v1/realtime/detect	POST /v1/realtime/check/phone ou POST /v1/realtime/check/email
Série	Implícita pelos produtos que você envia	Explícita no caminho, e precisa corresponder a eles
Campo de produtos	products (alias)	product_ids
Idempotency-Key	Obrigatório	Obrigatório

Migrar exige alterar duas linhas:

# 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 e products juntos em uma única requisição é rejeitado como 400 invalid_realtime_request, então os dois não podem ser misturados durante uma implantação gradual.

Nenhuma data de encerramento é publicada

O contrato marca o endpoint como descontinuado, mas ainda não traz uma data de remoção, então esta documentação não pode informar uma. Migre agora — a mudança é um caminho e um nome de campo, e não há comportamento a testar de novo.

A seguir

• OpenAPI — o contrato legível por máquina, incluindo o sinalizador deprecated
• Changelog — o que mudou, e quando