Pular para o conteúdo
Documentação

API: publicar domínios no HAProxy

Como consultar, publicar e remover um domínio no HAProxy pela API do miniCP e acompanhar a emissão do SSL pelos jobs.

R Regis Manze 20/11/2026 4 min de leitura

Estes endpoints publicam um domínio do miniCP no HAProxy (o balanceador na frente dos servidores) e emitem o certificado SSL. Servem para domínios já criados ou para publicar depois um alias extra.

Requisitos:

  • HAProxy configurado em Configurações > HAProxy no miniCP. Sem isso, as operações de escrita respondem 409.
  • Token de escrita para publicar e remover. O token de leitura só consulta.
  • Para publicar um alias: miniCP 2.63.1 ou mais novo.

Nos exemplos:

MINICP=https://painel.exemplo.com.br:5000
TOKEN=seu_token_de_escrita

Consultar a situação

GET /api/v1/domains/<dominio>/haproxy

curl -s -H "Authorization: Bearer $TOKEN" "$MINICP/api/v1/domains/loja.com.br/haproxy"
{
  "ok": true,
  "domain": "loja.com.br",
  "haproxy": {
    "enabled": true,
    "backend": "bk_web01",
    "provisioned": true,
    "other_backend": [],
    "entries": [
      { "acl_name": "loja_com_br", "hosts": ["loja.com.br", "www.loja.com.br"], "backend": "bk_web01" }
    ],
    "cert": { "filename": "loja.com.br.pem", "expires": "2027-01-20" }
  }
}
Campo Significado
enabled false se o HAProxy não está configurado neste miniCP.
backend Backend deste servidor no HAProxy.
provisioned true se o domínio já aponta para este servidor.
other_backend Outros servidores que também atendem o domínio.
entries Entradas do HAProxy que contêm o nome.
cert Certificado encontrado no HAProxy, ou null.

Publicar no HAProxy

POST /api/v1/domains/<dominio>/haproxy

curl -s -X POST "$MINICP/api/v1/domains/loja.com.br/haproxy" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"include_www": true, "ssl": true, "email": "ti@exemplo.com.br"}'
Campo Descrição
include_www true publica também o www. do nome.
ssl true (padrão) emite o certificado SSL.
email E-mail para o certificado. Se omitido, usa o e-mail padrão de Configurações. Com ssl e sem nenhum e-mail, responde 400.

O nome na URL pode ser o domínio principal ou um alias dele. O domínio precisa existir neste miniCP; senão a resposta é 404.

Respostas:

  • Com ssl: true: 202 Accepted. A publicação e a emissão rodam em segundo plano, porque o certificado pode levar mais de um minuto.

    {
      "ok": true,
      "message": "Provisionamento no HAProxy + SSL de 'loja.com.br' iniciado em segundo plano.",
      "job_id": "a1b2c3d4e5f6",
      "status_url": "/api/v1/jobs/a1b2c3d4e5f6"
    }
    
  • Com ssl: false: 200 quando termina, já publicado. Se o HAProxy recusar, 502 com o motivo.

Dica: para publicar um alias além do www (por exemplo loja.net.br), crie o alias com PATCH e depois chame POST /api/v1/domains/loja.net.br/haproxy.

Atenção: o DNS do nome precisa apontar para o HAProxy antes de pedir SSL. Senão a emissão do certificado falha e o job termina com erro.

Acompanhar o job

GET /api/v1/jobs/<id>

curl -s -H "Authorization: Bearer $TOKEN" "$MINICP/api/v1/jobs/a1b2c3d4e5f6"
{
  "ok": true,
  "job": {
    "id": "a1b2c3d4e5f6",
    "domain": "loja.com.br",
    "status": "ok",
    "msg": "Dominio 'loja.com.br' provisionado no HAProxy (backend: bk_web01).",
    "created_at": 1795010000.1,
    "run_at": 1795010002.1,
    "finished_at": 1795010065.4
  }
}
status Significado
agendado Aguardando o horário de início.
executando Em andamento.
ok Concluído.
erro Falhou. O motivo está em msg.

As datas (created_at, run_at, finished_at) vêm em segundos desde 1970 (timestamp Unix). Consulte a cada 5 a 10 segundos até o status ser ok ou erro.

Se o painel reiniciar antes de o job terminar (por exemplo, numa atualização), o job é retomado sozinho quando o painel volta: o status volta para agendado, com msg "retomado apos reinicio do painel", e segue normalmente. Jobs criados por versões antigas do painel, sem os dados para retomar, terminam com erro e msg "interrompido por reinicio do painel; provisione de novo": nesse caso, chame o POST de novo.

O miniCP guarda só os 30 jobs mais recentes. Um job antigo responde 404. Os mesmos jobs aparecem na tela HAProxy do painel.

Remover do HAProxy

DELETE /api/v1/domains/<dominio>/haproxy

curl -s -X DELETE -H "Authorization: Bearer $TOKEN" \
  "$MINICP/api/v1/domains/loja.com.br/haproxy?cert=1"
  • Remove só as entradas deste servidor que atendem o nome. Entradas de outros servidores não são tocadas.
  • cert=1 remove também o certificado. Se outro servidor ainda atende o domínio, o certificado é mantido e a mensagem avisa.
  • O domínio continua existindo no miniCP. Para apagar tudo de uma vez, use DELETE /api/v1/domains/<dominio>?haproxy=1&cert=1.

A resposta traz message com o que foi feito, por exemplo nenhuma ACL deste servidor para o dominio quando não havia nada a remover.

Copiar para usar com IA

Este artigo foi útil?

Que bom! O que ajudou mais? O que faltou nesta página?

Opcional — seu voto já foi registrado.

Obrigado pelo seu feedback!