API de Proteção DDoS

API de Proteção DDoS — Visão geral e autenticação

A Fusiora DDoS Protection API é um wrapper em torno do Avoro DDoS Manager. Com ela você pode inspecionar endereços IP protegidos, revisar o histórico de ataques, anexar perfis de filtragem às IPs, gerenciar listas de IP reutilizáveis e configurar a proteção por IP.

Com ela você pode:

Inspecionar os endereços IP protegidos na sua conta.
Revisar o histórico de ataques que atingiram suas IPs.
Anexar perfis de filtragem (presets + faixas de protocolo/porta) às IPs.
Gerenciar listas de IP reutilizáveis com entradas WHITELIST / BLACKLIST / TRUST.
Configurar as definições de proteção por IP: ação padrão, modo simétrico, ASN blocklist, country blocklist.

URL base

Todos os endpoints ficam sob:

https://dpm.fusiora.com

Envie cada requisição para um caminho sob essa base, por ex. https://dpm.fusiora.com/api/attacks.

Grupos de endpoints

A API é organizada em torno dos recursos que você gerencia:

Protected IPs — /api/ips/{ip}, /api/ip/{ip}/… — Ler & configurar a proteção de uma única IP.
Filter Profiles — /api/filters, /api/ip/{ip}/profiles — Navegar pelos presets, anexá-los/desanexá-los por faixa de protocolo+porta.
IP Lists — /api/iplists, /api/iplists/{id}/entries — Listas CIDR reutilizáveis referenciadas pelos perfis.
Attacks — /api/attacks, /api/attacks/{id}/stats — Ler o histórico de ataques e estatísticas de séries temporais.

Convenções

Os corpos das requisições são JSON. Envie sempre Content-Type: application/json para requisições POST, PUT e PATCH.
As respostas bem-sucedidas retornam JSON, exceto 204 No Content para atualizações e exclusões que não têm nada a retornar.
Os erros retornam JSON com um campo error descrevendo o problema. Consulte a Referência para os códigos de status.
Os endpoints PATCH sob /api/ip/{ip}/... têm escopo de campo: leem a configuração atual da IP, alteram apenas o campo solicitado e a reescrevem. Todas as outras configurações são preservadas.

Autenticação

Cada requisição deve incluir sua chave de API pessoal no cabeçalho HTTP x-api-key. Requisições sem uma chave válida são rejeitadas com 401 Unauthorized.

x-api-key: YOUR_API_KEY

É isso — sem prefixo Bearer, sem assinatura, sem parâmetro de expiração.

Teste rápido

Uma chamada bem-sucedida a /api/attacks confirma que sua chave é válida:

curl -X GET "https://dpm.fusiora.com/api/attacks" \
  -H "x-api-key: YOUR_API_KEY"

Se a chave estiver errada ou ausente, você receberá 401:

{ "error": "Missing or invalid API key" }

Usando a chave

Envie o mesmo cabeçalho em todos os endpoints:

# GET
curl -X GET "https://dpm.fusiora.com/api/ips/85.239.155.11" \
  -H "x-api-key: YOUR_API_KEY"

# POST with body
curl -X POST "https://dpm.fusiora.com/api/iplists" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "officevpn"}'

# PATCH with body
curl -X PATCH "https://dpm.fusiora.com/api/ip/85.239.155.11/default-action" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"defaultAction": "FILTER"}'

Manter a chave secreta

Nunca a faça commit em um repositório público. Trate-a como uma senha.
Não a use a partir de JavaScript do lado do cliente rodando em um navegador — em vez disso, encaminhe as chamadas pelo seu próprio backend.
Rotacione-a se suspeitar que vazou.
Use uma chave por ambiente (produção / staging) sempre que possível.

O que a chave pode fazer

A chave está vinculada a uma conta de usuário e a uma lista fixa de IPs no lado da Avoro. Ela pode fazer tudo o que essa conta tem permissão de fazer — hoje não há scopes por chave.

Permissões e propriedade

A API é multi-tenant. Cada IP e cada lista de IP pertence a exatamente uma conta, e a API nunca permite que você cruze essa fronteira.

Quando você chama um endpoint, a API verifica:

A chave é válida? (Não → 401)
Se a URL contém uma IP — essa IP está na sua conta? (Não → 403)
Se a URL contém um ID de lista — essa lista foi criada pela sua conta? (Não → 404)

Por que 403 para IPs mas 404 para listas?

É deliberado.

As IPs têm um formato conhecido (a.b.c.d). Retornar 403 confirma que a IP existe em algum lugar, apenas não na sua conta. Tudo bem — IPs são informação pública.
Os IDs de listas de IP são identificadores numéricos internos. Retornar 403 para a lista de outra pessoa permitiria que atacantes enumerassem as listas de outros usuários tentando IDs em sequência. Por isso a API retorna 404 Not Found — indistinguível de uma lista que nunca existiu.

