Changelog

Esta página registra mudanças na API e nesta documentação. As entradas começam em 2026-09-19: tudo o que mudou antes de esta página existir não é listado retroativamente, então trate uma entrada ausente como “não registrado” em vez de “não alterado”.

Como ler

Tipo	Significado
API	O serviço mudou — um endpoint, um campo, um limite.
Contrato	O documento OpenAPI publicado mudou.
Docs	A documentação mudou. A API permaneceu igual.
Correção	A documentação vinha descrevendo a API incorretamente.

As entradas de Correção são destacadas separadamente de propósito. Elas descrevem uma mudança no que você leria, não no que a API faz — então nada na sua integração quebra, mas qualquer coisa que você construiu a partir da descrição antiga pode estar errada.

2026-10-27 — Referência de códigos de país

Docs · Adicionado

Uma página de Códigos de país pesquisável, listando todos os códigos ISO 3166-1 alfa-2 oficialmente atribuídos, vinculada a partir dos endpoints que aceitam o campo country.

2026-09-19 — Documentação reestruturada, contrato publicado

Docs · Adicionado

Uma seção Referência: OpenAPI, Versionamento e descontinuação, Status e suporte, Segurança e Glossário.
O documento OpenAPI 3.1 agora é publicado em https://docs.zelnum.com/openapi.yaml, um espelho idêntico byte a byte da cópia da plataforma, importável no Postman, no Insomnia e em geradores de cliente.
Exemplos de cliente em Python, Node.js, PHP e Go para ambos os modos de detecção, junto com os exemplos cURL existentes. A navegação vinha prometendo exemplos de SDK enquanto só existia cURL.
Tabelas de resposta campo a campo para os endpoints de verificação em tempo real, envio em lote, status da tarefa e resultado.
Duas novas proteções de build: o build agora falha diante de uma tabela irregular em qualquer idioma, e reconcilia todos os endpoints citados nesta documentação com o documento OpenAPI vendorizado nas duas direções — um endpoint documentado que o contrato não tem, e um caminho do contrato que ninguém documenta, são ambos falhas.

Contrato · Adicionado

O próprio documento OpenAPI: 10 caminhos, 9 esquemas, e deprecated: true no POST /v1/realtime/detect legado.

Docs · Correções

O country em lote foi documentado como obrigatório para todo envio. Ele é obrigatório para produtos de telefone e deve ser omitido para produtos de e-mail. Como estava escrito, os nove produtos de e-mail em lote eram impossíveis de enviar — toda requisição teria falhado na validação.
A regra de volume em lote estava errada. Ela dizia “1,000 a 2,000,000 números por requisição”. A regra real é o próprio mínimo do produto selecionado — 500, 1,000 ou 2,000 — até o máximo da plataforma, de 2,000,000. O número antigo excluía onze produtos cujo mínimo é 500.
O catálogo de erros listava quatro códigos que a API nunca retorna. A página de documentação legada da plataforma nomeia not_found, result_not_ready, result_expired e validation_failed; a implementação não emite nenhum deles, e essas respostas não trazem nenhum campo code. A tabela agora lista os 22 códigos que a API realmente retorna, e uma segunda tabela documenta as condições sem código — com um aviso para quem portou esses quatro ramos.
Os exemplos de resposta não traziam campos que a API realmente retorna. series, charged_amount e refunded_amount nas respostas de tempo real; idempotent_replay e recovery_pending nos envios em lote; e dez contadores de progresso da tarefa, incluindo submitted, prefiltered, deduped, stage, last_progress_at e failure_message.
Os limites de requisições nomeavam o endpoint errado. A linha de tempo real dizia POST /v1/realtime/check/phone; o limite se aplica a POST /v1/realtime/check/{series}, incluindo e-mail.
Os cabeçalhos de resposta foram descritos incorretamente. A página de limites de requisições dava a entender que o conjunto completo de cabeçalhos aparece em toda resposta. Não é o caso: o bucket de tempo real informa apenas X-RateLimit-Remaining em caso de sucesso e nunca X-RateLimit-Limit, e X-RateLimit-Reset aparece apenas em um 429 geral ou de detecção. A página agora diz qual cabeçalho aparece onde.
O modelo de chaves foi descrito incorretamente. A página de segurança afirmava que uma conta mantém uma chave por vez. Uma conta pode manter várias chaves ativas, e o Console as cria, regenera e exclui individualmente — então uma rotação gradual sem tempo de inatividade é possível, e regenerar no mesmo lugar é a variante que não tem sobreposição. GET /v1/api-key informa a chave ativa mais recente, e não um inventário, e seu last_used é gravado no máximo uma vez a cada cinco minutos.
IDs versus slugs foram descritos incorretamente. O glossário dizia que um ID ou slug trocado é rejeitado como product_mode_not_supported. Nos endpoints de tempo real, product_ids é validado como um array de inteiros, então um slug é rejeitado mais cedo como 400 invalid_realtime_request; 422 product_mode_not_supported é a resposta do endpoint em lote a um produto de tempo real.
A página de formato da resposta contradizia a página de saldo quanto à moeda. Uma dizia “a moeda de cobrança da conta”, a outra dizia USD. Ambas agora dizem USD, que é o que o contrato e o endpoint de saldo dizem.
Uma unidade de preço foi afirmada sem fonte. O modo em lote era descrito como “cobrado por 10,000 verificações”. O catálogo não expõe preços, então a afirmação foi removida em vez de mantida.
Duas correções só haviam chegado às páginas escritas à mão. A afirmação sobre a moeda e a de “por 10,000 verificações” foram corrigidas nas páginas em inglês e em chinês simplificado, mas a tabela de strings que gera os outros sete idiomas ainda as carregava, então sete idiomas continuaram publicando ambas. Elas também foram corrigidas na tabela.
/examples/ era uma página diferente em cada idioma. A página em inglês era um pequeno hub de navegação, enquanto os outros oito renderizavam um passo a passo em lote de cinco etapas. O inglês agora corresponde ao passo a passo, então todos os nove idiomas têm o mesmo conteúdo.

Docs · Ajustes

As tabelas de parâmetros perdiam silenciosamente sua coluna de descrição em todos os sete idiomas gerados. Um helper compartilhado emitia um cabeçalho de três colunas para linhas de quatro células, e o GFM descarta toda célula além da largura do cabeçalho — então, em espanhol, por exemplo, o valor “Required” era renderizado sob o título “Description” e a própria descrição desaparecia, em três páginas de sete idiomas. O helper agora recebe um formato de colunas explícito e falha o build diante de uma linha irregular, e a proteção do estágio de dist verifica de novo, de forma independente, cada tabela renderizada em cada idioma.
Os idiomas gerados renderizavam em inglês os cabeçalhos de coluna da tabela de produtos, sua nota e sua linha de sincronização, e as crases da nota chegavam ao navegador como caracteres literais. O texto do componente agora vem da tabela de strings traduzida, e uma tradução ausente falha o build em vez de usar um fallback.

Assinar as mudanças

Ainda não há feed. Enquanto não houver, o sinal confiável é o contrato:

npm run openapi:check

em uma tarefa agendada — ela sai com código diferente de zero no momento em que o documento publicado difere da cópia que você vendorizou. Consulte OpenAPI para as duas URLs.