API de Protección DDoS

API de Protección DDoS — Resumen y autenticación

La Fusiora DDoS Protection API es un wrapper sobre el Avoro DDoS Manager. Con ella puedes inspeccionar direcciones IP protegidas, revisar el historial de ataques, adjuntar perfiles de filtrado a las IP, gestionar listas de IP reutilizables y configurar la protección por IP.

Con esta API puedes:

Inspeccionar las direcciones IP protegidas de tu cuenta.
Revisar el historial de ataques que alcanzaron tus IP.
Adjuntar perfiles de filtrado (presets + rangos de protocolo/puerto) a las IP.
Gestionar listas de IP reutilizables con entradas WHITELIST / BLACKLIST / TRUST.
Configurar ajustes de protección por IP: acción por defecto, modo simétrico, ASN blocklist, country blocklist.

URL base

Todos los endpoints están bajo:

https://dpm.fusiora.com

Envía cada solicitud a una ruta bajo esa base, por ejemplo https://dpm.fusiora.com/api/attacks.

Grupos de endpoints

La API se organiza en torno a los recursos que gestionas:

Protected IPs — /api/ips/{ip}, /api/ip/{ip}/… — Leer y configurar la protección de una sola IP.
Filter Profiles — /api/filters, /api/ip/{ip}/profiles — Explorar presets y adjuntarlos/desadjuntarlos por rango de protocolo+puerto.
IP Lists — /api/iplists, /api/iplists/{id}/entries — Listas CIDR reutilizables referenciadas por los perfiles.
Attacks — /api/attacks, /api/attacks/{id}/stats — Leer el historial de ataques y estadísticas de series temporales.

Convenciones

Los cuerpos de las solicitudes son JSON. Envía siempre Content-Type: application/json en las solicitudes POST, PUT y PATCH.
Las respuestas correctas devuelven JSON, excepto 204 No Content para actualizaciones y eliminaciones que no tienen nada que devolver.
Los errores devuelven JSON con un campo error que describe el problema. Consulta la Referencia para los códigos de estado.
Los endpoints PATCH bajo /api/ip/{ip}/... están acotados a un campo: leen la configuración actual de la IP, cambian solo el campo solicitado y la reescriben. Todos los demás ajustes se conservan.

Autenticación

Cada solicitud debe incluir tu clave API personal en la cabecera HTTP x-api-key. Las solicitudes sin una clave válida se rechazan con 401 Unauthorized.

x-api-key: YOUR_API_KEY

Eso es todo: sin prefijo Bearer, sin firma, sin parámetro de expiración.

Prueba rápida

Una llamada correcta a /api/attacks confirma que tu clave es válida:

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

Si la clave es incorrecta o falta, obtendrás 401:

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

Uso de la clave

Envía la misma cabecera en todos los 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"}'

Mantener la clave en secreto

Nunca la subas a un repositorio público. Trátala como una contraseña.
No la uses desde JavaScript del lado del cliente que se ejecuta en un navegador — en su lugar, enruta las llamadas a través de tu propio backend.
Rótala si sospechas que se ha filtrado.
Usa una clave por entorno (producción / staging) siempre que sea posible.

Qué puede hacer la clave

La clave está vinculada a una cuenta de usuario y a una lista fija de IP en el lado de Avoro. Puede hacer todo lo que esa cuenta tenga permitido — hoy no hay scopes por clave.

Permisos y propiedad

La API es multi-tenant. Cada IP y cada lista de IP pertenece a exactamente una cuenta, y la API nunca te permite cruzar esa frontera.

Cuando llamas a un endpoint, la API comprueba:

¿Es válida la clave? (No → 401)
Si la URL contiene una IP, ¿está esa IP en tu cuenta? (No → 403)
Si la URL contiene un ID de lista, ¿fue creada esa lista por tu cuenta? (No → 404)

¿Por qué 403 para IP pero 404 para listas?

Es deliberado.

