Consulta unitária em tempo real

POST/v1/realtime/check/phone

Consulta síncrona de um número. Uma solicitação pode selecionar vários produtos em tempo real por ID; não use slugs de produtos em lote.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`identifier`	string	Sim	Um número E.164, por exemplo +8613800138000.
`country`	string	Não	Opcional para E.164 completo; um número nacional exige o código ISO de país correspondente. — Códigos de país
`product_ids`	array	Sim	Lista de 1 a 10 IDs de produtos em tempo real.

Escolher os produtos a verificar

Os IDs de produto não se adivinham: leia-os em GET /v1/products e use o id da entrada cujo mode seja realtime. Produtos em lote são endereçados por slug, então um slug nunca funciona neste endpoint. A página de produtos mostra os IDs em tempo real com o prefixo # exatamente por isso.

Lista de Produtos

Uma chamada verifica um número contra até dez produtos em tempo real. Você recebe um único request_id, uma entrada por produto em results e cada uma é cobrada separadamente, então status pode voltar como partial_succeeded. Mais de dez IDs em uma chamada é rejeitado; o console aplica o mesmo limite.

Exemplo de Resposta

{
  "request_id": "8c1e4f91-7bd8-4d7e-a3ae-3d7e5b0c6c11",
  "identifier": "+8613800138000",
  "series": "phone",
  "status": "succeeded",
  "request_status": "completed",
  "replayed": false,
  "total_reserved": 0.004000,
  "total_charged": 0.004000,
  "total_refunded": 0.000000,
  "charged_amount": 0.004000,
  "refunded_amount": 0.000000,
  "results": [
    {
      "product_id": 47,
      "product": "wavalid-realtime",
      "result": "valid",
      "cached": false,
      "billing_status": "charged",
      "charged_amount": 0.002000,
      "refunded_amount": 0.000000,
      "checked_at": "2026-09-05T10:00:00Z",
      "error_code": null
    },
    {
      "product_id": 50,
      "product": "tgValid-rt",
      "result": "invalid",
      "cached": false,
      "billing_status": "charged",
      "charged_amount": 0.002000,
      "refunded_amount": 0.000000,
      "checked_at": "2026-09-05T10:00:01Z",
      "error_code": null
    }
  ]
}

Campos da resposta

Campo	Tipo	Descrição
`request_id`	string (UUID)	UUID que identifica este envio. Informe-o em solicitações de suporte.
`identifier`	string	O identificador verificado, devolvido na resposta.
`series`	string	`phone` ou `email`.
`status`	string	`succeeded`, `partial_succeeded` ou `failed` — derivado de quantos resultados foram cobrados.
`request_status`	string	Estado interno do ciclo de vida da requisição.
`total_reserved`	number	Valor reservado antes da execução das verificações.
`total_charged`	number	Total cobrado em todos os produtos do combo.
`total_refunded`	number	Total reembolsado por itens que não puderam ser resolvidos.
`charged_amount`	number	Cobrança líquida. Sempre igual a `total_charged`.
`refunded_amount`	number	Reembolso líquido. Sempre igual a `total_refunded`.
`replayed`	boolean	`true` quando uma repetição de Idempotency-Key retornou um resultado armazenado.
`results`	array	Uma entrada por produto solicitado, na ordem em que os produtos foram solicitados.

`results[]`

Campo	Tipo	Descrição
`product_id`	integer	ID do produto em tempo real no catálogo.
`product`	string	Slug do produto para o qual o ID é resolvido.
`result`	string	`valid`, `invalid` ou `unknown` — indica se o identificador está registrado.
`cached`	boolean	`true` quando o veredito veio do cache. Um acerto de cache ainda é cobrado.
`billing_status`	string	`charged` ou `refunded`.
`charged_amount`	number	Valor cobrado por este produto.
`refunded_amount`	number	Valor reembolsado por este produto.
`checked_at`	string (ISO 8601)	Quando o veredito foi produzido, em UTC.
`error_code`	string \| null	Motivo pelo qual o item não pôde ser resolvido, ou `null` quando foi bem-sucedido.

Exemplo de cURL

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","country":"CN","product_ids":[47,50]}'

Cobrança e semântica

Cada produto usa o preço por consulta fixado para a solicitação, inclusive com cache. valid e invalid são cobrados; unknown, timeout e itens ocupados são reembolsados.

Um combo parcialmente bem-sucedido retorna HTTP 200 com status=partial_succeeded; falha total usa status=failed. Verifique billing_status e error_code de cada item.

Idempotency-Key tem até 191 bytes e é limitado por usuário. Após timeout ou erro 500, repita o conteúdo original com a chave original. Os resultados são mantidos por 30 dias por padrão.

error_code identifica falhas do provedor, capacidade, prazo, cache ou proteção de concorrência. Itens com falha não são cobrados.

Erro

Endpoints	Significado / ação
`400`	Corrija o número, os produtos ou a chave; não houve pré-cobrança.
`401`	Verifique a chave, a conta e o acesso em tempo real; não houve pré-cobrança.
`402`	Saldo insuficiente; nenhum item do combo é executado.
`409`	Repita após Retry-After; um conteúdo diferente não pode reutilizar a chave.
`429`	Aguarde o Retry-After; não houve pré-cobrança.
`500`	O resultado é incerto. Repita com a chave original e não envie uma nova chave.
`503`	Rota, cache ou limitador indisponível; tente novamente mais tarde.