API

O NNumbers WAF tem uma API REST documentada em OpenAPI. É a mesma API que a Console usa: tudo o que você faz na tela pode ser feito por chamada, com a mesma permissão e o mesmo isolamento por organização.

Visão geral

Item	Como funciona
Estilo	REST, corpo em JSON, campos em snake_case
Identificadores	UUID versão 7, em texto
Datas e horas	RFC 3339, em UTC
Documentação	Especificação OpenAPI publicada com o produto
Escopo	Sempre a organização da sua sessão

A Console é o caminho recomendado para começar: ela mostra o estado de cada etapa e evita erro de montagem de chamada. A API serve para automação — criar domínio em lote, sincronizar política com o seu provisionamento, puxar eventos para o seu SIEM.

Autenticação

A autenticação é feita pela Console: você obtém a credencial no seu acesso da NNumbers Console e a usa nas chamadas. Não há usuário e senha próprios do WAF, e a API não aceita credencial de outra organização.

A organização vem da credencial, nunca do corpo, da query ou de um cabeçalho da chamada. Um recurso de outra organização responde 404, e não 403: a existência dele não é revelada.

Permissões

Cada operação exige uma permissão, coerente com os papéis da Console:

Permissão	Cobre
domains.read	Consultar domínios, verificação, estado e origem
domains.manage	Criar, alterar e remover domínio, origem e verificação
protection.manage	Ativar e desativar proteção
policies.read	Consultar políticas, regras, exceções e revisões
policies.manage	Criar e alterar política e regras
exceptions.manage	Criar e remover exceção
events.read	Consultar eventos
metrics.read	Consultar visão geral e métricas

Chamada sem a permissão necessária responde erro de escopo, com o identificador de correlação para você levar ao suporte.

Paginação

Listas usam cursor:

Parâmetro	Valor
limit	De 1 a 200; padrão 50
cursor	Valor opaco devolvido na resposta anterior

A resposta traz os itens e o cursor seguinte:

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

Quando next_cursor vem nulo, a lista terminou. Não construa cursor por conta própria nem guarde posição por número de página: o cursor é opaco e pode mudar de forma.

Idempotência

Toda chamada que cria, altera ou remove exige o cabeçalho Idempotency-Key, com 1 a 128 caracteres.

Situação	Resposta
Primeira chamada com a chave	Operação executada
Repetição com a mesma chave e mesmo corpo	A mesma resposta da primeira, marcada como repetida
Repetição com a mesma chave e corpo diferente	Conflito de idempotência
Chave já expirada	A chave é descartada depois de 24 horas

Use uma chave por intenção de mudança, gerada uma vez e reaproveitada nas retentativas. É isso que impede um domínio duplicado quando a rede falha no meio.

Alterações também aceitam controle de versão: o recurso tem uma versão inteira, e a chamada pode exigir que a versão continue a mesma. Se outra pessoa alterou antes, a resposta é conflito de versão, e não sobrescrita silenciosa.

Erros

O erro tem sempre a mesma forma:

{
  "error": {
    "code": "validation_failed",
    "message": "Texto legível sobre o que falhou",
    "correlation_id": "identificador da chamada"
  }
}

Código	Quando acontece
unauthorized	Credencial ausente ou inválida
forbidden_scope	Credencial válida sem a permissão da operação
not_found	Recurso inexistente na sua organização
validation_failed	Corpo ou parâmetro inválido
conflict	Conflito com o estado atual
version_conflict	A versão exigida não é mais a atual
idempotency_conflict	Mesma chave de idempotência com corpo diferente
hostname_unavailable	Hostname já cadastrado por outra organização
invalid_state_transition	A etapa não é válida no estado atual do domínio
verification_failed	A verificação de propriedade não passou
origin_rejected	Origem recusada pelas regras de endereço ou porta
policy_in_use	Política ainda usada por um domínio
payload_too_large	Corpo acima do limite da API
rate_limited	Chamadas acima do limite da API
dependency_unavailable	Serviço temporariamente indisponível; repita depois

Guarde o correlation_id de toda falha: é o que liga a chamada ao registro do lado da NNumbers, sem precisar reproduzir o erro.

Operações demoradas

Verificar, ativar, desativar, remover e aplicar política são operações que não terminam na mesma resposta. A chamada responde com o recurso e o estado corrente, e você acompanha pelo estado do domínio — os mesmos estados que a Console mostra.

Próximos passos

• Domínios — os estados que a API devolve.
• Eventos e exceções — o que puxar para o seu monitoramento.
• Segurança — permissões e auditoria.