Ir para o conteúdo

Proxy

O proxy do provedor e o proxy próprio por número: ver, trocar o IP, escolher o país e usar o seu.

Cada número de WhatsApp pode sair por um proxy. Há duas origens:

  • o proxy do provedor, que a plataforma configura: cada número recebe um proxy fixo (um número, um IP), que você troca quando quiser;
  • o seu proxy próprio, por número: uma URL que você traz, se o plano incluir.

O número só pega o proxy ao conectar: trocar o proxy reconecta o número, com alguns segundos sem sessão.

Ver o proxy de um número

bash
curl -H "Authorization: Bearer $API_KEY" \
  "$API_URL/api/v1/instances/<id>/proxy"
json
{"enabled": true, "current": "", "provider": "webshare.io", "country": "", "countries": null,
 "source": "custom", "custom": {"scheme": "http", "host": "proxy.example.com", "port": 8080, "has_auth": true}}
  • source: custom (o seu), provider (o do provedor, em current, com as credenciais mascaradas) ou none.
  • custom só vem com source: "custom" e nunca traz o usuário nem a senha: has_auth diz se há.
  • enabled diz se a API tem o provedor configurado e se o plano inclui o proxy. countries traz os países disponíveis, quando o provedor responde.

Abre com a chave do número ou com uma chave de API (wck_...) com o escopo Números.

O proxy do provedor

Trocar o IP (vai para o próximo proxy do provedor, com outro endereço, e reconecta o número):

bash
curl -X POST -H "Authorization: Bearer $NUMBER_KEY" \
  "$API_URL/api/v1/instances/<id>/proxy/rotate"

Escolher o país do proxy:

bash
curl -X POST "$API_URL/api/v1/instances/<id>/proxy/country" \
  -H "Authorization: Bearer $NUMBER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country": "BR"}'
  • Essas duas rotas abrem com a chave do número. Uma chave de API não troca o IP nem o país.
  • O plano precisa incluir o proxy: sem ele, 403 plan_feature_disabled.
  • Cada troca de IP ou de país conta uma troca do mês. Acima do teto do plano, 403 plan_limit; uma troca que falha não conta.
  • Sem outro IP disponível no provedor, 409 NO_OTHER_PROXY. Sem provedor configurado na plataforma, 400 proxy not configured.
  • Com o proxy próprio em uso, as duas respondem 409 custom_proxy_active.

O proxy próprio

bash
curl -X PUT "$API_URL/api/v1/instances/<id>/proxy/custom" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "http://usuario:senha@proxy.example.com:8080"}'
  • Plano: o proxy próprio vem desligado em todo plano que não o inclua de forma explícita: sem ele, 403 plan_feature_disabled.
  • A URL: http://, https:// ou socks5://, com usuário e senha opcionais, sem caminho, query nem fragmento; porta de 1 a 65535 (padrão 80, 443 e 1080). Fora disso, 400 invalid_proxy_url, com o motivo.
  • Endereço público: o host não pode ser interno (loopback, rede privada, link-local, nome como localhost ou .local), nem um nome que resolve para um endereço interno.
  • O teste antes de trocar: a API abre um túnel até o WhatsApp pelo seu proxy, em até 10 segundos. Se falhar, 400 proxy_unreachable, com o motivo, e nada muda.
  • Aceito: conta como uma troca do mês (o mesmo teto da troca de IP), o número reconecta pelo seu proxy, e a resposta é a mesma do GET .../proxy.
  • O proxy do provedor fica guardado como estava, para quando você remover o seu.

Voltar ao proxy do provedor (ou sem proxy):

bash
curl -X DELETE -H "Authorization: Bearer $API_KEY" \
  "$API_URL/api/v1/instances/<id>/proxy/custom"

Usar e remover o proxy próprio abrem com a chave do número ou com uma chave de API com o escopo Números (e o número na lista dela). Com a conta suspensa ou cancelada, o PUT responde 403 ACCOUNT_SUSPENDED; o DELETE e a leitura continuam abertos. Número removido: 410 INSTANCE_REMOVED.

Nem a resposta nem os registros da API mostram o usuário e a senha do seu proxy: só o esquema, o host e se há autenticação.