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
envexige 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
usernameresponde400. 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 comHTTP_,SERVER_,REMOTE_,REQUEST_,SCRIPT_ouDOCUMENT_e outras variáveis do CGI; - não vale para domínios
node(eles têm variáveis próprias) nemredirect.
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 valornull), 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).