Mesma lógica para entradas de lista: excluir uma entrada que pertence à lista de outro usuário retorna 404.

O que você pode e não pode fazer

Você pode:

Ler qualquer IP da sua conta: GET /api/ips/{ip}.
Listar, criar, atualizar, excluir suas próprias listas de IP: /api/iplists/....
Adicionar / remover entradas nas suas próprias listas: /api/iplists/{id}/entries.
Ler ataques contra suas IPs: GET /api/attacks (os resultados são filtrados automaticamente para suas IPs).
Referenciar outra das suas próprias listas como uma entrada aninhada.

Você não pode:

Mexer em uma IP que não está na sua conta → 403.
Ler, modificar ou excluir uma lista que você não criou → 404.
Aninhar uma lista de outra pessoa dentro da sua → 400 ("nested list not found").
Excluir uma entrada por meio de uma URL de lista que não possui essa entrada → 404.

Escopo do histórico de ataques

O endpoint /api/attacks é especial: em vez de falhar com 403, ele filtra silenciosamente qualquer ataque cuja IP de destino não esteja na sua conta. Um array vazio é uma resposta válida — isso torna a paginação + filtragem seguras para chamar a partir de jobs em segundo plano sem verificações de propriedade por ataque.

Armadilhas comuns

Chave errada para o ambiente errado. IPs de produção e staging vivem em contas diferentes. Misturar chaves gera 403 confusos.
IDs de lista copiados da conta de um colega. Use os seus.
Listas aninhadas auto-referenciais. Adicionar a lista 730 como entrada dentro da lista 730 retorna 400.

Próximos passos

Protected IPs — configurar a proteção de uma única IP.
Filter Profiles — anexar presets a faixas de protocolo + porta.
IP Lists — gerenciar listas CIDR reutilizáveis.
Attack History — ler registros e estatísticas de ataques.
Reference — códigos de status, notação CIDR, tipos de ação.

Com a URL base, a autenticação por x-api-key e o modelo de propriedade claros, você está pronto para explorar o restante da documentação e começar a configurar a proteção das suas IPs.

IPs protegidos

Endpoints para inspecionar e configurar a proteção contra DDoS de um único IP atribuído à sua conta.

Todos os endpoints PATCH abaixo têm escopo de campo: leem a configuração atual do IP, alteram apenas o campo solicitado e a gravam de volta. Os limites, os perfis de filtro anexados e outras configurações são preservados.

Obter detalhes do IP

Retorna a configuração completa de um dos seus IPs protegidos.

GET /api/ips/{ip}

Parâmetro de caminho

ip (obrigatório) — Endereço IPv4 que você possui (ex.: 85.239.155.11).

Exemplo

curl -X GET "https://dpm.fusiora.com/api/ips/85.239.155.11" \
  -H "x-api-key: YOUR_API_KEY"

Resposta (200 OK)

{
  "ID": 1234,
  "Ipv4": "85.239.155.11",
  "Description": "Game server #1",
  "Enabled": true,
  "DefaultAction": "FILTER",
  "SymmetricMode": "FULL",
  "CountryBlockMode": 0,
  "CountryBlockList": [],
  "AsnBlockMode": 0,
  "AsnBlockList": [],
  "SynThreshold": 50000,
  "UdpThreshold": 50000
}

Limites de proteção adicionais podem aparecer na resposta — aqui são somente leitura. Use os endpoints PATCH dedicados abaixo para alterar configurações individuais.

Erros: 401 chave inválida · 403 IP não está na sua conta · 500 falha upstream.

Ação padrão

A ação padrão decide o que acontece com o tráfego em portas que não têm um perfil de filtro específico. É, na prática, a regra geral de um IP.

PATCH /api/ip/{ip}/default-action

Corpo

{ "defaultAction": "FILTER" }

Valores

ACCEPT — Proteção contra DDoS desativada. Apenas portas com um perfil de filtro são protegidas. Use se você gerencia a proteção por conta própria — raro.
FILTER — Proteção padrão em todas as portas. Padrão recomendado. Configuração normal para servidores de produção.
DROP — Descarta todo o tráfego. Apenas portas com um filtro anexado deixam o tráfego passar. Botão de emergência: resposta a incidentes, manutenção, configurações de lista de permissões estrita.

Exemplos

# Standard protection (recommended)
curl -X PATCH "https://dpm.fusiora.com/api/ip/85.239.155.11/default-action" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"defaultAction": "FILTER"}'

# Killswitch
curl -X PATCH "https://dpm.fusiora.com/api/ip/85.239.155.11/default-action" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"defaultAction": "DROP"}'

