Esta página lista os códigos de resposta da API do miniCP e mostra como escrever uma automação que não cria nada em dobro nem provoca bloqueio do IP.
Códigos de resposta
Toda resposta de erro tem "ok": false e a mensagem em português no campo error.
| Código | Quando acontece | O que fazer |
|---|---|---|
200 |
Consulta ou alteração concluída. | — |
201 |
Domínio criado. | — |
202 |
Publicação no HAProxy com SSL iniciada em segundo plano. | Acompanhe o job_id. |
400 |
Dado inválido: domínio, alias, PHP não instalado, campo não aceito, SSL sem e-mail, troca de dono. | Corrija o pedido. Repetir igual não resolve. |
401 |
Token ausente ou errado (unauthorized). Também quando a API está desligada. |
Pare. Confira o token. Cada tentativa errada conta para o bloqueio. |
403 |
Token de leitura numa operação de escrita, ou IP fora da lista permitida. | Use o token de escrita ou libere o IP em Configurações > Geral > API. |
404 |
Usuário, domínio ou job não encontrado. Alias usado no DELETE. |
Confira o nome. |
409 |
Domínio já existe, ou HAProxy não configurado neste servidor. | Consulte antes de criar. |
429 |
IP bloqueado por excesso de tentativas com token errado. | Espere 15 minutos. |
500 |
Erro interno ao aplicar a alteração. | Veja a mensagem e o painel antes de repetir. |
502 |
O HAProxy recusou a operação. | Veja a mensagem; confira o HAProxy. |
Boas práticas
- Consulte antes de criar. Faça
GET /api/v1/domains/<dominio>antes doPOST. Se responder200, o domínio já existe: não crie de novo. Assim o script pode rodar mais de uma vez sem efeito colateral. - Pare no
401. Não repita chamadas com token errado. Cinco falhas em 15 minutos bloqueiam o IP por 15 minutos, inclusive para o login no painel. - Não repita
400. O pedido está errado; repetir só gera ruído no log. - Acompanhe jobs com intervalo. Consulte
GET /api/v1/jobs/<id>a cada 5 a 10 segundos, com um tempo máximo (por exemplo 5 minutos). - Use o token certo. Sistemas que só leem recebem o token de leitura. O de escrita fica só na automação de ativação.
- Restrinja por IP. Preencha os IPs permitidos sempre que houver token de escrita.
- Guarde o token fora do código. Use variável de ambiente ou cofre de senhas, nunca o repositório.
- Confira na auditoria. Tudo o que a API altera aparece em Auditoria com o usuário
api.
Script de exemplo: ativar um domínio
O script abaixo ativa um site para um cliente que já tem conta no miniCP:
- Confere se o usuário existe.
- Confere se o domínio já existe (se sim, não cria de novo).
- Cria o domínio e pede a publicação no HAProxy com SSL.
- Acompanha o job até terminar.
Precisa de curl e jq.
#!/usr/bin/env bash
# Uso: MINICP=https://painel.exemplo.com.br:5000 TOKEN=seu_token \
# ./ativar.sh loja.com.br loja 8.3
set -euo pipefail
DOMINIO="$1"; USUARIO="$2"; PHP="${3:-8.3}"
: "${MINICP:?defina MINICP}"; : "${TOKEN:?defina TOKEN}"
CORPO=$(mktemp); trap 'rm -f "$CORPO"' EXIT
COD=""
# chamada generica: corpo da resposta em $CORPO, codigo HTTP em $COD
api() {
local metodo="$1" caminho="$2" dados="${3:-}"
local args=(-s -o "$CORPO" -w '%{http_code}' -X "$metodo"
-H "Authorization: Bearer $TOKEN")
if [ -n "$dados" ]; then
args+=(-H "Content-Type: application/json" -d "$dados")
fi
COD=$(curl "${args[@]}" "$MINICP$caminho")
case "$COD" in
401|403|429) echo "Acesso negado ($COD): $(jq -r .error "$CORPO")" >&2; exit 1 ;;
esac
}
# 1) usuario precisa existir
api GET "/api/v1/users/$USUARIO"
[ "$COD" = 200 ] || { echo "Usuario $USUARIO nao existe ($COD)"; exit 1; }
# 2) dominio ja existe? nao cria de novo
api GET "/api/v1/domains/$DOMINIO"
if [ "$COD" = 200 ]; then
echo "Dominio $DOMINIO ja existe (dono: $(jq -r .domain.username "$CORPO")). Nada a fazer."
exit 0
fi
# 3) cria e pede HAProxy + SSL
dados=$(jq -n --arg d "$DOMINIO" --arg u "$USUARIO" --arg p "$PHP" \
'{domain:$d, username:$u, php_version:$p, aliases:["www."+$d],
haproxy:{include_www:true, ssl:true}}')
api POST "/api/v1/domains" "$dados"
if [ "$COD" != 201 ]; then
echo "Falha ao criar ($COD): $(jq -r .error "$CORPO")"; exit 1
fi
echo "Criado: $(jq -r .message "$CORPO")"
jq -r '.provisioning[] | " - \(.message)"' "$CORPO"
JOB=$(jq -r '[.provisioning[].job_id | select(. != null)][0] // empty' "$CORPO")
# 4) acompanha o job (ate 5 minutos)
if [ -n "$JOB" ]; then
for _ in $(seq 1 60); do
sleep 5
api GET "/api/v1/jobs/$JOB"
st=$(jq -r '.job.status // "desconhecido"' "$CORPO")
echo " job $JOB: $st"
case "$st" in
ok) echo "Publicado com SSL."; exit 0 ;;
erro) echo "Erro: $(jq -r .job.msg "$CORPO")"; exit 1 ;;
esac
done
echo "Tempo esgotado. Veja o job na tela HAProxy do painel."; exit 1
fi
Dica: o script não cria o usuário. A conta precisa existir antes, criada pelo painel.
Atenção: o certificado só é emitido se o DNS do domínio já aponta para o HAProxy. Se o job terminar com
erro, ajuste o DNS e peça de novo comPOST /api/v1/domains/<dominio>/haproxy.