Las IP tienen una forma conocida (a.b.c.d). Devolver 403 confirma que la IP existe en algún lugar, solo que no en tu cuenta. Eso está bien — las IP son información pública.
Los ID de listas de IP son identificadores numéricos internos. Devolver 403 por la lista de otra persona permitiría a los atacantes enumerar las listas de otros usuarios probando IDs en secuencia. Por eso la API devuelve 404 Not Found — indistinguible de una lista que nunca existió.

La misma lógica para las entradas de lista: eliminar una entrada que pertenece a la lista de otro usuario devuelve 404.

Qué puedes y qué no puedes hacer

Puedes:

Leer cualquier IP de tu cuenta: GET /api/ips/{ip}.
Listar, crear, actualizar, eliminar tus propias listas de IP: /api/iplists/....
Añadir / eliminar entradas en tus propias listas: /api/iplists/{id}/entries.
Leer ataques contra tus IP: GET /api/attacks (los resultados se filtran automáticamente a tus IP).
Referenciar otra de tus propias listas como una entrada anidada.

No puedes:

Tocar una IP que no está en tu cuenta → 403.
Leer, modificar o eliminar una lista que no creaste → 404.
Anidar una lista de otra persona dentro de la tuya → 400 ("nested list not found").
Eliminar una entrada a través de una URL de lista que no posee esa entrada → 404.

Alcance del historial de ataques

El endpoint /api/attacks es especial: en lugar de fallar con 403, filtra silenciosamente cualquier ataque cuya IP de destino no esté en tu cuenta. Un array vacío es una respuesta válida — esto hace que la paginación + filtrado sea seguro de llamar desde trabajos en segundo plano sin comprobaciones de propiedad por ataque.

Errores comunes

Clave equivocada para el entorno equivocado. Las IP de producción y staging viven en cuentas diferentes. Mezclar claves produce 403 confusos.
ID de listas copiados de la cuenta de un compañero. Usa los tuyos.
Listas anidadas auto-referenciales. Añadir la lista 730 como entrada dentro de la lista 730 devuelve 400.

Próximos pasos

Protected IPs — configura la protección de una sola IP.
Filter Profiles — adjunta presets a rangos de protocolo + puerto.
IP Lists — gestiona listas CIDR reutilizables.
Attack History — lee registros y estadísticas de ataques.
Reference — códigos de estado, notación CIDR, tipos de acción.

Con la URL base, la autenticación por x-api-key y el modelo de propiedad claros, ya estás listo para explorar el resto de la documentación y empezar a configurar la protección de tus IP.

IPs protegidas

Endpoints para inspeccionar y configurar la protección DDoS de una sola IP asignada a tu cuenta.

Todos los endpoints PATCH de abajo tienen alcance de campo: leen la configuración actual de la IP, cambian solo el campo solicitado y la vuelven a guardar. Los umbrales, los perfiles de filtro adjuntos y otros ajustes se conservan.

Obtener detalles de la IP

Devuelve la configuración completa de una de tus IPs protegidas.

GET /api/ips/{ip}

Parámetro de ruta

ip (obligatorio) — Dirección IPv4 de tu propiedad (p. ej. 85.239.155.11).

Ejemplo

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

Respuesta (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
}

Pueden aparecer umbrales de protección adicionales en la respuesta: aquí son de solo lectura. Usa los endpoints PATCH dedicados de abajo para cambiar ajustes individuales.

Errores: 401 clave no válida · 403 la IP no está en tu cuenta · 500 fallo aguas arriba.

Acción predeterminada

La acción predeterminada decide qué ocurre con el tráfico en puertos que no tienen un perfil de filtro específico. Es, en la práctica, la regla general de una IP.

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

Cuerpo

{ "defaultAction": "FILTER" }

Valores

ACCEPT — Protección DDoS desactivada. Solo se protegen los puertos con un perfil de filtro. Úsalo si gestionas la protección tú mismo: poco habitual.
FILTER — Protección estándar en todos los puertos. Predeterminado recomendado. Ajuste normal para servidores de producción.
DROP — Descarta todo el tráfico. Solo dejan pasar tráfico los puertos con un filtro adjunto. Interruptor de emergencia: respuesta a incidentes, mantenimiento, configuraciones de lista de permitidos estricta.

