NODAPI

Proxy

Configurar ou alterar o proxy

POST/instance/proxy
  • Aceita apenas os modos custom (proxy próprio) e none (sem proxy).

  • Em proxy_url e proxy_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 (como proxy.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 em proxy_url;
  • mode=internal: usa a infraestrutura interna; ou
  • mode=none: conexão direta, permitida apenas com confirm_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 OK aqui = configuração persistida com sucesso;
  • falhas reais de conectividade podem aparecer depois; e
  • para observar o estado real, consulte GET /instance/proxy e leia:
  • effective_mode
  • effective_detail
  • fallback.active
  • last_test_error
  • validation_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:porta
  • https://usuario:senha@host:porta
  • socks5://usuario:senha@host:porta
  • socks5h://usuario:senha@host:porta

O esquema socks:// genérico não é aceito. Para proxies SOCKS, use socks5:// ou socks5h://.

Corpo da requisição (JSON)

CampoTipoDescrição
modestring

Campo canônico para definir a estratégia de proxy.

proxy_urlstring

Obrigatório quando mode=custom. Protocolos aceitos: http://, https://, socks5:// e socks5h://. O esquema socks:// genérico não é suportado; use socks5:// ou socks5h://.

Exemplo: http://usuario:senha@ip:porta

proxy_fallbackstring

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://.

confirm_no_proxyboolean

Obrigatório quando mode=none.

rotate_nowboolean

Quando true com mode=internal, troca imediatamente o proxy interno persistido sem expor o fornecedor usado.

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.

Cole a chave gerada no painel.