curl --request POST \
--url https://api.wppfy.com/instance/proxy \
--header 'Content-Type: application/json' \
--header 'token: <api-key>' \
--data '
{
"mode": "custom",
"proxy_url": "http://usuario:senha@proxy-do-cliente.example:8080",
"proxy_fallback": "internal"
}
'{
"details": "Proxy configurado",
"proxy": {
"mode": "custom",
"effective_mode": "custom",
"fallback": {
"active": false,
"reason": "",
"since": 0
},
"proxy_url": "http://***:***@proxy-do-cliente.example:8080",
"proxy_fallback": "internal",
"managed": false,
"last_test_at": 0,
"last_test_error": "",
"validation_error": false
},
"restart_requested": true
}Configurar ou alterar o proxy
Define explicitamente um dos três estados aceitos:
mode=custom: usa um proxy próprio informado emproxy_url;mode=internal: usa a infraestrutura interna; oumode=none: conexão direta, permitida apenas comconfirm_no_proxy=true.
Importante: POST /instance/proxy confirma que a configuração foi salva, não que o proxy já foi comprovado em uso.
A validação operacional principal acontece no próximo ciclo real de conexão da instância.
Em termos práticos:
200 OKaqui = configuração persistida com sucesso;- falhas reais de conectividade podem aparecer depois; e
- para observar o estado real, consulte
GET /instance/proxye leia:effective_modeeffective_detailfallback.activelast_test_errorvalidation_error
Quando mode=custom, você também pode definir a contingência via proxy_fallback:
internal: tenta a infraestrutura interna e, se ainda assim falhar, pode usar direto como último recurso;never: não usa contingência; ou- uma URL de proxy de contingência controlada pelo próprio cliente.
Quando mode=internal, rotate_now: true troca imediatamente o proxy interno persistido.
Se houver mais de uma origem interna disponível, a plataforma escolhe outra origem sem expor o fornecedor.
Se houver apenas uma origem, troca apenas o proxy/IP dentro dessa origem.
Protocolos aceitos em URLs de proxy customizado:
http://usuario:senha@host:portahttps://usuario:senha@host:portasocks5://usuario:senha@host:portasocks5h://usuario:senha@host:porta
O esquema socks:// genérico não é aceito. Para proxies SOCKS, use socks5:// ou socks5h://.
curl --request POST \
--url https://api.wppfy.com/instance/proxy \
--header 'Content-Type: application/json' \
--header 'token: <api-key>' \
--data '
{
"mode": "custom",
"proxy_url": "http://usuario:senha@proxy-do-cliente.example:8080",
"proxy_fallback": "internal"
}
'{
"details": "Proxy configurado",
"proxy": {
"mode": "custom",
"effective_mode": "custom",
"fallback": {
"active": false,
"reason": "",
"since": 0
},
"proxy_url": "http://***:***@proxy-do-cliente.example:8080",
"proxy_fallback": "internal",
"managed": false,
"last_test_at": 0,
"last_test_error": "",
"validation_error": false
},
"restart_requested": true
}Autorizações
Corpo
Campo canônico para definir a estratégia de proxy.
custom, internal, none Obrigatório quando mode=custom.
Protocolos aceitos: http://, https://, socks5:// e socks5h://.
O esquema socks:// genérico não é suportado; use socks5:// ou socks5h://.
"http://usuario:senha@ip:porta"
Política de contingência para mode=custom.
Aceita internal, never ou uma URL de proxy de contingência usando http://, https://, socks5:// ou socks5h://.
Obrigatório quando mode=none.
Quando true com mode=internal, troca imediatamente o proxy interno persistido sem expor o fornecedor usado.
País ISO alpha-2 usado para validar a saída do proxy gerenciado. Use somente com mode=internal.
"br"
Estado/UF do alvo geográfico retornado pelo catálogo de cidades.
"sp"
Slug da cidade retornado por GET /proxy-managed/cities.
"campinas"