Ejemplos

# 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"}'

Respuesta (200 OK)

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

Errores: 400 valor no válido · 401 clave no válida · 403 la IP no es tuya · 500 fallo aguas arriba.

Protección simétrica

Filtro con estado que exige que cada conexión se comporte de forma coherente en ambas direcciones. Eficaz contra el tráfico suplantado, ya que los paquetes suplantados nunca reciben tráfico de respuesta coincidente.

PATCH /api/ip/{ip}/symmetric

Cuerpo

{ "symmetricMode": "FULL" }

Valores

FULL — Impone inspección simétrica. Los flujos asimétricos son desafiados o descartados. Recomendado.
DISABLED — No impone enrutamiento simétrico. Úsalo solo si tu red es intencionadamente asimétrica.

Ejemplos

# 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"}'

Respuesta (200 OK)

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

Errores: 400 valor no válido · 401 clave no válida · 403 la IP no es tuya · 500 fallo aguas arriba.

Lista de bloqueo de ASN

Filtra el tráfico por ASN de origen (Autonomous System Number). Útil para bloquear redes abusivas o limitar una IP al ASN de un proveedor de nube concreto.

La lista tiene un límite de 20 ASN por IP y funciona como lista negra o lista blanca.

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

Cuerpo

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

Modos

0 — Disabled — El filtrado por ASN está desactivado. Se ignora asnBlockList.
1 — Blacklist — Se bloquea el tráfico de los ASN listados. Todo lo demás se permite.
2 — Whitelist — Solo se permite el tráfico de los ASN listados. Todo lo demás se bloquea.

Envía ambos campos juntos. Los números de ASN son enteros entre 1 y 4,294,967,295. Sin prefijo AS: envía 13335, no "AS13335". Los duplicados se eliminan en el servidor.

Ejemplos

# 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": []}'

Respuesta (200 OK)

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

Errores: 400 modo no válido / lista no es un array / >20 entradas / ASN no válido · 401 clave no válida · 403 la IP no es tuya · 500 fallo aguas arriba.

Lista de bloqueo de países

Filtra el tráfico por país de origen (GeoIP). La lista tiene un límite de 20 países por IP y usa códigos ISO 3166-1 alpha-2.

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

Cuerpo

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

Modos

0 — Disabled — El filtrado por país está desactivado. Se ignora countryBlockList.
1 — Blacklist — Se bloquea el tráfico de los países listados. Todo lo demás se permite.
2 — Whitelist — Solo se permite el tráfico de los países listados. Todo lo demás se bloquea.

Los códigos no distinguen mayúsculas de minúsculas en la entrada y se almacenan en mayúsculas ("cz" pasa a ser "CZ"). Los duplicados se eliminan en el servidor.

Ejemplos

# 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": []}'

Respuesta (200 OK)

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

Códigos de país comunes

Códigos ISO 3166-1 alpha-2 de uso frecuente:

CZ — República Checa
RU — Rusia
SK — Eslovaquia
CN — China
DE — Alemania
UA — Ucrania
US — Estados Unidos
IN — India
GB — Reino Unido
BR — Brasil
FR — Francia
JP — Japón
PL — Polonia
KR — Corea del Sur
NL — Países Bajos
AU — Australia

Errores: 400 modo no válido / lista no es un array / >20 entradas / código no válido · 401 clave no válida · 403 la IP no es tuya · 500 fallo aguas arriba.

Combina estos endpoints para ajustar la protección por IP: define una acción predeterminada sensata, impón la inspección simétrica y restringe el acceso con listas de ASN y países según lo exija tu tráfico.

Perfiles de Filtro

Un preset de filtro es un conjunto de reglas con nombre preparado por Fusiora (ajustado para FiveM, tráfico web, DNS, etc.). Para usar uno, lo vinculas a una IP como un perfil de filtro asociado a un protocolo y un rango de puertos específicos.

Un perfil es la combinación de:

Un preset (el conjunto de reglas).
Un protocolo (UDP, TCP, ICMP).
Un rango de puertos de destino (minDstPort – maxDstPort, ambos inclusive).

Puedes vincular muchos perfiles a una sola IP — uno por servicio.

Listar presets disponibles

GET /api/filters

Sin parámetros de ruta ni de consulta.

Ejemplo

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

Respuesta (200 OK)

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

Cada entrada expone exactamente lo que necesitas para vincular un perfil:

id — úsalo como presetId al vincular.
name — nombre para mostrar, útil para registros y paneles.
protocol — protocolo para el que está construido este preset. Debe coincidir con el protocol que envíes.

Errores: 401 clave inválida · 500 fallo upstream.

Listar perfiles vinculados a una IP

GET /api/ip/{ip}/profiles

Ejemplo

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

Respuesta (200 OK)

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

Errores: 401 clave inválida · 403 IP no es tuya · 500 fallo upstream.

Vincular un perfil

POST /api/ip/{ip}/profiles

Cuerpo

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

presetId (obligatorio) — ID de GET /api/filters.
protocol (obligatorio) — nombre del protocolo, normalmente UDP, TCP o ICMP. Debe coincidir con el protocolo del preset.
minDstPort (obligatorio) — límite inferior de puertos de destino, inclusive (0 – 65535).
maxDstPort (obligatorio) — límite superior, inclusive (0 – 65535). Debe ser >= minDstPort.
notes (opcional) — nota de formato libre (cadena, puede estar vacía).

Ejemplo — servidor de juego 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"
  }'

Respuesta (200 OK)

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

Guarda el ID — lo necesitarás para eliminar el perfil más tarde.

Errores: 401 clave inválida · 403 IP no es tuya · 500 rechazo upstream — preset inválido, perfil solapado, protocolo no coincidente. El mensaje de error incluye el motivo upstream.

Eliminar un perfil

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

El perfil debe pertenecer a la IP de la URL — los perfiles vinculados a otra IP no se pueden eliminar por esta ruta.

Ejemplo

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

Respuesta (200 OK)

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

Errores: 401 clave inválida · 403 IP no es tuya · 404 el perfil no pertenece a esta IP · 500 fallo upstream.

Los perfiles de filtro son la forma de aplicar las reglas de protección de Fusiora exactamente donde las necesitas, servicio por servicio, en cada una de tus IPs.

Listas de IP

Las listas de IP son colecciones de direcciones CIDR reutilizables y con nombre que puedes referenciar desde los perfiles de protección DDoS. En lugar de duplicar el mismo conjunto de IPs en muchos filtros, mantienes una sola lista y la actualizas en un solo lugar.

Por qué usarlas

DRY. Un cambio actualiza cada filtro que referencia la lista.
Componibles. Las listas pueden incluir otras listas como entradas, construyendo una jerarquía (p. ej. partners → acme-corp + globex).
Caducidad por entrada. Las entradas de direcciones pueden eliminarse automáticamente tras N segundos, perfecto para baneos temporales.

Tipos de acción

Cada entrada tiene un ipListAction. Decide qué hace la capa de protección cuando el tráfico coincide.

WHITELIST — El tráfico siempre se permite, incluso cuando otras reglas lo bloquearían. Úsalo para socios de confianza o servicios de monitoreo. Predeterminado si no defines ninguno.
BLACKLIST — El tráfico siempre se descarta. Úsalo para atacantes conocidos o bloqueos detallados donde el filtrado por país/ASN es demasiado amplio.
TRUST — El tráfico omite por completo todo el filtrado DDoS. Úsalo solo para infraestructura interna o redes sobre las que tienes control total.

Ten cuidado con TRUST. Es un bypass, no solo una regla de permiso. Úsalo con moderación.

Propiedad

Cada lista pertenece al usuario que la creó.
Solo puedes ver, modificar o eliminar las listas que tú creaste.
Las listas de otros usuarios se reportan como 404 Not Found, no como 403, para que los IDs de lista no puedan enumerarse.
Las referencias a listas anidadas deben apuntar a una lista que también poseas.

