Pular para o conteúdo principal
POST
Existência de Destinatário em Lote (Sem Instância)

Introdução

Este endpoint é similar à Verificação de Número (Sem Instância), mas permite verificar até 100 números em uma única requisição, sem exigir nenhuma instância conectada. Assim como na versão single, a consulta é atendida por uma infraestrutura dedicada da Zapster com cache persistente.
Endpoint público. No momento, este endpoint pode ser usado sem autenticação. Por ser público, as requisições sem token ficam sujeitas a limites de uso gratuito, mais restritos e que podem mudar a qualquer momento. Com o token da sua conta, valem os limites da sua conta. Ao ultrapassar o limite, a resposta é 429 com o código rate_limited e o header Retry-After indica quando tentar de novo.
Para os detalhes sobre formato de número, nono dígito e a URL da foto de perfil, consulte os Pontos de Atenção do endpoint single.

Como funciona?

A resposta é sempre uma lista de objetos, na mesma ordem dos números enviados no corpo da requisição — um objeto por número consultado. Cada número é avaliado quanto à sua existência no WhatsApp e se corresponde a uma conta WhatsApp Business. Números inválidos ou não encontrados retornam um objeto de erro no lugar dos dados do destinatário.
Exemplo de Resposta

Três formatos de item na resposta

Cada item da lista assume um de três formatos, dependendo do resultado:
Um número com formato inválido (fora do E.164) não chega a ser consultado — por isso o item de resposta não tem o campo exists, só original e error. Já um número não encontrado foi de fato consultado e simplesmente não existe no WhatsApp, por isso vem com exists: false.

Rate limit conta por destinatário

Diferente da maioria dos endpoints da API — que contam o rate limit por requisição HTTP — este endpoint conta por destinatário dentro do lote. Um POST com 100 números válidos consome 100 unidades da sua cota, não 1. Números com formato inválido não consomem cota, já que nem chegam a ser verificados no WhatsApp. Um lote com mais números válidos do que o limite inteiro da sua janela é recusado com 429 sem consumir a cota. Nesse caso, divida a lista em lotes menores, de no máximo o valor de X-RateLimit-Limit. Os valores do limite podem mudar a qualquer momento. Ao ultrapassar o limite, a API responde 429 com o código rate_limited e os headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset e Retry-After.

Autorizações

Authorization
string
header
obrigatório

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Corpo

application/json
recipients
string[]
obrigatório

Números em formato internacional (E.164), com ou sem + inicial. Limite de 100 por requisição.

Required array length: 1 - 100 elements
Exemplo:

Resposta

Success

original
string
obrigatório

Número exatamente como foi enviado na lista de consulta, sem alterações.

Exemplo:

"5511999999999"

exists
boolean

true se o número existir e false se não foi encontrado. Ausente quando original está fora do formato internacional — nesse caso a resposta traz apenas original e error.

error
object

Presente quando o número não é encontrado ou está fora do formato internacional.

id
string

ID ou número do destinatário.

is_business
boolean

Define se o recipient informado é um perfil do tipo business ou normal.

lid
string

Identificador LID do destinatário no WhatsApp.

name
string

Nome da conta comercial (WhatsApp Business), como aparece no WhatsApp. Presente apenas quando is_business é true e a conta tem um nome; contas pessoais nunca trazem esse campo.

Exemplo:

"Padaria Pão Quente"

profile_picture
string<uri>

Foto de perfil do destinatário. Sempre presente — é uma URL estável que aponta para o endpoint de foto de perfil (GET /wa/recipients/{recipient}/pp), então pode ser usada diretamente em um <img src> e armazenada como referência. Quando o número não tem foto disponível, esse endpoint responde com um placeholder configurável.

Exemplo:

"https://api.zapsterapi.com/v1/wa/recipients/5511999999999/pp"