# Disable protection (accept all)
curl -X PATCH "https://dpm.fusiora.com/api/ip/85.239.155.11/default-action" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"defaultAction": "ACCEPT"}'

Resposta (200 OK)

{ "success": true, "message": "Default action set to FILTER", "data": {} }

Erros: 400 valor inválido · 401 chave inválida · 403 o IP não é seu · 500 falha upstream.

Proteção simétrica

Filtro com estado que exige que cada conexão se comporte de forma consistente em ambas as direções. Eficaz contra tráfego falsificado, já que pacotes falsificados nunca recebem tráfego de resposta correspondente.

PATCH /api/ip/{ip}/symmetric

Corpo

{ "symmetricMode": "FULL" }

Valores

FULL — Aplica inspeção simétrica. Fluxos assimétricos são desafiados ou descartados. Recomendado.
DISABLED — Não aplica roteamento simétrico. Use apenas se a sua rede for intencionalmente assimétrica.

Exemplos

# Enable (recommended)
curl -X PATCH "https://dpm.fusiora.com/api/ip/85.239.155.11/symmetric" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"symmetricMode": "FULL"}'

# Disable
curl -X PATCH "https://dpm.fusiora.com/api/ip/85.239.155.11/symmetric" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"symmetricMode": "DISABLED"}'

Resposta (200 OK)

{ "success": true, "message": "Symmetric mode set to FULL", "data": {} }

Erros: 400 valor inválido · 401 chave inválida · 403 o IP não é seu · 500 falha upstream.

Lista de bloqueio de ASN

Filtra o tráfego por ASN de origem (Autonomous System Number). Útil para bloquear redes abusivas ou restringir um IP ao ASN de um provedor de nuvem específico.

A lista tem limite de 20 ASNs por IP e funciona como blacklist ou whitelist.

PATCH /api/ip/{ip}/asn-blocklist

Corpo

{
  "asnBlockMode": 1,
  "asnBlockList": [12345, 67890]
}

Modos

0 — Disabled — A filtragem por ASN está desligada. asnBlockList é ignorada.
1 — Blacklist — O tráfego dos ASNs listados é bloqueado. Todo o restante é permitido.
2 — Whitelist — Apenas o tráfego dos ASNs listados é permitido. Todo o restante é bloqueado.

Envie ambos os campos juntos. Os números de ASN são inteiros entre 1 e 4,294,967,295. Sem prefixo AS — envie 13335, não "AS13335". Duplicatas são removidas no servidor.

Exemplos

# Block two networks
curl -X PATCH "https://dpm.fusiora.com/api/ip/85.239.155.11/asn-blocklist" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"asnBlockMode": 1, "asnBlockList": [12345, 67890]}'

# Whitelist only Cloudflare (AS13335)
curl -X PATCH "https://dpm.fusiora.com/api/ip/85.239.155.11/asn-blocklist" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"asnBlockMode": 2, "asnBlockList": [13335]}'

# Disable
curl -X PATCH "https://dpm.fusiora.com/api/ip/85.239.155.11/asn-blocklist" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"asnBlockMode": 0, "asnBlockList": []}'

Resposta (200 OK)

{ "success": true, "message": "ASN blocklist updated", "data": {} }

Erros: 400 modo inválido / lista não é array / >20 entradas / ASN inválido · 401 chave inválida · 403 o IP não é seu · 500 falha upstream.

Lista de bloqueio de países

Filtra o tráfego por país de origem (GeoIP). A lista tem limite de 20 países por IP e usa códigos ISO 3166-1 alpha-2.

PATCH /api/ip/{ip}/country-blocklist

Corpo

{
  "countryBlockMode": 1,
  "countryBlockList": ["CN", "RU", "KP"]
}

Modos

0 — Disabled — A filtragem por país está desligada. countryBlockList é ignorada.
1 — Blacklist — O tráfego dos países listados é bloqueado. Todo o restante é permitido.
2 — Whitelist — Apenas o tráfego dos países listados é permitido. Todo o restante é bloqueado.

Os códigos não diferenciam maiúsculas de minúsculas na entrada e são armazenados em maiúsculas ("cz" torna-se "CZ"). Duplicatas são removidas no servidor.

Exemplos

# Block three countries
curl -X PATCH "https://dpm.fusiora.com/api/ip/85.239.155.11/country-blocklist" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"countryBlockMode": 1, "countryBlockList": ["CN", "RU", "KP"]}'

# Whitelist Czechia and Slovakia only
curl -X PATCH "https://dpm.fusiora.com/api/ip/85.239.155.11/country-blocklist" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"countryBlockMode": 2, "countryBlockList": ["CZ", "SK"]}'

# Disable
curl -X PATCH "https://dpm.fusiora.com/api/ip/85.239.155.11/country-blocklist" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"countryBlockMode": 0, "countryBlockList": []}'