Anidamiento

Una lista puede contener otra lista como entrada:

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

Dos reglas importantes:

Sin autorreferencia. Agregar la lista 730 como entrada de la lista 730 devuelve 400.
Sin referencias entre usuarios. La lista anidada debe ser tuya.

Si eliminas una lista que otra de tus listas referenciaba, la referencia queda inactiva: la lista padre no da error, simplemente deja de coincidir con lo que la hija solía aportar.

Límites y cuotas

Máx. de entradas por lista: 1 – 1,000,000, configurable mediante maxEntries. Por defecto 1000.
Formato del nombre de la lista: 1-64 caracteres alfanuméricos solamente, sin espacios, guiones ni guiones bajos.
Descripción de la lista: hasta 500 caracteres.

Crear una lista

POST /api/iplists

Cuerpo

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

name (obligatorio) — 1-64 caracteres alfanuméricos (a-z, A-Z, 0-9). Sin espacios, guiones ni guiones bajos.
description (opcional) — Texto libre de hasta 500 caracteres.
maxEntries (opcional) — 1 – 1,000,000. Por defecto 1000.

Ejemplos

# 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}'

Respuesta (201 Created)

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

Guarda el ID: lo necesitarás para cualquier otra operación sobre esta lista.

Listar tus listas

GET /api/iplists

Parámetros de consulta

includeItems (opcional) — "true" para incluir las entradas en línea. Omítelo o usa "false" solo para metadatos.

Ejemplos

# 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"

Respuesta (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"
  }
]

Las listas propiedad de otros usuarios nunca se devuelven.

Obtener una lista

GET /api/iplists/{id}

Devuelve los detalles completos y las entradas de una sola lista que poseas.

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

Devuelve 404 si la lista no existe o si no eres su propietario.

Actualizar una lista

PUT /api/iplists/{id}

Actualiza el name, la description o el maxEntries de la lista. Para cambiar las entradas en sí, usa los endpoints de entradas que aparecen más abajo.

Cuerpo

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

Ejemplos

# 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}'

Respuesta: 204 No Content. El cuerpo está vacío cuando tiene éxito.

Eliminar una lista

DELETE /api/iplists/{id}

Elimina permanentemente la lista y todas sus entradas. Cualquier referencia de perfil o de lista anidada queda inactiva, así que comprueba el uso primero.

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

Respuesta: 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"

Respuesta (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
  }
]

Agregar una entrada

POST /api/iplists/{id}/entries

Una entrada es o bien una dirección (CIDR) o bien una lista anidada (listId). Proporciona exactamente uno de esos campos por entrada: nunca ambos, nunca ninguno.

Cuerpo — entrada IP/CIDR

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

Cuerpo — referencia a lista anidada

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

address (uno de address/listId) — Un CIDR válido. Las IPs individuales deben ser /32 (IPv4) o /128 (IPv6). Los ceros a la izquierda se rechazan (01.2.3.4/32 es inválido).
listId (uno de address/listId) — ID de otra lista de IP que poseas. No puede ser igual a la lista padre. No puede referenciar una lista que no poseas.
ipListAction (opcional) — WHITELIST, BLACKLIST o TRUST. Por defecto WHITELIST.
expireAfterSec (opcional, solo dirección) — Elimina la entrada automáticamente tras N segundos. Entero no negativo. Se ignora en entradas de lista anidada.

Ejemplos

# 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"}'

Respuesta (201 Created)

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

Eliminar una entrada

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

La entrada debe pertenecer a la lista nombrada en la URL: aunque conozcas un ID de entrada de otra lista (tuya o de otra persona), no puede eliminarse a través del padre equivocado.

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

Respuesta: 204 No Content.

Errores comunes

