Pular para o conteúdo
Documentação

API: criar, editar e remover domínios

Como criar, alterar e remover domínios pela API do miniCP com o token de escrita, com exemplos em curl.

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

Com o token de escrita você cria, altera e remove domínios sem abrir o painel. A API aplica as mesmas validações da tela Domínios.

Requisitos:

  • miniCP 2.63.0 ou mais novo (o campo env exige 2.65.0).
  • Token de escrita gerado em Configurações > Geral > API. Veja API do miniCP: visão geral e tokens.
  • O usuário (conta) dono do domínio já deve existir no miniCP.

Nos exemplos:

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

Atenção: as alterações são aplicadas uma de cada vez. Se dois sistemas enviarem pedidos ao mesmo tempo, o segundo espera o primeiro terminar.

Criar um domínio

POST /api/v1/domains com corpo JSON.

curl -s -X POST "$MINICP/api/v1/domains" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "loja.com.br",
    "username": "loja",
    "type": "php",
    "php_version": "8.3",
    "aliases": ["www.loja.com.br"],
    "rewrite": "magento",
    "haproxy": { "include_www": true, "ssl": true }
  }'

Campos

Campo Obrigatório Descrição
domain Sim Nome do domínio. Exemplo: loja.com.br.
username Sim Usuário dono. Precisa existir.
type Não php (padrão), node ou redirect.
php_version Não Versão do PHP (padrão 8.3). Precisa estar instalada no servidor.
aliases Não Lista de nomes extras, como ["www.loja.com.br"]. Aceita curinga *.loja.com.br. Um nome que já é domínio ou alias de outro site é recusado.
doc_root Não Pasta do site, relativa à home do usuário. Padrão: public_html. Exemplo: loja/pub. Aceita só letras, números, ., _, - e /, sem espaços nem ...
rewrite Não Modelo de regras: generic (padrão), magento ou laravel.
create_index Não true cria um index.html de boas-vindas.
haproxy Não Publica no HAProxy logo após criar. Veja abaixo.
cloudflare Não Cria o registro DNS na Cloudflare. Veja abaixo.

Campos para type: "redirect":

Campo Descrição
redirect_to URL de destino, começando com http:// ou https://. Obrigatório.
redirect_code 301 (padrão, permanente) ou 302 (temporário).
redirect_keep_path true mantém o caminho: /produto vai para destino/produto.

Campos para type: "node" (dentro do objeto node):

Campo Descrição
node.start Comando de início. Padrão: npm start.
node.port Porta interna da aplicação, entre 3000 e 3999. Sem informar, o painel escolhe uma livre.
node.env Valor de NODE_ENV, só letras minúsculas. Padrão: production.
node.bin Caminho absoluto do binário do Node, se não for o padrão.

Opções haproxy e cloudflare

Campo Descrição
haproxy.include_www true publica também o www. do domínio.
haproxy.ssl true (padrão) emite o certificado SSL. Precisa do e-mail padrão definido em Configurações; sem ele o domínio é publicado sem certificado e a resposta avisa.
cloudflare.proxied true cria o registro com o proxy da Cloudflare ligado.

Só funcionam se o HAProxy e a Cloudflare estiverem configurados no servidor. Com cloudflare, a publicação no HAProxy é agendada para cerca de 1 minuto depois, para dar tempo ao DNS. Com SSL, ela roda em segundo plano e gera um job. Para só publicar sem opções, pode enviar "haproxy": true.

Resposta

Sucesso responde 201:

{
  "ok": true,
  "message": "Dominio 'loja.com.br' criado com sucesso!",
  "domain": {
    "domain": "loja.com.br",
    "aliases": ["www.loja.com.br"],
    "username": "loja",
    "status": "active",
    "type": "php",
    "php_version": "8.3",
    "document_root": "/home/loja/public_html"
  },
  "provisioning": [
    { "ok": true, "message": "Provisionamento no HAProxy + SSL de 'loja.com.br' iniciado em segundo plano.", "job_id": "a1b2c3d4e5f6" }
  ]
}

Acompanhe o job_id em GET /api/v1/jobs/<id> (veja API: publicar domínios no HAProxy). A resposta de criação não traz o bloco ssl; consulte GET /api/v1/domains/<dominio> depois.

Erros comuns: domínio já existe (409), usuário não encontrado (404), PHP não instalado, alias em uso, nome inválido ou document root inválido (400). Para o document root, a mensagem é Document root invalido: use letras, numeros, . _ - e / (sem espacos nem ..)..

Se o servidor web recusar a configuração do novo domínio, nada é criado e o erro traz O servidor web recusou a configuracao do dominio; nada foi criado..

Exemplos

Redirecionamento:

curl -s -X POST "$MINICP/api/v1/domains" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"domain":"lojaantiga.com.br","username":"loja","type":"redirect",
       "redirect_to":"https://loja.com.br","redirect_code":301,"redirect_keep_path":true}'

Aplicação Node.js:

curl -s -X POST "$MINICP/api/v1/domains" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"domain":"app.loja.com.br","username":"loja","type":"node",
       "doc_root":"app","node":{"start":"npm start","env":"production"}}'

Alterar um domínio

PATCH /api/v1/domains/<dominio>. Envie só os campos que quer mudar.

Campo Descrição
php_version Nova versão do PHP (instalada no servidor).
aliases Lista completa de aliases. Substitui a atual; [] remove todos.
doc_root Nova pasta, relativa à home do usuário. Não pode ser vazia. Mesma regra de caracteres da criação.
rewrite generic, magento ou laravel.
enabled false desativa o site (mostra a página de site inativo); true reativa.
env Variáveis de ambiente do domínio, como objeto {"CHAVE": "valor"}. Substitui todas as atuais; {} remove todas. Só para domínios PHP. Veja abaixo.
curl -s -X PATCH "$MINICP/api/v1/domains/loja.com.br" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"php_version":"8.4","aliases":["www.loja.com.br","loja.net.br"]}'

A resposta traz changes, com uma frase por alteração aplicada, e o domínio atualizado.

  • Pode usar um alias na URL: a alteração vale para o domínio principal.
  • Campos fora da lista acima são recusados com 400, indicando os aceitos.
  • Troca de dono não é suportada. Enviar username responde 400. Para mudar de conta, remova o domínio e crie de novo no outro usuário.
  • Se um campo falhar no meio, os anteriores já ficam aplicados. A mensagem de erro informa o que já foi feito em (ja aplicado: ...).
  • Se o servidor web recusar a configuração de um campo (PHP, rewrite, aliases, document root ou variáveis), aquele campo volta ao estado anterior e o erro traz O servidor web recusou a configuracao; nada foi alterado.. Uma configuração inválida nunca fica gravada travando os próximos reloads.

Dica: ao incluir um alias em domínio que já tem certificado, a resposta avisa que o certificado atual não cobre o novo nome. Publique o alias no HAProxy com SSL para emitir o certificado dele.

Variáveis de ambiente (env)

O campo env grava variáveis de ambiente no vhost do domínio, as mesmas da tela Domínios (ícone { }). O PHP lê com getenv('CHAVE') ou $_SERVER['CHAVE']. O servidor web é recarregado em seguida.

Exemplo: Magento com duas lojas no mesmo código, cada domínio com o seu MAGE_RUN_CODE:

curl -s -X PATCH "$MINICP/api/v1/domains/loja1.exemplo.com.br" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"env":{"MAGE_RUN_CODE":"base","MAGE_RUN_TYPE":"website"}}'

curl -s -X PATCH "$MINICP/api/v1/domains/loja2.exemplo.com.br" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"env":{"MAGE_RUN_CODE":"loja2","MAGE_RUN_TYPE":"website"}}'

Em changes aparece, por exemplo: "Variaveis de 'loja1.exemplo.com.br' atualizadas: MAGE_RUN_CODE, MAGE_RUN_TYPE.".

Para remover todas as variáveis do domínio:

curl -s -X PATCH "$MINICP/api/v1/domains/loja1.exemplo.com.br" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"env":{}}'

Regras:

  • nome com letras, números e _, sem começar com número, até 64 caracteres;
  • valor com até 1024 caracteres, sem aspas duplas, \, $ ou quebra de linha;
  • até 50 variáveis por domínio;
  • nomes reservados são recusados: PHP_VALUE, PHP_ADMIN_VALUE, HTTPS, PATH, os que começam com HTTP_, SERVER_, REMOTE_, REQUEST_, SCRIPT_ ou DOCUMENT_ e outras variáveis do CGI;
  • não vale para domínios node (eles têm variáveis próprias) nem redirect.

Variável reservada ou valor inválido respondem 400, com a mensagem:

{"ok": false, "error": "'PHP_VALUE' e reservada pelo servidor web/PHP e nao pode ser definida."}

Se o servidor web recusar a nova configuração, nada muda: o vhost anterior volta.

Atenção: no GET, o token de leitura vê só os nomes das variáveis (cada uma com valor null), e o token de escrita vê os valores. Mesmo assim, evite guardar senhas nelas.

Remover um domínio

DELETE /api/v1/domains/<dominio>

curl -s -X DELETE -H "Authorization: Bearer $TOKEN" \
  "$MINICP/api/v1/domains/loja.com.br?haproxy=1&cert=1"
Parâmetro Efeito
haproxy=1 Tira também as entradas deste servidor no HAProxy.
cert=1 Junto com haproxy=1, remove o certificado do HAProxy.

O que acontece:

  • A configuração do site sai do servidor web e o domínio sai do painel.
  • Os arquivos da home do usuário são mantidos.
  • Sem haproxy=1, o HAProxy não é alterado.
  • Informe sempre o domínio principal. Um alias na URL é recusado com 404, indicando o domínio principal.

A resposta traz message e, com haproxy=1, o bloco haproxy com o resultado (ok e message).

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!