Resposta (200 OK)

{ "success": true, "message": "Country blocklist updated", "data": {} }

Códigos de país comuns

Códigos ISO 3166-1 alpha-2 usados com frequência:

CZ — República Tcheca
RU — Rússia
SK — Eslováquia
CN — China
DE — Alemanha
UA — Ucrânia
US — Estados Unidos
IN — Índia
GB — Reino Unido
BR — Brasil
FR — França
JP — Japão
PL — Polônia
KR — Coreia do Sul
NL — Países Baixos
AU — Austrália

Erros: 400 modo inválido / lista não é array / >20 entradas / código inválido · 401 chave inválida · 403 o IP não é seu · 500 falha upstream.

Combine esses endpoints para ajustar a proteção por IP — defina uma ação padrão sensata, aplique inspeção simétrica e restrinja o acesso com listas de ASN e de países conforme o seu tráfego exigir.

Perfis de Filtro

Um preset de filtro é um conjunto de regras nomeado preparado pela Fusiora (ajustado para FiveM, tráfego web, DNS, etc.). Para usar um, você o vincula a um IP como um perfil de filtro associado a um protocolo e a uma faixa de portas específicos.

Um perfil é a combinação de:

Um preset (o conjunto de regras).
Um protocolo (UDP, TCP, ICMP).
Uma faixa de portas de destino (minDstPort – maxDstPort, ambos inclusive).

Você pode vincular vários perfis a um único IP — um por serviço.

Listar presets disponíveis

GET /api/filters

Sem parâmetros de caminho ou de consulta.

Exemplo

curl -X GET "https://dpm.fusiora.com/api/filters" \
  -H "x-api-key: YOUR_API_KEY"

Resposta (200 OK)

[
  { "id": 42, "name": "GameUDP", "protocol": "UDP" },
  { "id": 43, "name": "WebTCP",  "protocol": "TCP" },
  { "id": 44, "name": "DNS",     "protocol": "UDP" }
]

Cada entrada expõe exatamente o que você precisa para vincular um perfil:

id — use isto como presetId ao vincular.
name — nome de exibição, útil para logs e painéis.
protocol — protocolo para o qual este preset foi construído. Deve corresponder ao protocol que você envia.

Erros: 401 chave inválida · 500 falha upstream.

Listar perfis vinculados a um IP

GET /api/ip/{ip}/profiles

Exemplo

curl -X GET "https://dpm.fusiora.com/api/ip/85.239.155.11/profiles" \
  -H "x-api-key: YOUR_API_KEY"

Resposta (200 OK)

[
  {
    "ID": 5511,
    "PresetID": 42,
    "PresetName": "GameUDP",
    "Protocol": "UDP",
    "MinDstPort": 30120,
    "MaxDstPort": 30130,
    "Notes": "FiveM"
  }
]

Erros: 401 chave inválida · 403 IP não é seu · 500 falha upstream.

Vincular um perfil

POST /api/ip/{ip}/profiles

Corpo

{
  "presetId": 42,
  "protocol": "UDP",
  "minDstPort": 30120,
  "maxDstPort": 30130,
  "notes": "FiveM server"
}

presetId (obrigatório) — ID de GET /api/filters.
protocol (obrigatório) — nome do protocolo, normalmente UDP, TCP ou ICMP. Deve corresponder ao protocolo do preset.
minDstPort (obrigatório) — limite inferior das portas de destino, inclusive (0 – 65535).
maxDstPort (obrigatório) — limite superior, inclusive (0 – 65535). Deve ser >= minDstPort.
notes (opcional) — nota de formato livre (string, pode estar vazia).

Exemplo — servidor de jogo FiveM

curl -X POST "https://dpm.fusiora.com/api/ip/85.239.155.11/profiles" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "presetId": 42,
    "protocol": "UDP",
    "minDstPort": 30120,
    "maxDstPort": 30130,
    "notes": "FiveM"
  }'

Resposta (200 OK)

{
  "ID": 5512,
  "PresetID": 42,
  "Protocol": "UDP",
  "MinDstPort": 30120,
  "MaxDstPort": 30130,
  "Notes": "FiveM server"
}

Salve o ID — você precisará dele para excluir o perfil mais tarde.

Erros: 401 chave inválida · 403 IP não é seu · 500 rejeição upstream — preset inválido, perfil sobreposto, protocolo incompatível. A mensagem de erro inclui o motivo upstream.

Excluir um perfil

DELETE /api/ip/{ip}/profiles/{profileId}

O perfil deve pertencer ao IP indicado na URL — perfis vinculados a um IP diferente não podem ser excluídos por este caminho.

Exemplo

curl -X DELETE "https://dpm.fusiora.com/api/ip/85.239.155.11/profiles/5512" \
  -H "x-api-key: YOUR_API_KEY"