400 — ID de lista, formato de nombre, longitud de descripción o rango de maxEntries inválidos.
400 — Se enviaron address y listId a la vez, o ninguno. Envía exactamente uno.
400 — address no es un CIDR válido: comprueba los ceros a la izquierda.
400 — ipListAction no es WHITELIST / BLACKLIST / TRUST.
400 — expireAfterSec es negativo o no es un entero.
400 — listId es igual al ID de la lista padre: autorreferencia.
400 — La lista anidada referenciada no existe o no es tuya.
401 — Clave de API ausente o inválida.
404 — La lista no existe o no es tuya: misma respuesta a propósito, consulta Primeros pasos.

Con las listas de IP centralizas la gestión de direcciones de confianza y bloqueadas en un único lugar reutilizable, manteniendo tus perfiles de protección limpios y coherentes.

Historial de ataques

Lee el historial de ataques contra tus IPs protegidas y obtén estadísticas de series temporales de cualquier ataque concreto.

Los resultados se limitan automáticamente a las IPs asignadas a tu cuenta: puedes llamar a estos endpoints con total libertad sin preocuparte por filtrar datos de otros inquilinos.

Obtener el historial de ataques

Devuelve la lista de ataques que han afectado a tus IPs protegidas.

GET /api/attacks

Parámetros de consulta

page (no requerido) — Número de página para la paginación.
query (no requerido) — Filtro de texto libre reenviado a Avoro (p. ej. tipo de ataque o IP).

Ejemplos

# 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"

