Proxy
Configurar ou alterar o proxy
/instance/proxyAceita apenas os modos
custom(proxy próprio) enone(sem proxy).Em
proxy_urleproxy_fallback, o host precisa ser um IP público escrito por extenso (IPv4, ou IPv6 entre colchetes), com a porta explícita entre 1024 e 65535. Nome de host (comoproxy.exemplo.com) não é aceito, e portas de bancos e serviços internos (6379, 5432, 27017, 11211, 9200 e similares) são recusadas. Exemplo:socks5://usuario:[email protected]:1080.
Autenticação: envie a chave da conexão no header token ou em Authorization: Bearer.
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://.
Corpo da requisição (JSON)
| Campo | Tipo | Descrição |
|---|---|---|
| mode | string | Campo canônico para definir a estratégia de proxy. |
| proxy_url | string | Obrigatório quando Exemplo: http://usuario:senha@ip:porta |
| proxy_fallback | string | Política de contingência para |
| confirm_no_proxy | boolean | Obrigatório quando |
| rotate_now | boolean | Quando Exemplo: false |
* obrigatório
Exemplos de corpo
Proxy customizado com fallback interno
{
"mode": "custom",
"proxy_url": "http://usuario:[email protected]:8080",
"proxy_fallback": "internal"
}Proxy customizado com proxy de contingência próprio
{
"mode": "custom",
"proxy_url": "http://usuario:[email protected]:8080",
"proxy_fallback": "socks5://backup:[email protected]:1080"
}Modo interno
{
"mode": "internal"
}Rotacionar proxy interno agora
{
"mode": "internal",
"rotate_now": true
}Direto explícito
{
"mode": "none",
"confirm_no_proxy": true
}Respostas
- 200Proxy configurado com sucesso
- 400Payload inválido ou falha na validação do proxy
- 401Token inválido ou expirado
- 409Não há proxy alternativo disponível para rotação interna
- 500Erro interno do servidor ao configurar o proxy
Experimente
Atenção: a chamada é real. Ela roda na sua conexão e pode enviar mensagem de verdade. A chave fica só nesta tela e some ao sair dela; nunca é guardada.