Resposta (200 OK)

{
  "success": true,
  "message": "Profile 5512 deleted from IP 85.239.155.11",
  "data": {}
}

Erros: 401 chave inválida · 403 IP não é seu · 404 o perfil não pertence a este IP · 500 falha upstream.

Os perfis de filtro são a forma de aplicar as regras de proteção da Fusiora exatamente onde você precisa, serviço por serviço, em cada um dos seus IPs.

Listas de IP

As listas de IP são coleções nomeadas e reutilizáveis de endereços CIDR que pode referenciar a partir de perfis de proteção DDoS. Em vez de duplicar o mesmo conjunto de IPs em muitos filtros, mantém uma única lista e atualiza-a num só lugar.

Porquê usá-las

DRY. Uma alteração atualiza todos os filtros que referenciam a lista.
Combináveis. As listas podem incluir outras listas como entradas — construa uma hierarquia (p. ex. partners → acme-corp + globex).
Expiração por entrada. As entradas de endereço podem remover-se automaticamente após N segundos — perfeito para banimentos temporários.

Tipos de ação

Cada entrada tem uma ipListAction. Decide o que a camada de proteção faz quando o tráfego corresponde.

WHITELIST — O tráfego é sempre permitido, mesmo quando outras regras o bloqueariam. Use para parceiros de confiança ou serviços de monitorização. Predefinição se não definir nenhuma.
BLACKLIST — O tráfego é sempre descartado. Use para atacantes conhecidos ou bloqueios detalhados onde a filtragem por país/ASN é demasiado ampla.
TRUST — O tráfego ignora completamente toda a filtragem DDoS. Use apenas para infraestrutura interna ou redes sobre as quais tem controlo total.

Tenha cuidado com TRUST. É um bypass, não apenas uma regra de permissão. Use com moderação.

Propriedade

Cada lista pertence ao utilizador que a criou.
Só pode ver, modificar ou eliminar as listas que você criou.
As listas de outros utilizadores são reportadas como 404 Not Found — não 403 — para que os IDs de lista não possam ser enumerados.
As referências a listas aninhadas devem apontar para uma lista que também lhe pertença.

Aninhamento

Uma lista pode conter outra lista como entrada:

{ "listId": 729, "ipListAction": "BLACKLIST" }

Duas regras importantes:

Sem auto-referência. Adicionar a lista 730 como entrada da lista 730 devolve 400.
Sem referências entre utilizadores. A lista aninhada tem de ser sua.

Se eliminar uma lista que outra das suas listas referenciava, a referência torna-se inativa — a lista pai não dá erro, apenas deixa de corresponder ao que a filha costumava fornecer.

Limites e quotas

Máx. de entradas por lista: 1 – 1,000,000, configurável via maxEntries. Predefinição: 1000.
Formato do nome da lista: apenas 1-64 caracteres alfanuméricos — sem espaços, hífens ou sublinhados.
Descrição da lista: até 500 caracteres.

Criar uma lista

POST /api/iplists

Corpo

{
  "name": "officevpn",
  "description": "Allowed IPs for office VPN",
  "maxEntries": 1000
}

name (obrigatório) — 1-64 caracteres alfanuméricos (a-z, A-Z, 0-9). Sem espaços, hífens ou sublinhados.
description (opcional) — Texto livre até 500 caracteres.
maxEntries (opcional) — 1 – 1,000,000. Predefinição: 1000.

Exemplos

# Minimal
curl -X POST "https://dpm.fusiora.com/api/iplists" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "officevpn"}'

# Full
curl -X POST "https://dpm.fusiora.com/api/iplists" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "blockedasns", "description": "Known bad networks", "maxEntries": 5000}'

Resposta (201 Created)

{
  "ID": 730,
  "Name": "officevpn",
  "Description": "Allowed IPs for office VPN",
  "MaxEntries": 1000,
  "EntryCount": 0,
  "CreatedAt": "2026-05-13T10:00:00Z"
}

Guarde o ID — irá precisar dele para qualquer outra operação nesta lista.

Listar as suas listas

GET /api/iplists

Parâmetros de consulta

includeItems (opcional) — "true" para incluir as entradas em linha. Omita ou use "false" apenas para metadados.

Exemplos

# Metadata only
curl -X GET "https://dpm.fusiora.com/api/iplists" \
  -H "x-api-key: YOUR_API_KEY"

# With entries
curl -X GET "https://dpm.fusiora.com/api/iplists?includeItems=true" \
  -H "x-api-key: YOUR_API_KEY"

Resposta (200 OK)

[
  {
    "ID": 730,
    "Name": "officevpn",
    "Description": "Allowed IPs for office VPN",
    "MaxEntries": 1000,
    "EntryCount": 3,
    "CreatedAt": "2026-05-13T10:00:00Z",
    "UpdatedAt": "2026-05-13T10:05:00Z"
  }
]