Respuesta (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 elemento es un evento de ataque independiente:

ID — Úsalo para obtener las estadísticas (siguiente sección).
DstAddressString — La IP atacada. Siempre una de las tuyas.
Type — Clasificación del ataque (p. ej. UDP_FLOOD, SYN_FLOOD, …).
Bps — Ancho de banda máximo en bits por segundo.
Pps — Tasa máxima de paquetes en paquetes por segundo.
StartedAt — Marca de tiempo ISO 8601 de cuándo comenzó el ataque.
EndedAt — Marca de tiempo ISO 8601 de cuándo terminó el ataque.

Un array vacío es una respuesta perfectamente válida: simplemente significa que ningún ataque coincidió.

Errores: 401 clave no válida · 500 fallo upstream (el cuerpo incluye un debugId — cítalo en los tickets de soporte).

Obtener estadísticas de ataques

Devuelve estadísticas de series temporales —muestras de ancho de banda y tasa de paquetes— para un evento de ataque específico. Úsalo para representar gráficamente cómo el ataque aumentó y disminuyó.

GET /api/attacks/{id}/stats

id (requerido) — ID numérico del ataque obtenido de GET /api/attacks.

Ejemplo

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

Respuesta (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 muestra es una observación individual:

T — Marca de tiempo ISO 8601 de la muestra.
Bps — Ancho de banda en ese momento, en bits por segundo.
Pps — Tasa de paquetes en ese momento, en paquetes por segundo.

La cadencia entre muestras depende de la duración del ataque y del muestreo upstream: no asumas intervalos fijos al graficar.

Errores: 401 clave no válida · 500 fallo upstream.

Con estos dos endpoints puedes reconstruir tanto la visión general de los ataques recientes como el detalle minuto a minuto de cualquiera de ellos.

Referencia de la API

Material de consulta que complementa el resto de la documentación de la API: los códigos de estado HTTP que devuelve la API y la notación CIDR utilizada en cada entrada de IP.

Códigos de estado HTTP

La API de Fusiora usa códigos de estado HTTP estándar. A continuación: cada código que devuelve la API, cuándo lo verás y qué hacer.

Éxito

200 OK — La solicitud tuvo éxito. El cuerpo de la respuesta contiene el resultado.
201 Created — Se creó un nuevo recurso. Devuelto por POST /api/iplists y POST /api/iplists/{id}/entries.
204 No Content — La actualización o eliminación tuvo éxito. El cuerpo de la respuesta está vacío — no intentes analizarlo como JSON.

Errores del cliente

400 Bad Request — El cuerpo o la consulta de la solicitud está mal formado. El campo error describe el problema. Corrige la carga útil. Revisa los enums, los tamaños de array y los formatos de valor (CIDR, códigos de país ISO).
401 Unauthorized — Falta el encabezado x-api-key o es desconocido. Añade el encabezado. Revisa que la clave no tenga espacios finales ni un entorno incorrecto.
403 Forbidden — La clave es válida, pero la IP de la URL no está asignada a tu cuenta. Usa solo IPs asignadas a tu cuenta.
404 Not Found — El recurso no existe — o no es tuyo. Los errores de propiedad en las listas de IP se devuelven como 404 por diseño para evitar la enumeración de IDs. Verifica que el recurso exista y que lo hayas creado tú.

Errores del servidor

500 Internal Server Error — La API ascendente de Avoro falló. El campo error incluye detalles. Los errores del historial de ataques incluyen un debugId. Reintenta con retroceso exponencial. Si persiste, contacta con soporte indicando el debugId.
502 Bad Gateway — Avoro ascendente devolvió una respuesta inesperada. Reintenta. Si persiste, contacta con soporte.

Árbol de decisión rápido

Cuando recibas una respuesta que no sea de éxito:

¿400? Lee el campo error — te indica el fallo de validación exacto. No reintentes sin corregir la carga útil.
¿401? No reintentes — corrige tu encabezado.
¿403? La IP no es tuya. Revisa la URL.
¿404? El recurso falta o no es tuyo. Vuelve a comprobar el ID.
¿500 / 502? Reintenta con retroceso exponencial. Contacta con soporte si persiste.

Forma de la respuesta de error

Todos los errores comparten la misma forma JSON:

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

Algunas respuestas 500 incluyen campos adicionales:

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

Cita el debugId al contactar con soporte — es la forma más rápida de que localicemos tu fallo específico.

Notación CIDR

Cada entrada de IP en la API de Fusiora se indica en notación CIDR (Classless Inter-Domain Routing): address/prefix. El prefijo es el número de bits iniciales que comparte la dirección.

Una sola IP es /32 para IPv4 o /128 para IPv6. No existe el formato de "IP desnuda"; incluye siempre el prefijo.

Referencia rápida IPv4

1.2.3.4/32 — solo 1.2.3.4 — 1 dirección.
192.168.1.0/24 — 192.168.1.0 – 192.168.1.255 — 256 direcciones.
10.0.0.0/16 — 10.0.0.0 – 10.0.255.255 — 65 536 direcciones.
10.0.0.0/8 — 10.0.0.0 – 10.255.255.255 — ~16,7 M de direcciones.
0.0.0.0/0 — Toda la IPv4 — máxima precaución.

Referencia rápida IPv6

2001:db8::1/128 — Una sola dirección IPv6.
2001:db8::/32 — Una asignación típica de ISP — millones de /48.
2001:db8::/48 — Un solo sitio / cliente.

Reglas que aplica la API

Incluye siempre el prefijo. Incluso las IPs individuales necesitan /32 o /128. 1.2.3.4 por sí sola se rechaza.
Sin ceros a la izquierda en los octetos. 01.2.3.4/32 no es válido. Usa 1.2.3.4/32.
IPv6 debe tener la forma válida según RFC 4291. La abreviatura compacta :: está bien; se aceptan dígitos hexadecimales en mayúsculas o minúsculas.

Patrones comunes

Permitir la IP estática de tu oficina — 203.0.113.5/32
Bloquear un /24 abusivo completo — 198.51.100.0/24
Permitir todo el rango de tu VPC de AWS — 10.0.0.0/16
Host IPv6 individual — 2001:db8::1/128

Dónde aparece CIDR en la API

Las cadenas CIDR aparecen en el campo address de las entradas de listas de IP — consulta Listas de IP.

El filtrado por país y ASN usa códigos de país y números de ASN en su lugar — no aceptan CIDR. Consulta IPs protegidas para eso.

Atajo mental

Cuanto menor sea el número de prefijo, mayor será el rango:

/32 = 1 dirección (la más pequeña posible).
/24 = 256 direcciones (una subred "Clase C" típica).
/16 = 65 536 direcciones.
/8 = ~16,7 millones de direcciones.
/0 = todo internet.

En caso de duda, usa una calculadora CIDR en línea para verificar tu rango.