VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Conta do administrador

IPs bloqueados

Registra, lista, consulta e remove os IPs bloqueados pela equipe de segurança da loja.

O registro de IPs bloqueados guarda endereços que a equipe de segurança da loja marcou como indesejados, com o motivo e, opcionalmente, uma data de vencimento. Use para registrar um bloqueio vindo de um alerta, listar o que está ativo ou remover um bloqueio por engano.

O registro não recusa requisições sozinho

Nesta versão da API, adicionar um IP à lista o registra e o torna consultável em Verificar IP, mas a plataforma não recusa por conta própria as requisições vindas dele. Se você precisa barrar o tráfego, aplique também o bloqueio no seu firewall ou CDN e use esta lista como cadastro e auditoria. A consulta compara o texto do endereço exatamente: uma faixa CIDR cadastrada não casa com os IPs dentro dela.

Todas as rotas desta página exigem o privilégio manage_security ou manage_settings e o módulo security ligado.

GET/api/v1/admin/security/blocked-ipsAdmin

Listar IPs bloqueados

Lista os bloqueios, do mais recente para o mais antigo. Inclui os já vencidos que ainda não foram limpos (veja Limpar vencidos).

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário (veja Tokens).

Parâmetros de consulta

pageintegerpadrão: 1
Página, a partir de 1. Valor menor que 1 vira 1.
per_pageintegerpadrão: 20
Itens por página, de 1 a 100. Fora do intervalo volta para 20 (não é limitado a 100).

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/admin/security/blocked-ips?page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Lista paginada
json
{
  "items": [
    {
      "id": "7d7889d2-6e29-4022-bd78-f3a6139a2951",
      "ip_address": "198.51.100.77",
      "reason": "Tentativas de login em excesso",
      "blocked_at": "2026-10-11T20:52:43.976100Z",
      "expires_at": "2026-10-12T20:52:43.975872Z",
      "created_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

itemsobject[]
Bloqueios da página (veja os campos em Consultar bloqueio). Lista vazia quando não há nenhum.
totalinteger
Total de bloqueios, todas as páginas.
pageinteger
Página devolvida.
per_pageinteger
Tamanho de página usado.
total_pagesinteger
Número de páginas.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.{"error":"invalid or expired token"}
403Falta manage_security (ou manage_settings).{"error":"insufficient privileges","privilege_required_any":["manage_security","manage_settings"]}
403O módulo security está desligado na loja.{"error":"module_disabled","module":"security"}
500Falha ao listar.{"error":"failed to list blocked IPs","detail":"..."}
POST/api/v1/admin/security/blocked-ipsAdmin

Bloquear um IP

Registra o bloqueio e grava quem o fez (o administrador do token) e quando. Se o mesmo endereço já estiver na lista, a entrada existente é atualizada (motivo, vencimento e autor) e a resposta continua 201. O campo created_by enviado no corpo é ignorado.

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário (veja Tokens).

Corpo da requisição

ip_addressstringobrigatório
Endereço IPv4 ou IPv6, ou faixa em notação CIDR (203.0.113.0/24).
reasonstringobrigatório
Motivo do bloqueio, texto livre.
duration_hoursintegerpadrão: 0
Duração em horas. 0 ou omitido: bloqueio permanente.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/security/blocked-ips" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "ip_address": "198.51.100.77",
  "reason": "Tentativas de login em excesso",
  "duration_hours": 24
}'

Resposta

201Bloqueio registrado
json
{
  "id": "7d7889d2-6e29-4022-bd78-f3a6139a2951",
  "ip_address": "198.51.100.77",
  "reason": "Tentativas de login em excesso",
  "blocked_at": "2026-10-11T20:52:43.976100Z",
  "expires_at": "2026-10-12T20:52:43.975872Z",
  "created_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc"
}

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.{"error":"invalid or expired token"}
403Falta manage_security (ou manage_settings).{"error":"insufficient privileges","privilege_required_any":["manage_security","manage_settings"]}
403O módulo security está desligado na loja.{"error":"module_disabled","module":"security"}
400Corpo inválido, ip_address ou reason ausente, ou endereço que não é IP nem CIDR.{"error":"invalid IP address: nope"}
400reason ausente.{"error":"reason is required"}
500Falha ao gravar.{"error":"failed to block IP","detail":"..."}
GET/api/v1/admin/security/blocked-ips/{id}Admin

Consultar bloqueio

Devolve um bloqueio pelo id.

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário (veja Tokens).

Parâmetros de caminho

iduuidobrigatório
Id do bloqueio (UUID), o campo id devolvido na criação e na lista.

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/admin/security/blocked-ips/7d7889d2-6e29-4022-bd78-f3a6139a2951" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Bloqueio
json
{
  "id": "7d7889d2-6e29-4022-bd78-f3a6139a2951",
  "ip_address": "198.51.100.77",
  "reason": "Tentativas de login em excesso",
  "blocked_at": "2026-10-11T20:52:43.976100Z",
  "expires_at": "2026-10-12T20:52:43.975872Z",
  "created_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc"
}

Campos da resposta

iduuid
Id do bloqueio.
ip_addressstring
Endereço ou faixa bloqueada, como foi cadastrada.
reasonstring
Motivo informado.
blocked_atstring
Quando o bloqueio foi criado ou atualizado, RFC 3339 em UTC.
expires_atstring
Quando vence, RFC 3339 em UTC. Ausente no bloqueio permanente.
created_byuuid
Id do administrador que fez o bloqueio.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.{"error":"invalid or expired token"}
403Falta manage_security (ou manage_settings).{"error":"insufficient privileges","privilege_required_any":["manage_security","manage_settings"]}
403O módulo security está desligado na loja.{"error":"module_disabled","module":"security"}
404Não existe bloqueio com esse id.{"error":"blocked IP not found"}
500Falha ao ler, inclusive quando o id não é um UUID válido (a mensagem de detalhe vem em português).{"error":"failed to get blocked IP","detail":"..."}
DELETE/api/v1/admin/security/blocked-ips/{id}Admin

Remover bloqueio

Apaga o bloqueio. Não há como desfazer pela API; para bloquear de novo, crie outro. A remoção fica no registro de atividades da loja.

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário (veja Tokens).

Parâmetros de caminho

iduuidobrigatório
Id do bloqueio (UUID), o campo id devolvido na criação e na lista.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/admin/security/blocked-ips/7d7889d2-6e29-4022-bd78-f3a6139a2951" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Bloqueio removido
json
{
  "message": "IP unblocked"
}

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.{"error":"invalid or expired token"}
403Falta manage_security (ou manage_settings).{"error":"insufficient privileges","privilege_required_any":["manage_security","manage_settings"]}
403O módulo security está desligado na loja.{"error":"module_disabled","module":"security"}
404Não existe bloqueio com esse id (inclui chamar duas vezes).{"error":"blocked IP not found"}
500Falha ao remover.{"error":"failed to unblock IP","detail":"..."}

Veja também

  • Verificar IP e limpar vencidos
  • Erros da API
  • Conta do administrador
Anterior
Catálogo de privilégios
Próxima
Verificar IP e limpar vencidos
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Exemplo de requisição
  • Resposta
  • Erros
  • Exemplo de requisição
  • Resposta
  • Erros
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também