As listas pertencentes a outros utilizadores nunca são devolvidas.

Obter uma lista

GET /api/iplists/{id}

Devolve os detalhes completos e as entradas de uma única lista que possua.

curl -X GET "https://dpm.fusiora.com/api/iplists/730" \
  -H "x-api-key: YOUR_API_KEY"

Devolve 404 se a lista não existir ou se não for sua.

Atualizar uma lista

PUT /api/iplists/{id}

Atualiza o name, a description ou o maxEntries da lista. Para alterar as próprias entradas, use os endpoints de entradas abaixo.

Corpo

{
  "name": "officevpn",
  "description": "Updated description",
  "maxEntries": 2000
}

Exemplos

# Rename
curl -X PUT "https://dpm.fusiora.com/api/iplists/730" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "officevpnv2"}'

# Increase capacity
curl -X PUT "https://dpm.fusiora.com/api/iplists/730" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "officevpn", "maxEntries": 5000}'

Resposta: 204 No Content. O corpo está vazio em caso de sucesso.

Eliminar uma lista

DELETE /api/iplists/{id}

Elimina permanentemente a lista e todas as suas entradas. Qualquer referência de perfil ou de lista aninhada torna-se inativa, por isso verifique a utilização primeiro.

curl -X DELETE "https://dpm.fusiora.com/api/iplists/730" \
  -H "x-api-key: YOUR_API_KEY"

Resposta: 204 No Content.

Listar entradas

GET /api/iplists/{id}/entries

curl -X GET "https://dpm.fusiora.com/api/iplists/730/entries" \
  -H "x-api-key: YOUR_API_KEY"

Resposta (200 OK)

[
  {
    "ID": 4501,
    "address": "203.0.113.5/32",
    "ipListAction": "WHITELIST",
    "expireAfterSec": 0,
    "ipListID": 730
  },
  {
    "ID": 4502,
    "address": "198.51.100.0/24",
    "ipListAction": "BLACKLIST",
    "ipListID": 730
  }
]

Adicionar uma entrada

POST /api/iplists/{id}/entries

Uma entrada é ou um endereço (CIDR) ou uma lista aninhada (listId). Forneça exatamente um desses campos por entrada — nunca ambos, nunca nenhum.

Corpo — entrada IP/CIDR

{
  "address": "203.0.113.5/32",
  "ipListAction": "WHITELIST",
  "expireAfterSec": 3600
}

Corpo — referência de lista aninhada

{
  "listId": 729,
  "ipListAction": "BLACKLIST"
}

address (um de address/listId) — Um CIDR válido. IPs únicos devem ser /32 (IPv4) ou /128 (IPv6). Zeros à esquerda são rejeitados (01.2.3.4/32 é inválido).
listId (um de address/listId) — ID de outra lista de IP que possua. Não pode ser igual à lista pai. Não pode referenciar uma lista que não possua.
ipListAction (opcional) — WHITELIST, BLACKLIST ou TRUST. Predefinição: WHITELIST.
expireAfterSec (opcional, apenas endereço) — Remove a entrada automaticamente após N segundos. Inteiro não negativo. Ignorado em entradas de lista aninhada.

Exemplos

# Allow a single IP forever
curl -X POST "https://dpm.fusiora.com/api/iplists/730/entries" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"address": "203.0.113.5/32", "ipListAction": "WHITELIST"}'

# Block a /24 subnet
curl -X POST "https://dpm.fusiora.com/api/iplists/730/entries" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"address": "198.51.100.0/24", "ipListAction": "BLACKLIST"}'

# Temporary block — auto-expires in 1 hour
curl -X POST "https://dpm.fusiora.com/api/iplists/730/entries" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"address": "192.0.2.10/32", "ipListAction": "BLACKLIST", "expireAfterSec": 3600}'

# Include another of your lists (nested)
curl -X POST "https://dpm.fusiora.com/api/iplists/730/entries" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"listId": 729, "ipListAction": "BLACKLIST"}'

Resposta (201 Created)

{
  "ID": 4503,
  "address": "203.0.113.5/32",
  "ipListAction": "WHITELIST",
  "expireAfterSec": 3600,
  "ipListID": 730
}

Eliminar uma entrada

DELETE /api/iplists/{id}/entries/{entryId}

A entrada tem de pertencer à lista nomeada no URL — mesmo que conheça um ID de entrada de uma lista diferente (sua ou de outra pessoa), não pode ser eliminada através do pai errado.

curl -X DELETE "https://dpm.fusiora.com/api/iplists/730/entries/4503" \
  -H "x-api-key: YOUR_API_KEY"

Resposta: 204 No Content.

