A API REST do miniProxy permite automatizar, a partir de outro sistema, as mesmas tarefas que você faz pelo painel: publicar um domínio, apontá-lo para um backend, gerar o certificado SSL, adicionar ou tirar servidores e bloquear IPs. É ela que o miniCP usa para publicar os sites de um servidor no balanceador da frente.
Todas as respostas são em JSON e todas as alterações de configuração são aplicadas com reload do HAProxy na mesma chamada.
URL base
Todos os endpoints ficam sob o caminho /haproxy-admin/api. A URL completa depende de como o painel está publicado:
| Forma de acesso | URL base |
|---|---|
| Direto na porta do painel (padrão 5000) | http://203.0.113.10:5000/haproxy-admin/api |
| Pelo domínio do painel, atrás do HAProxy em HTTPS | https://proxy.exemplo.com.br/haproxy-admin/api |
Atenção: prefira sempre o acesso por HTTPS. Na autenticação Basic o usuário e a senha viajam em cada requisição; em HTTP puro eles passam abertos pela rede. Não publique a porta 5000 direto na internet: libere o acesso ao painel só para os IPs dos sistemas que usam a API.
Autenticação
A API usa HTTP Basic Auth com um usuário e senha do próprio painel (os mesmos da tela de login). Não há token de API separado.
Para criar um usuário só para a integração:
- Vá em Sistema > Usuarios.
- Clique em Novo Usuario.
- Preencha Usuario (ex.:
integracao-minicp) e Senha (mínimo 6 caracteres) e clique em Criar. - Use esse usuário e senha no sistema que vai chamar a API.
Com curl, informe as credenciais com -u:
curl -u integracao-minicp:SENHA https://proxy.exemplo.com.br/haproxy-admin/api/version
Detalhes importantes:
- Sem credenciais válidas, a resposta é
401com{"ok": false, "error": "Autenticacao necessaria"}. - Chamadas com Basic Auth não passam pela verificação de origem (proteção CSRF) do painel, então funcionam a partir de qualquer script ou servidor.
- Os endpoints de gráficos e telas internas do painel (lista no fim desta página) não aceitam Basic Auth: só funcionam com a sessão de quem está logado no navegador.
Dica: se você trocar a senha do usuário em Usuarios > Alterar senha, atualize também a configuração do sistema integrado (no miniCP, a aba HAProxy em Configuracoes).
Formato das requisições e respostas
- Envie o corpo dos
POSTem JSON, com o cabeçalhoContent-Type: application/json. - Toda resposta traz
"ok": trueou"ok": false. Em caso de erro, o campoerrorexplica o motivo e o status HTTP indica o tipo (400dado inválido,404não encontrado,409já existe,500falha ao executar). - Nas operações que alteram a config, o campo
reloaddiz se o reload do HAProxy deu certo ("ok") ou traz a mensagem de falha.
Antes de gravar, a maioria das operações valida a nova configuração com o HAProxy; se ela for recusada, nada é alterado e a resposta traz o erro. A cada alteração o painel guarda um backup do haproxy.cfg, que pode ser restaurado em Sistema > Backups.
Versão
GET /version
Retorna a versão do miniProxy instalada. Útil para conferir se vários servidores estão na mesma versão.
curl -u integracao-minicp:SENHA https://proxy.exemplo.com.br/haproxy-admin/api/version
{"version": "2.36.1"}
Provisionar um site completo
POST /provision
Faz em uma única chamada as três etapas de publicar um site: cria o backend com os servidores, cria o domínio apontando para ele e gera o certificado SSL.
| Campo | O que informar |
|---|---|
domain |
Domínio principal (obrigatório), ex.: loja.exemplo.com.br |
servers |
Lista de servidores (obrigatório): name, address, port e, opcionais, maxconn (padrão 3000) e backup (padrão false) |
backend |
Nome do backend. Se omitido, é gerado a partir do domínio (ex.: bk_loja_exemplo_com_br) |
balance |
Algoritmo de balanceamento (padrão roundrobin) |
include_www |
Incluir também o www. (padrão true) |
generate_cert |
Gerar o certificado SSL (padrão true) |
email |
Email para o Let's Encrypt. Opcional se o Email do responsavel estiver preenchido em Configs > Geral do painel |
curl -u integracao-minicp:SENHA -X POST \
https://proxy.exemplo.com.br/haproxy-admin/api/provision \
-H "Content-Type: application/json" \
-d '{
"domain": "loja.exemplo.com.br",
"servers": [{"name": "web1", "address": "198.51.100.20", "port": 80}]
}'
A resposta mostra o resultado de cada etapa em steps (backend, domain e cert):
{
"ok": true,
"domain": "loja.exemplo.com.br",
"backend": "bk_loja_exemplo_com_br",
"steps": {
"backend": {"ok": true, "name": "bk_loja_exemplo_com_br", "servers": 1, "reload": "ok"},
"domain": {"ok": true, "acl_name": "loja_exemplo_com_br", "backend": "bk_loja_exemplo_com_br", "reload": "ok"},
"cert": {"ok": true, "pem_path": "/etc/haproxy/certs/loja.exemplo.com.br.pem", "reload": "ok"}
}
}
Comportamento quando algo já existe:
- Backend já existe: a etapa
backendé pulada ("skipped": true) e os servidores enviados não são aplicados. Para mudar os servidores de um backend existente, use/backends/add-servere/backends/remove-server. - Domínio já existe: ele é atualizado no lugar (veja
/domains/addabaixo) e a resposta traz"updated": true. - Certificado: se a etapa falhar (DNS não aponta para o proxy, domínio atrás da Cloudflare com proxy ligado etc.), backend e domínio continuam criados; a resposta volta com
"ok": falsee o erro do certbot emsteps.cert.error.
Atenção: o certificado é emitido pela validação HTTP-01, então o domínio precisa já estar apontando para este proxy. Domínios com proxy da Cloudflare ligado (nuvem laranja) devem usar a validação DNS-01 em Certificados SSL.
Domínios
GET /domains
Lista os domínios publicados no frontend HTTPS, com seus hosts e backend.
curl -u integracao-minicp:SENHA https://proxy.exemplo.com.br/haproxy-admin/api/domains
POST /domains/add
Cria um domínio apontando para um backend que já existe. Se o domínio já existir, ele é atualizado no lugar (upsert): os hosts novos são somados aos atuais, o backend é trocado e a resposta traz "updated": true. Isso permite usar a mesma chamada para "trocar o backend do domínio".
| Campo | O que informar |
|---|---|
domain |
Domínio (obrigatório) |
backend |
Backend de destino. Se omitido, usa o backend padrão do frontend. Precisa existir, senão a chamada é recusada |
include_www |
Incluir também o www. (padrão true) |
acl_name |
Nome interno do domínio na config. Se omitido, é gerado a partir do domínio (pontos e hífens viram _) |
curl -u integracao-minicp:SENHA -X POST \
https://proxy.exemplo.com.br/haproxy-admin/api/domains/add \
-H "Content-Type: application/json" \
-d '{"domain": "loja.exemplo.com.br", "backend": "bk_servidor2"}'
{"ok": true, "updated": true, "domain": "loja.exemplo.com.br", "acl_name": "loja_exemplo_com_br",
"backend": "bk_servidor2", "include_www": true, "reload": "ok"}
Na config, o resultado é um par de linhas no frontend ft_https:
acl loja_exemplo_com_br hdr(host) -i loja.exemplo.com.br www.loja.exemplo.com.br
use_backend bk_servidor2 if loja_exemplo_com_br
Dica: se você enviar sempre o mesmo
domainsemacl_name, o nome interno gerado é o mesmo, e a chamada atualiza o domínio existente em vez de criar outro. Se um domínio foi criado com umacl_namediferente, envie esse mesmoacl_name.
POST /domains/remove
Remove o domínio (as linhas acl e use_backend). Informe o nome interno, não o domínio.
| Campo | O que informar |
|---|---|
acl_name |
Nome interno do domínio (obrigatório), como aparece em GET /domains |
curl -u integracao-minicp:SENHA -X POST \
https://proxy.exemplo.com.br/haproxy-admin/api/domains/remove \
-H "Content-Type: application/json" \
-d '{"acl_name": "loja_exemplo_com_br"}'
O certificado e o backend não são removidos junto.
Certificados SSL
GET /certs
Lista os certificados instalados no HAProxy, com validade.
curl -u integracao-minicp:SENHA https://proxy.exemplo.com.br/haproxy-admin/api/certs
POST /certs/generate
Gera (ou expande, se já existir) um certificado Let's Encrypt pela validação HTTP-01 e publica no HAProxy.
| Campo | O que informar |
|---|---|
domain |
Domínio (obrigatório) |
include_www |
Incluir também o www. (padrão true) |
email |
Email para o Let's Encrypt. Opcional se o Email do responsavel estiver preenchido em Configs |
curl -u integracao-minicp:SENHA -X POST \
https://proxy.exemplo.com.br/haproxy-admin/api/certs/generate \
-H "Content-Type: application/json" \
-d '{"domain": "loja.exemplo.com.br"}'
A chamada pode levar até cerca de 2 minutos. Configure o timeout do seu cliente HTTP de acordo.
POST /certs/renew
Renova todos os certificados que estão perto de vencer e publica os renovados no HAProxy. Não tem corpo.
curl -u integracao-minicp:SENHA -X POST https://proxy.exemplo.com.br/haproxy-admin/api/certs/renew
A resposta traz certbot_ok (se o certbot terminou sem erro), published (certificados atualizados) e failed (os que falharam). Uma falha em um certificado não impede a publicação dos demais. Pode levar alguns minutos.
POST /certs/remove
Remove um arquivo de certificado do HAProxy. O default.pem não pode ser removido.
| Campo | O que informar |
|---|---|
filename |
Nome do arquivo, ex.: loja.exemplo.com.br.pem |
curl -u integracao-minicp:SENHA -X POST \
https://proxy.exemplo.com.br/haproxy-admin/api/certs/remove \
-H "Content-Type: application/json" \
-d '{"filename": "loja.exemplo.com.br.pem"}'
Backends e servidores
GET /backends
Lista todos os backends com seus servidores.
curl -u integracao-minicp:SENHA https://proxy.exemplo.com.br/haproxy-admin/api/backends
POST /backends/create
Cria um backend novo. Se já existir um com o mesmo nome, a resposta é 409.
| Campo | O que informar |
|---|---|
name |
Nome do backend (letras, números, - e _), ex.: bk_loja |
servers |
Lista de servidores: name, address, port, e opcionais maxconn e backup |
balance |
Algoritmo (padrão roundrobin) |
options |
Lista de linhas extras da config, ex.: ["option httpchk GET /health"] |
curl -u integracao-minicp:SENHA -X POST \
https://proxy.exemplo.com.br/haproxy-admin/api/backends/create \
-H "Content-Type: application/json" \
-d '{
"name": "bk_loja",
"servers": [
{"name": "web1", "address": "198.51.100.20", "port": 80},
{"name": "web2", "address": "198.51.100.21", "port": 80, "backup": true}
]
}'
POST /backends/add-server
Adiciona um servidor a um backend existente.
| Campo | O que informar |
|---|---|
backend |
Nome do backend (obrigatório) |
name |
Nome do servidor (obrigatório) |
address |
IP ou hostname (obrigatório) |
port |
Porta (obrigatório) |
maxconn |
Máximo de conexões simultâneas (padrão 3000) |
backup |
true para só receber tráfego quando os principais caírem (padrão false) |
curl -u integracao-minicp:SENHA -X POST \
https://proxy.exemplo.com.br/haproxy-admin/api/backends/add-server \
-H "Content-Type: application/json" \
-d '{"backend": "bk_loja", "name": "web3", "address": "198.51.100.22", "port": 80}'
POST /backends/remove-server
Remove um servidor do backend.
curl -u integracao-minicp:SENHA -X POST \
https://proxy.exemplo.com.br/haproxy-admin/api/backends/remove-server \
-H "Content-Type: application/json" \
-d '{"backend": "bk_loja", "name": "web3"}'
POST /backends/toggle-server
Coloca um servidor em manutenção (disable) ou o devolve ao balanceamento (enable). Vale na hora, sem reload, e fica gravado na config.
| Campo | O que informar |
|---|---|
backend |
Nome do backend |
name |
Nome do servidor |
action |
enable ou disable |
curl -u integracao-minicp:SENHA -X POST \
https://proxy.exemplo.com.br/haproxy-admin/api/backends/toggle-server \
-H "Content-Type: application/json" \
-d '{"backend": "bk_loja", "name": "web1", "action": "disable"}'
Atenção: um backend pode atender vários domínios. Desabilitar ou remover o único servidor ativo tira todos esses sites do ar.
POST /backends/remove
Remove um backend inteiro e as linhas use_backend que apontavam para ele. O backend padrão do frontend não pode ser removido.
curl -u integracao-minicp:SENHA -X POST \
https://proxy.exemplo.com.br/haproxy-admin/api/backends/remove \
-H "Content-Type: application/json" \
-d '{"name": "bk_loja"}'
Atenção: os domínios que usavam esse backend passam a cair no backend padrão.
Portas TCP
Equivalente à tela Portas TCP: encaminha uma porta dedicada (MySQL, FTP, SSH...) direto para um servidor, sem HTTP.
GET /tcp-proxies
curl -u integracao-minicp:SENHA https://proxy.exemplo.com.br/haproxy-admin/api/tcp-proxies
POST /tcp-proxies/create
| Campo | O que informar |
|---|---|
name |
Nome do proxy, ex.: mysql |
ports |
Porta ou intervalos: 3306 ou 21,30000-30010 |
servers |
Lista de servidores: name, address, port |
bind_addr |
Endereço de escuta (padrão *, todos) |
balance |
roundrobin, leastconn, source ou first (padrão roundrobin) |
timeout |
Tempo máximo de conexão ociosa (padrão 1h) |
curl -u integracao-minicp:SENHA -X POST \
https://proxy.exemplo.com.br/haproxy-admin/api/tcp-proxies/create \
-H "Content-Type: application/json" \
-d '{"name": "mysql", "ports": "3306", "servers": [{"name": "db1", "address": "198.51.100.30", "port": 3306}]}'
Portas já em uso ou reservadas pelo proxy são recusadas com 409.
POST /tcp-proxies/remove
curl -u integracao-minicp:SENHA -X POST \
https://proxy.exemplo.com.br/haproxy-admin/api/tcp-proxies/remove \
-H "Content-Type: application/json" \
-d '{"name": "mysql"}'
Blocklist global
Equivalente a Regras > Blocklist global. Vale para todos os domínios e é aplicada na hora, sem reload.
/blocklist/ip (GET, POST, DELETE)
| Método | Efeito |
|---|---|
GET |
Lista os IPs/faixas bloqueados, com motivo e data |
POST |
Bloqueia um IP ou faixa CIDR. Campos: ip (obrigatório) e reason (opcional) |
DELETE |
Desbloqueia. Campo: ip |
# bloquear
curl -u integracao-minicp:SENHA -X POST \
https://proxy.exemplo.com.br/haproxy-admin/api/blocklist/ip \
-H "Content-Type: application/json" \
-d '{"ip": "203.0.113.45", "reason": "scanner de vulnerabilidades"}'
# desbloquear
curl -u integracao-minicp:SENHA -X DELETE \
https://proxy.exemplo.com.br/haproxy-admin/api/blocklist/ip \
-H "Content-Type: application/json" \
-d '{"ip": "203.0.113.45"}'
O IP bloqueado tem a conexão TCP recusada antes mesmo do TLS, então ele não aparece no log de acesso. Faixas da Cloudflare e de rede interna (privada/loopback) são recusadas pela API, porque derrubariam todo o tráfego que passa por elas.
/blocklist/ua (GET, POST, DELETE)
Bloqueia (403) qualquer requisição cujo User-Agent contenha o trecho informado, sem diferenciar maiúsculas de minúsculas.
| Campo | O que informar |
|---|---|
ua |
Trecho do User-Agent, sem espaços, até 200 caracteres, ex.: ahrefsbot |
reason |
Motivo (opcional) |
curl -u integracao-minicp:SENHA -X POST \
https://proxy.exemplo.com.br/haproxy-admin/api/blocklist/ua \
-H "Content-Type: application/json" \
-d '{"ua": "ahrefsbot", "reason": "crawler de SEO"}'
Atenção: um trecho curto demais (ex.:
bot) pega também Googlebot e Bingbot e pode tirar seus sites do Google. Use o nome completo do robô.
Limpar o cache de um domínio
Para domínios com cache ligado em Cache e persistencia, o próprio domínio responde a um caminho especial que limpa o cache dele na hora, sem reload. Use o token exibido na tela Cache e persistencia (botão Trocar token gera outro).
curl -X POST https://loja.exemplo.com.br/__mp-cache-purge -H "X-Purge-Token: TOKEN"
A resposta é cache limpo (200) ou token invalido (403). Cada chamada limpa só o domínio do endereço chamado (incluindo o www.). Esse caminho não usa o usuário e senha do painel.
Endpoints internos do painel
Os endpoints abaixo alimentam as telas e gráficos do painel. Eles exigem a sessão de quem está logado no navegador, não aceitam Basic Auth e podem mudar entre versões sem aviso. Não use em integrações.
| Endpoint | Usado em |
|---|---|
/status, /traffic, /history/*, /server-stats, /tcp-server-stats |
Dashboard, Backends, Portas TCP |
/logs, /logs/tail, /domain-logs |
Logs e detalhe do domínio |
/analytics/*, /ip-traffic |
Tráfego por domínio, Tráfego & limites |
/cache/stats |
Cache e persistencia |
/rules/matches, /rules/log, /blocklog/* |
Regras e Bloqueios |
/waf/*, /threats/check |
WAF e Listas de ameaças |
/health, /diagnostics |
Saúde (uptime) e Diagnóstico |
/ip/info, /ip/log |
Investigar IP |
/update/check, /update/status |
Atualização |