Recurso em beta: pode mudar. Eles estão marcados (não confirmado) na tabela. Não existe vínculo entre a ProxyBox e a Z-API.
Por que migrar, e quando não?
Quem usa a Z-API ganha, na ProxyBox, o IP brasileiro de provedor dedicado por número (no plano com IP), a chave por instância sem chave global, o modo de consulta de avisos, a aprovação humana e o conector de IA. Em compensação, a Z-API tem uma documentação extensa, muitos recursos (catálogo, canais, comunidades, botão de PIX) e um programa de parceiros maduro que aqui não existem. Veja o comparativo datado em alternativa à Z-API. Se o seu código usa botão de PIX, catálogo ou comunidades, leia a lista do que não existe antes de migrar.
Passo a passo
- Contrate a instância e conecte o número (veja os primeiros passos). Se quiser testar antes sem número, use o sandbox.
- Anote o
sluge a chavepbwa_…da instância. - No seu sistema, troque a base. O resto do código fica.
- Se você recebe avisos, no painel escolha o formato de aviso zapi (veja abaixo) e cadastre o endereço.
- Teste cada rota que o seu sistema usa, em ordem de importância.
- Só então pare a instância na Z-API.
# antes
curl -X POST "https://api.z-api.io/instances/ID/token/TOKEN/send-text" \
-H "Client-Token: SEU_CLIENT_TOKEN" -H "Content-Type: application/json" \
-d '{"phone":"5547999999999","message":"Seu pedido saiu."}'
# depois
curl -X POST "https://proxybox.com.br/api/whatsapp/zapi/instances/atendimento-da-loja/token/pbwa_SUA_CHAVE/send-text" \
-H "Content-Type: application/json" \
-d '{"phone":"5547999999999","message":"Seu pedido saiu."}'
# {"zaapId":"3EB0...","messageId":"3EB0...","id":"3EB0..."}
Os três campos da resposta (zaapId, messageId, id) têm o mesmo valor: o id da mensagem. Não existe um id separado da Z-API.
Quais são os erros?
O formato é {"error": "<motivo HTTP>", "message": "<texto em português>"}, com campos extras quando cabem (code, retryAfter, exists, phone). Sucesso é sempre HTTP 200. Resumo do mapa:
| Situação | HTTP |
|---|---|
| Campo inválido (com o nome do campo da Z-API) | 400 |
| Número sem WhatsApp | 400 com exists: false |
| Sem conexão; trava de contato novo | 409 |
| Ritmo ou limite do dia | 429 |
| Instância pausada; sem permissão; status desligado | 403 |
| Rota ou instância inexistente | 404 |
| Recurso sem equivalente | 404 com code: unsupported |
| Falha temporária | 502 |
O token nunca aparece em mensagem de erro. Se o slug não for o da instância dona do token, a resposta é 404.
Vai trocar de provedor? Rode as suas chamadas no sandbox antes de mudar a URL: é grátis e nada sai para o WhatsApp.
Testar grátisQual é o mapa de rotas de envio?
* = obrigatório. (não confirmado) = método ou caminho não visto na documentação da Z-API.
| Rota Z-API | Equivale a | Observações |
|---|---|---|
POST send-text |
enviar texto | phone*, message*, messageId vira resposta a uma mensagem, delayMessage e delayTyping até 5 s cada (não confirmado) |
POST send-image |
enviar imagem | image* em https ou data:...;base64, caption, viewOnce; editar legenda: 501 |
POST send-document/{extensão} |
enviar documento | fileName, caption; o nome ganha a extensão se faltar |
POST send-audio |
enviar voz | Depende do conversor de áudio da instância; senão 501 |
POST send-video, send-gif |
enviar vídeo | O GIF vai como MP4 |
POST send-sticker |
enviar figurinha | stickerAuthor ignorado |
POST send-location |
enviar localização | Só as coordenadas chegam; nome e endereço não |
POST send-contact, send-contacts |
enviar contato | send-contacts envia um por contato, até 5 (não confirmado) |
POST send-link |
enviar link | Sai como texto com o endereço, sem prévia |
POST send-reaction, send-remove-reaction |
reação | |
POST send-poll |
enquete | A Z-API só aceita grupo; aqui qualquer destino |
POST send-button-list, send-button-actions |
botões de resposta e de ação | Viram botões. Os botões da rota nativa foram provados em 12/11/2026; as rotas send-button-* da Z-API ainda não |
POST send-option-list, send-carousel |
lista e carrossel | Recusados: 422 interactive_unsupported (o WhatsApp mostra "mensagem incompatível") |
POST forward-message |
encaminhar | (não confirmado) |
POST send-text-status, send-image-status, send-video-status |
status | Desligado por padrão: 403 status_disabled |
delayMessage e delayTyping somam ao ritmo da instância, no máximo 5 segundos cada.
Quais são as rotas de leitura e administração?
| Rota Z-API | Observações |
|---|---|
POST read-message |
{value:true} |
DELETE messages?messageId&phone&owner[&deleteForMe] (também delete-message) |
Caminho confirmado na página; owner ignorado |
GET chats |
page e pageSize até 100; unread sempre "0" |
GET chat-messages/{phone} |
(não confirmado) rota e formato |
POST modify-chat |
Só archive, unarchive, pin, unpin; as demais ações dão 404 unsupported |
GET contacts, GET contacts/{phone}, GET profile-picture?phone= |
Perfil e foto |
GET phone-exists/{phone}, POST phone-exists-batch |
Lote de até 50 (a Z-API aceita mais); devolve objeto (não confirmado) |
GET groups, GET group-metadata/{id} |
O link de convite vem nulo ali; use a rota própria |
POST create-group, update-group-name, update-group-photo, update-group-description |
|
POST add-participant, remove-participant, add-admin, remove-admin |
|
POST leave-group, POST update-group-settings |
requireAdminApproval e adminOnlyAddMember ignorados |
GET group-invitation-link/{id}, POST redefine-invitation-link/{id} |
|
GET light-group-metadata/{id}, GET group-invitation-metadata?url= |
(não confirmado) |
Quais são as rotas da instância?
| Rota | Como funciona |
|---|---|
GET status |
{connected, smartphoneConnected, session, error} (formato atualizado em 12/11/2026; a rota send-text foi provada em aparelho, esta ainda não) |
GET qr-code, GET qr-code/image |
QR como data:image/png;base64,... (não confirmado) (resposta já conectada) |
GET phone-code/{phone} |
Código de pareamento |
GET disconnect, GET restart |
Desconecta e reconecta |
E os avisos?
Na Z-API cada tipo de aviso tem um endereço. Na ProxyBox a instância tem um endereço para todos. As rotas update-webhook-* e update-every-webhooks existem, mas se você gravar um tipo com endereço diferente do já salvo, a resposta é 400 explicando e mandando usar update-every-webhooks. value vazio remove só aquele tipo. O endereço passa pela guarda de rede (https, público). Para a presença no chat (update-webhook-chat-presence), o valor é guardado sem efeito: a ProxyBox não recebe presença.
Escolha o formato zapi e os avisos chegam como a Z-API envia, com a assinatura X-ProxyBox-Signature sobre o corpo que sai:
| Aviso da ProxyBox | Corpo no formato zapi |
|---|---|
| Mensagem recebida (individual ou grupo) | ReceivedCallback com phone, fromMe, momment, chatName, senderName, isGroup e uma chave por tipo (text, image, audio, video, document, location, contact, sticker, poll) |
| Resposta a botão ou lista | text mais buttonsResponseMessage ou listResponseMessage (não confirmado) |
| Mensagem enviada | DeliveryCallback; com notifySentByMe, ReceivedCallback com fromMe: true |
| Entregue, lida, ouvida | MessageStatusCallback |
| Conectou ou desconectou | ConnectedCallback ou DisconnectedCallback |
| Reação, edição, exclusão | ReceivedCallback com reaction, isEdit ou notification: REVOKE |
| Grupo atualizado, chamada | ReceivedCallback com notification (não confirmado) os nomes |
Se você também ligou o S3, imageUrl, audioUrl e similares vêm preenchidos; sem ele, vêm vazios.
O que não existe nas rotas da ProxyBox?
Cada item abaixo responde 404 com code: unsupported e uma frase em português:
- botão de PIX, de código único (OTP) e lista com imagem ou vídeo;
- produto, catálogo e pedidos; fixar mensagem; evento; votar em enquete; vídeo redondo;
- responder botão ou lista pela API (
reply-*); - ligações e SIP; bloquear, denunciar e adicionar contato; comunidades; canais (newsletter); listas de transmissão; fila de mensagens;
- Business (produtos, etiquetas nativas, coleções), privacidade do perfil, dados do aparelho, Meta AI;
- ajustes automáticos da Z-API (leitura automática, rejeitar chamada por essa rota, proteção de aviso);
- aprovar ou recusar entrada em grupo e aceitar convite;
- criar e cancelar instância pelo programa de parceiros (criar instância por API está em breve).
O que muda de comportamento?
- Ritmo da casa: as travas da API v1 valem aqui (10 por minuto, 500 por dia, pausa, trava de contato novo, não perturbe). A Z-API não limita desse jeito; é possível que um código que enviava rápido passe a receber 429.
- Só https em mídia e em avisos. Endereços internos são recusados.
- Chaves e IPs permitidos valem: veja IPs permitidos.
- Páginas:
pageSizeaté 100. - Token na URL. Quem não aceita isso usa a API v1, que leva a chave em cabeçalho.
O que está não confirmado, em resumo?
- Método e caminho de todas as rotas, exceto
DELETE messages. Para reduzir o risco, as rotas que gravam aceitam POST e PUT, e as que leem aceitam GET e POST. - O formato exato de erro da Z-API além de
{"error": "..."}. - Objeto ou lista em
phone-exists. - Corpos de
forward-message,chat-messages,send-contactse das rotas de metadados leves. - Valores de
PresenceChatCallbacke nomes denotificationnos avisos de grupo e chamada. - O código HTTP da Z-API para token inválido.
Se você tem acesso à coleção da Z-API (a conta grátis exporta o Postman), compare e abra um ticket com as diferenças: ajustamos durante o teste.
Veja também
- Migrar da Evolution API: mapa de rotas
- Botões no WhatsApp via API: resposta e ação
- Webhook da API de WhatsApp: eventos e assinatura
- Sandbox da API de WhatsApp: testar sem número
Índice completo: todos os guias. Sobre o produto: planos e recursos da API de WhatsApp.
Autoria: equipe técnica da ProxyBox. Atualizado em 11/11/2026. Fontes: documentação pública da Z-API (developer.z-api.io), lida em 11/11/2026, conforme a nota técnica da compatibilidade. A ProxyBox não tem vínculo com a Z-API. Recurso em beta.