API atual/Referência completa/Conta do administrador

Verificar IP e limpar vencidos

Consulta se um IP está bloqueado agora e apaga da lista os bloqueios que já venceram.

Duas rotas de apoio ao registro de IPs bloqueados. Valem as mesmas exigências: privilégio manage_security ou manage_settings e módulo security ligado.

GET/api/v1/admin/security/check-ipAdmin

Verificar se um IP está bloqueado

Responde se existe um bloqueio vigente (permanente ou ainda não vencido) para o endereço. A comparação é por igualdade de texto.

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de consulta

ipstringobrigatório

Endereço a consultar, exatamente como foi cadastrado.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/admin/security/check-ip?ip=198.51.100.77" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200IP bloqueado

json

{
  "ip": "198.51.100.77",
  "blocked": true,
  "entry": {
    "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"
  }
}

200IP livre

json

{
  "ip": "203.0.113.9",
  "blocked": false,
  "entry": null
}

Campos da resposta

ipstring

O endereço consultado.

blockedboolean

true se há bloqueio vigente.

entryobject

O bloqueio (mesmos campos de Consultar bloqueio) ou null.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
403	Falta `manage_security` (ou `manage_settings`).	`{"error":"insufficient privileges","privilege_required_any":["manage_security","manage_settings"]}`
403	O módulo `security` está desligado na loja.	`{"error":"module_disabled","module":"security"}`
400	Parâmetro `ip` ausente.	`{"error":"ip query parameter is required"}`
500	Falha na consulta.	`{"error":"failed to check IP","detail":"..."}`

POST/api/v1/admin/security/clean-expiredAdmin

Limpar bloqueios vencidos

Apaga da lista os bloqueios cuja data de vencimento já passou e informa quantos foram removidos. Bloqueios permanentes nunca são tocados. Um bloqueio vencido já deixa de contar em check-ip; esta rota só arruma a lista.

Cabeçalhos

Authorizationstringobrigatório

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

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/security/clean-expired" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Limpeza feita

json

{
  "message": "expired blocks cleaned",
  "removed": 3
}

Campos da resposta

messagestring

Texto fixo de confirmação.

removedinteger

Quantos bloqueios vencidos foram apagados.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
403	Falta `manage_security` (ou `manage_settings`).	`{"error":"insufficient privileges","privilege_required_any":["manage_security","manage_settings"]}`
403	O módulo `security` está desligado na loja.	`{"error":"module_disabled","module":"security"}`
500	Falha ao limpar.	`{"error":"failed to clean expired blocks","detail":"..."}`

Veja também

Verificar IP e limpar vencidos

Consulta se um IP está bloqueado agora e apaga da lista os bloqueios que já venceram.

Duas rotas de apoio ao registro de IPs bloqueados. Valem as mesmas exigências: privilégio manage_security ou manage_settings e módulo security ligado.

GET/api/v1/admin/security/check-ipAdmin

Verificar se um IP está bloqueado

Responde se existe um bloqueio vigente (permanente ou ainda não vencido) para o endereço. A comparação é por igualdade de texto.

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de consulta

ipstringobrigatório

Endereço a consultar, exatamente como foi cadastrado.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/admin/security/check-ip?ip=198.51.100.77" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200IP bloqueado

json

{
  "ip": "198.51.100.77",
  "blocked": true,
  "entry": {
    "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"
  }
}

200IP livre

json

{
  "ip": "203.0.113.9",
  "blocked": false,
  "entry": null
}

Campos da resposta

ipstring

O endereço consultado.

blockedboolean

true se há bloqueio vigente.

entryobject

O bloqueio (mesmos campos de Consultar bloqueio) ou null.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
403	Falta `manage_security` (ou `manage_settings`).	`{"error":"insufficient privileges","privilege_required_any":["manage_security","manage_settings"]}`
403	O módulo `security` está desligado na loja.	`{"error":"module_disabled","module":"security"}`
400	Parâmetro `ip` ausente.	`{"error":"ip query parameter is required"}`
500	Falha na consulta.	`{"error":"failed to check IP","detail":"..."}`

POST/api/v1/admin/security/clean-expiredAdmin

Limpar bloqueios vencidos

Cabeçalhos

Authorizationstringobrigatório

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

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/security/clean-expired" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Limpeza feita

json

{
  "message": "expired blocks cleaned",
  "removed": 3
}

Campos da resposta

messagestring

Texto fixo de confirmação.

removedinteger

Quantos bloqueios vencidos foram apagados.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
403	Falta `manage_security` (ou `manage_settings`).	`{"error":"insufficient privileges","privilege_required_any":["manage_security","manage_settings"]}`
403	O módulo `security` está desligado na loja.	`{"error":"module_disabled","module":"security"}`
500	Falha ao limpar.	`{"error":"failed to clean expired blocks","detail":"..."}`