Erros comuns

400 — ID de lista, formato de nome, comprimento de descrição ou intervalo de maxEntries inválidos.
400 — address e listId enviados ambos — ou nenhum. Envie exatamente um.
400 — address não é um CIDR válido — verifique os zeros à esquerda.
400 — ipListAction não é WHITELIST / BLACKLIST / TRUST.
400 — expireAfterSec é negativo ou não é um inteiro.
400 — listId é igual ao ID da lista pai — auto-referência.
400 — A lista aninhada referenciada não existe ou não é sua.
401 — Chave de API em falta ou inválida.
404 — A lista não existe ou não é sua — mesma resposta de propósito, consulte Primeiros passos.

Com as listas de IP centraliza a gestão de endereços de confiança e bloqueados num único lugar reutilizável, mantendo os seus perfis de proteção limpos e consistentes.

Histórico de ataques

Leia o histórico de ataques contra os seus IPs protegidos e obtenha estatísticas de séries temporais de qualquer ataque específico.

Os resultados são automaticamente limitados aos IPs atribuídos à sua conta — pode chamar estes endpoints livremente sem se preocupar com a fuga de dados de outros inquilinos.

Obter o histórico de ataques

Devolve a lista de ataques que atingiram os seus IPs protegidos.

GET /api/attacks

Parâmetros de consulta

page (não) — Número de página para a paginação.
query (não) — Filtro de texto livre encaminhado para a Avoro (por ex. tipo de ataque ou IP).

Exemplos

# Latest attacks (page 1)
curl -X GET "https://dpm.fusiora.com/api/attacks" \
  -H "x-api-key: YOUR_API_KEY"

# Paginated
curl -X GET "https://dpm.fusiora.com/api/attacks?page=2" \
  -H "x-api-key: YOUR_API_KEY"

# Filtered (e.g. only UDP floods)
curl -X GET "https://dpm.fusiora.com/api/attacks?query=UDP" \
  -H "x-api-key: YOUR_API_KEY"

Resposta (200 OK)

[
  {
    "ID": 88123,
    "DstAddressString": "85.239.155.11",
    "Type": "UDP_FLOOD",
    "Bps": 12500000000,
    "Pps": 8500000,
    "StartedAt": "2026-05-13T09:14:22Z",
    "EndedAt": "2026-05-13T09:18:55Z"
  }
]

Cada item é um evento de ataque separado:

ID — Use-o para obter as estatísticas (secção seguinte).
DstAddressString — O IP que foi alvo. Sempre um dos seus.
Type — Classificação do ataque (por ex. UDP_FLOOD, SYN_FLOOD, …).
Bps — Largura de banda de pico em bits por segundo.
Pps — Taxa de pacotes de pico em pacotes por segundo.
StartedAt — Marca temporal ISO 8601 de quando o ataque começou.
EndedAt — Marca temporal ISO 8601 de quando o ataque terminou.

Um array vazio é uma resposta perfeitamente válida — significa apenas que nenhum ataque correspondeu.

Erros: 401 chave inválida · 500 falha upstream (o corpo inclui um debugId — cite-o nos tickets de suporte).

Obter estatísticas de ataques

Devolve estatísticas de séries temporais — amostras de largura de banda e taxa de pacotes — para um evento de ataque específico. Use-as para representar graficamente como um ataque aumentou e diminuiu.

GET /api/attacks/{id}/stats

id (sim) — ID numérico do ataque obtido de GET /api/attacks.

Exemplo

curl -X GET "https://dpm.fusiora.com/api/attacks/88123/stats" \
  -H "x-api-key: YOUR_API_KEY"

Resposta (200 OK)

{
  "AttackID": 88123,
  "Samples": [
    { "T": "2026-05-13T09:14:22Z", "Bps": 8000000000,  "Pps": 6500000 },
    { "T": "2026-05-13T09:14:32Z", "Bps": 12500000000, "Pps": 8500000 }
  ]
}

Cada amostra é uma observação individual:

T — Marca temporal ISO 8601 da amostra.
Bps — Largura de banda nesse momento, em bits por segundo.
Pps — Taxa de pacotes nesse momento, em pacotes por segundo.

A cadência entre amostras depende da duração do ataque e da amostragem upstream — não assuma intervalos fixos ao criar gráficos.

Erros: 401 chave inválida · 500 falha upstream.

Com estes dois endpoints pode reconstruir tanto a visão geral dos ataques recentes como o detalhe minuto a minuto de qualquer um deles.

Referência da API

Material de consulta que apoia o restante da documentação da API: os códigos de status HTTP que a API retorna e a notação CIDR usada em cada entrada de IP.

Códigos de status HTTP

A API da Fusiora usa códigos de status HTTP padrão. Abaixo: cada código que a API retorna, quando você o verá e o que fazer.

