API de DNS

Retorna as estatísticas do DNS recursivo do servidor: status do serviço, métricas de consultas e cache, indicadores de segurança (DNSSEC) e o tamanho das listas de bloqueio ativas.

Blocos da resposta:

• service_status: unbound_active (serviço realmente ativo) e unbound_enabled (recursivo ligado nas opções do Ravi).
• current_metrics: consultas por segundo, tempo de resposta médio e mediano, taxa de acerto de cache (%), taxa de validação DNSSEC (%) e totais de consultas.
• query_types: contagem por tipo (A, AAAA, PTR, CNAME, ANY).
• security_metrics: validações DNSSEC, respostas bogus, consultas e respostas indesejadas.
• network_metrics: consultas TCP e IPv6.
• cache_metrics: tamanho do cache e fila de requisições.
• blocklists: quantidade de entradas de cada lista de bloqueio ativa (só aparecem as categorias ligadas na tela do DNS; chaves possíveis: adware_malware, phishing, anatel, cryptomining, ads, adult, social, games_gambling, tracking_analytics, fake_news).

curl -s "https://ravi.seuprovedor.com.br/api/api.php?token=SUA_CHAVE&action=dns&operation=recursive"

{
  "recursive": {
    "service_status":  { "unbound_active": true, "unbound_enabled": true },
    "current_metrics": { "queries_per_second": 412.7, "cache_hit_ratio": 87.3, "dnssec_validation_ratio": 96.1, ... },
    "query_types":     { "A": 125034, "AAAA": 30211, "PTR": 812, "CNAME": 145, "ANY": 3 },
    "security_metrics":{ "dnssec_validated": 118220, "dnssec_bogus": 4, "unwanted_queries": 51, "unwanted_replies": 12 },
    "network_metrics": { "tcp_queries": 210, "ipv6_queries": 18754 },
    "cache_metrics":   { ... },
    "blocklists":      { "phishing": 41230, "anatel": 1287 }
  }
}

Erro: {"msg":"No DNS log data found"} quando nunca houve coleta de estatísticas.

Lista as zonas do DNS autoritativo com seus registros. Sem domain, retorna todas as zonas; com domain, apenas a zona informada.

curl -s "https://ravi.seuprovedor.com.br/api/api.php?token=SUA_CHAVE&action=dns&operation=authoritative&domain=cliente.com.br"

{
  "authoritative": [
    {
      "id": 12,
      "domain": "cliente.com.br",
      "entries": [
        { "id": 301, "name": "ns1",  "value": "203.0.113.10", "type": "A",  "host": null, "priority": null, "alt_domain": null },
        { "id": 302, "name": "www",  "value": "203.0.113.20", "type": "A",  "host": null, "priority": null, "alt_domain": null },
        { "id": 303, "name": "@",    "value": "mail.cliente.com.br", "type": "MX", "host": null, "priority": 10, "alt_domain": null }
      ]
    }
  ]
}

Erro: {"msg":"No authoritative domains found"}.

Cria uma zona no DNS autoritativo, já com os registros padrão ns1, ns2 e www (tipo A, apontando para os IPs do próprio servidor), e recarrega o servidor autoritativo.

curl -s -X POST "https://ravi.seuprovedor.com.br/api/api.php" \
  -d "token=SUA_CHAVE" -d "action=dns" \
  -d "operation=add_domain" -d "domain=cliente.com.br"

{"msg":"ok"}

Erros: Please provide a valid domain, Domain already exists.

Cria um registro dentro de uma zona existente. É permitido repetir nome+tipo com valores diferentes (ex.: @ NS ns1 e @ NS ns2, ou vários TXT); apenas a combinação exata nome+tipo+valor repetida é recusada.

Registros TXT: envie o texto puro em host, sem aspas. O sistema adiciona as aspas na zona e divide automaticamente valores com mais de 255 caracteres em blocos concatenados, conforme o padrão DNS. Chaves DKIM longas e registros SPF podem ser enviados inteiros em uma única chamada, sem tratamento prévio.

PTR com domínio alternativo: quando adicional é informado em um registro PTR, o registro passa a ser publicado sob o domínio alternativo em vez da zona principal. Exemplo: subdomain=host1 com adicional=reverso.exemplo.net cria o PTR como host1.reverso.exemplo.net (com subdomain=@, o nome publicado é o próprio domínio alternativo). O campo aceita apenas letras, números, pontos e hífens; qualquer outro caractere retorna o erro Alternative domain cannot contain spaces or special characters.

curl -s -X POST "https://ravi.seuprovedor.com.br/api/api.php" \
  -d "token=SUA_CHAVE" -d "action=dns" -d "operation=add_subdomain" \
  -d "domain=cliente.com.br" -d "subdomain=@" -d "type=MX" \
  -d "host=mail.cliente.com.br" -d "priority=10"

curl -s -X POST "https://ravi.seuprovedor.com.br/api/api.php" \
  -d "token=SUA_CHAVE" -d "action=dns" -d "operation=add_subdomain" \
  -d "domain=exemplo.com" -d "subdomain=host1" -d "type=PTR" \
  -d "host=192.168.1.1" -d "adicional=reverso.exemplo.net"

{"msg":"ok"}

Erros: Please provide domain, subdomain, type and host, Domain not found, Entry already exists, Alternative domain cannot contain spaces or special characters (PTR com adicional inválido).

Verifica se um registro existe na zona. Útil antes de criar ou excluir, e para conferir o resultado de um lote.

curl -s "https://ravi.seuprovedor.com.br/api/api.php?token=SUA_CHAVE&action=dns&operation=search_subdomain&domain=cliente.com.br&subdomain=www&type=A"

{"msg":"true"}

{"msg":"true"} = o registro existe; {"msg":"false"} = não existe. Erro: Domain not found.

Exclui um registro da zona. A busca é feita por nome+tipo, sem considerar o valor.

curl -s -X POST "https://ravi.seuprovedor.com.br/api/api.php" \
  -d "token=SUA_CHAVE" -d "action=dns" -d "operation=delete_subdomain" \
  -d "domain=cliente.com.br" -d "subdomain=www" -d "type=A"

{"msg":"ok"}

Erros: Subdomain not found, Domain not found.

Exclui uma zona inteira do DNS autoritativo.

curl -s -X POST "https://ravi.seuprovedor.com.br/api/api.php" \
  -d "token=SUA_CHAVE" -d "action=dns" \
  -d "operation=delete_domain" -d "domain=cliente.com.br"

{"msg":"ok"}

Erro: Domain not found.

Recarrega o servidor autoritativo sob demanda. É o par do defer_reload: ao criar ou alterar muitos registros, envie defer_reload=1 em cada mutação (pulando a recarga individual) e chame reload_nsd uma única vez no fim. O resultado é 1 recarga em vez de N, e o lote fica muito mais rápido.

A chamada espera o serviço do Ravi processar a recarga, por até 15 segundos.

curl -s -X POST "https://ravi.seuprovedor.com.br/api/api.php" \
  -d "token=SUA_CHAVE" -d "action=dns" -d "operation=reload_nsd"

{"msg":"ok","reload_confirmed":true,"waited_ms":1800}

Se a espera estourar os 15 segundos, a resposta vem como {"msg":"ok_reload_timeout","reload_confirmed":false,...}: a recarga ainda pode completar logo em seguida; confirme com dig e, se preciso, repita a chamada.