API

El NNumbers WAF tiene una API REST documentada en OpenAPI. Es la misma API que usa la Console: todo lo que haces en pantalla puede hacerse por llamada, con el mismo permiso y el mismo aislamiento por organización.

Visión general

Ítem	Cómo funciona
Estilo	REST, cuerpo en JSON, campos en snake_case
Identificadores	UUID versión 7, en texto
Fechas y horas	RFC 3339, en UTC
Documentación	Especificación OpenAPI publicada con el producto
Alcance	Siempre la organización de tu sesión

La Console es el camino recomendado para empezar: muestra el estado de cada etapa y evita errores al armar la llamada. La API sirve para automatización — crear dominios en lote, sincronizar la política con tu aprovisionamiento, llevar eventos a tu SIEM.

Autenticación

La autenticación se hace por la Console: obtienes la credencial en tu acceso de NNumbers Console y la usas en las llamadas. No hay usuario y contraseña propios del WAF, y la API no acepta credencial de otra organización.

La organización viene de la credencial, nunca del cuerpo, de la query ni de una cabecera de la llamada. Un recurso de otra organización responde 404, y no 403: su existencia no se revela.

Permisos

Cada operación exige un permiso, coherente con los roles de la Console:

Permiso	Cubre
domains.read	Consultar dominios, verificación, estado y origen
domains.manage	Crear, cambiar y eliminar dominio, origen y verificación
protection.manage	Activar y desactivar protección
policies.read	Consultar políticas, reglas, excepciones y revisiones
policies.manage	Crear y cambiar política y reglas
exceptions.manage	Crear y eliminar excepciones
events.read	Consultar eventos
metrics.read	Consultar visión general y métricas

Una llamada sin el permiso necesario responde error de alcance, con el identificador de correlación para llevarlo al soporte.

Paginación

Las listas usan cursor:

Parámetro	Valor
limit	De 1 a 200; por defecto 50
cursor	Valor opaco devuelto en la respuesta anterior

La respuesta trae los ítems y el cursor siguiente:

{
  "items": [],
  "next_cursor": "opaco"
}

Cuando next_cursor viene nulo, la lista terminó. No construyas el cursor por tu cuenta ni guardes posición por número de página: el cursor es opaco y puede cambiar de forma.

Idempotencia

Toda llamada que crea, cambia o elimina exige la cabecera Idempotency-Key, con 1 a 128 caracteres.

Situación	Respuesta
Primera llamada con la clave	Operación ejecutada
Repetición con la misma clave y el mismo cuerpo	La misma respuesta de la primera, marcada como repetida
Repetición con la misma clave y cuerpo diferente	Conflicto de idempotencia
Clave ya expirada	La clave se descarta después de 24 horas

Usa una clave por intención de cambio, generada una vez y reutilizada en los reintentos. Eso es lo que impide un dominio duplicado cuando la red falla a mitad de camino.

Los cambios también aceptan control de versión: el recurso tiene una versión entera, y la llamada puede exigir que la versión siga siendo la misma. Si otra persona cambió antes, la respuesta es conflicto de versión, y no sobrescritura silenciosa.

Errores

El error tiene siempre la misma forma:

{
  "error": {
    "code": "validation_failed",
    "message": "Texto legible sobre lo que falló",
    "correlation_id": "identificador de la llamada"
  }
}

Código	Cuándo ocurre
unauthorized	Credencial ausente o inválida
forbidden_scope	Credencial válida sin el permiso de la operación
not_found	Recurso inexistente en tu organización
validation_failed	Cuerpo o parámetro inválido
conflict	Conflicto con el estado actual
version_conflict	La versión exigida ya no es la actual
idempotency_conflict	Misma clave de idempotencia con cuerpo diferente
hostname_unavailable	Hostname ya registrado por otra organización
invalid_state_transition	La etapa no es válida en el estado actual del dominio
verification_failed	La verificación de propiedad no pasó
origin_rejected	Origen rechazado por las reglas de dirección o puerto
policy_in_use	Política aún usada por un dominio
payload_too_large	Cuerpo por encima del límite de la API
rate_limited	Llamadas por encima del límite de la API
dependency_unavailable	Servicio temporalmente indisponible; repite después

Guarda el correlation_id de toda falla: es lo que une la llamada al registro del lado de NNumbers, sin necesidad de reproducir el error.

Operaciones largas

Verificar, activar, desactivar, eliminar y aplicar política son operaciones que no terminan en la misma respuesta. La llamada responde con el recurso y el estado actual, y sigues el avance por el estado del dominio — los mismos estados que muestra la Console.

Próximos pasos

• Dominios — los estados que devuelve la API.
• Eventos y excepciones — qué llevar a tu monitoreo.
• Seguridad — permisos y auditoría.