Pular para o conteúdo
Documentação

API: erros e boas práticas

Códigos de resposta da API do miniCP, como tratar cada erro e um script de exemplo para ativar um domínio com segurança.

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

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 do POST. Se responder 200, 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:

  1. Confere se o usuário existe.
  2. Confere se o domínio já existe (se sim, não cria de novo).
  3. Cria o domínio e pede a publicação no HAProxy com SSL.
  4. 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 com POST /api/v1/domains/<dominio>/haproxy.

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!