Empresa brasileira · Entrega automática · Suporte em português Seg a sex, 9h as 18h · PIX em reais
ProxyBox
API de WhatsApp · Conta e migração

Como migrar da Z-API para a ProxyBox?

Troque a base da Z-API por proxybox.com.br/api/whatsapp/zapi e mantenha o código. Mapa de rotas, avisos no formato zapi, diferenças e o que não existe.

9 min de leitura Atualizado em 14 de novembro de 2026
Resposta curta
Troque a base de https://api.z-api.io/instances/{id}/token/{token} por https://proxybox.com.br/api/whatsapp/zapi/instances/{slug}/token/{chave} (o slug é o nome técnico da instância, no painel; a chave é a pbwa_… da instância). As rotas cobertas mantêm os campos e as respostas no estilo da Z-API. O cabeçalho Client-Token é aceito e ignorado.

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

  1. Contrate a instância e conecte o número (veja os primeiros passos). Se quiser testar antes sem número, use o sandbox.
  2. Anote o slug e a chave pbwa_… da instância.
  3. No seu sistema, troque a base. O resto do código fica.
  4. Se você recebe avisos, no painel escolha o formato de aviso zapi (veja abaixo) e cadastre o endereço.
  5. Teste cada rota que o seu sistema usa, em ordem de importância.
  6. Só então pare a instância na Z-API.
bash
# 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átis

Qual é 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: pageSize até 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?

  1. 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.
  2. O formato exato de erro da Z-API além de {"error": "..."}.
  3. Objeto ou lista em phone-exists.
  4. Corpos de forward-message, chat-messages, send-contacts e das rotas de metadados leves.
  5. Valores de PresenceChatCallback e nomes de notification nos avisos de grupo e chamada.
  6. 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

Í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.

Perguntas frequentes

O meu código da Z-API funciona sem mudar nada?
Nas rotas cobertas, só a base muda. Mas os caminhos e métodos de muitas rotas foram montados a partir do nome das páginas da Z-API e não foram conferidos rota a rota. Teste cada uma antes de desligar a Z-API.
O Client-Token continua necessário?
Pode mandar, mas é ignorado. A segurança é a chave que vai na própria URL.
O token na URL é seguro?
É o desenho da Z-API, e ele aparece em log de acesso do servidor de quem chama. Quem não quiser isso usa a API v1, que leva a chave em cabeçalho.

Guias relacionados

Pronto para colocar no ar?

Comece no sandbox, grátis. Quando funcionar, contrate a instância do seu número e pague com PIX ou saldo.

Com IP brasileiro dedicado R$ 89,90/mês
Só a instância (traga o seu IP) R$ 39,90/mês
Travou em alguma etapa?Manda o print do erro no WhatsApp. Respondemos em português.
Suporte em português Fale no WhatsApp