Sucesso

200 OK — Requisição bem-sucedida. O corpo da resposta contém o resultado.
201 Created — Um novo recurso foi criado. Retornado por POST /api/iplists e POST /api/iplists/{id}/entries.
204 No Content — Atualização ou exclusão bem-sucedida. O corpo da resposta está vazio — não tente analisá-lo como JSON.

Erros do cliente

400 Bad Request — O corpo ou a consulta da requisição está malformado. O campo error descreve o problema. Corrija a carga útil. Verifique os enums, tamanhos de array e formatos de valor (CIDR, códigos de país ISO).
401 Unauthorized — O cabeçalho x-api-key está ausente ou é desconhecido. Adicione o cabeçalho. Verifique se a chave tem espaços no final ou ambiente errado.
403 Forbidden — A chave é válida, mas o IP na URL não está atribuído à sua conta. Use apenas IPs atribuídos à sua conta.
404 Not Found — O recurso não existe — ou não pertence a você. Erros de propriedade em listas de IP são reportados como 404 por design para impedir a enumeração de IDs. Verifique se o recurso existe e se foi você quem o criou.

Erros do servidor

500 Internal Server Error — A API upstream Avoro falhou. O campo error inclui detalhes. Erros do histórico de ataques incluem um debugId. Tente novamente com recuo exponencial. Se persistir, contate o suporte com o debugId.
502 Bad Gateway — O Avoro upstream retornou uma resposta inesperada. Tente novamente. Se persistir, contate o suporte.

Árvore de decisão rápida

Quando você receber uma resposta que não seja de sucesso:

400? Leia o campo error — ele informa a falha de validação exata. Não tente novamente sem corrigir a carga útil.
401? Não tente novamente — corrija seu cabeçalho.
403? O IP não é seu. Verifique a URL.
404? O recurso está ausente ou não pertence a você. Verifique novamente o ID.
500 / 502? Tente novamente com recuo exponencial. Contate o suporte se persistir.

Formato da resposta de erro

Todos os erros compartilham o mesmo formato JSON:

{ "error": "Description of what went wrong" }

Algumas respostas 500 incluem campos extras:

{
  "error": "Upstream API failed",
  "debugId": "abc123-xyz"
}

Cite o debugId ao contatar o suporte — é a forma mais rápida de localizarmos sua falha específica.

Notação CIDR

Cada entrada de IP na API da Fusiora é fornecida em notação CIDR (Classless Inter-Domain Routing): address/prefix. O prefixo é o número de bits iniciais que o endereço compartilha.

Um único IP é /32 para IPv4 ou /128 para IPv6. Não existe formato de "IP nu"; sempre inclua o prefixo.

Referência rápida IPv4

1.2.3.4/32 — apenas 1.2.3.4 — 1 endereço.
192.168.1.0/24 — 192.168.1.0 – 192.168.1.255 — 256 endereços.
10.0.0.0/16 — 10.0.0.0 – 10.0.255.255 — 65 536 endereços.
10.0.0.0/8 — 10.0.0.0 – 10.255.255.255 — ~16,7 M de endereços.
0.0.0.0/0 — Todo o IPv4 — extrema cautela.

Referência rápida IPv6

2001:db8::1/128 — Um único endereço IPv6.
2001:db8::/32 — Uma alocação típica de ISP — milhões de /48.
2001:db8::/48 — Um único site / cliente.

Regras que a API impõe

Sempre inclua o prefixo. Até IPs individuais precisam de /32 ou /128. 1.2.3.4 sozinho é rejeitado.
Sem zeros à esquerda nos octetos. 01.2.3.4/32 é inválido. Use 1.2.3.4/32.
IPv6 deve estar no formato válido RFC 4291. A forma abreviada compacta :: é aceitável; dígitos hexadecimais em maiúsculas ou minúsculas são ambos aceitos.

Padrões comuns

Permitir o IP estático do seu escritório — 203.0.113.5/32
Bloquear um /24 abusivo inteiro — 198.51.100.0/24
Permitir toda a sua faixa de VPC da AWS — 10.0.0.0/16
Host IPv6 único — 2001:db8::1/128

Onde o CIDR aparece na API

As strings CIDR aparecem no campo address das entradas de listas de IP — veja Listas de IP.

A filtragem por país e ASN usa códigos de país e números de ASN — eles não aceitam CIDR. Veja IPs protegidos para isso.

Atalho mental

Quanto menor o número do prefixo, maior a faixa:

/32 = 1 endereço (o menor possível).
/24 = 256 endereços (uma sub-rede "Classe C" típica).
/16 = 65 536 endereços.
/8 = ~16,7 milhões de endereços.
/0 = toda a internet.

Em caso de dúvida, use uma calculadora CIDR online para verificar sua faixa.