Documentacao da API

API REST para consulta de logs CGNAT armazenados no VictoriaLogs. Versao atual: v1

Base URL: https://natvault.ceritell.com.br/api/

Introducao

O NATVault armazena logs de firewall CGNAT (Carrier-Grade NAT) dos equipamentos MikroTik da rede, permitindo consultas por IP publico, porta, protocolo e periodo. Todos os dados sao armazenados no VictoriaLogs com retencao minima de 1 ano, conforme Art. 13 da Lei 12.965/2014 (Marco Civil da Internet).

Autenticacao

A API utiliza autenticacao baseada em sessao (cookie PHPSESSID). Para endpoints protegidos, e necessario fazer login primeiro via POST /api/v1/auth.php e enviar o cookie de sessao nas requisicoes subsequentes.

Todas as requisicoes POST requerem um token CSRF, enviado via header X-CSRF-TOKEN ou campo csrf_token.

Rate Limits

Os seguintes limites se aplicam:

Login	5 tentativas por IP a cada 15 minutos
Busca	Periodo maximo de 30 dias por consulta
Resultados	Maximo 100 resultados por pagina (paginacao disponivel)

Codigos de Erro

200	Sucesso
400	Requisicao invalida (parametros incorretos)
401	Nao autenticado
403	Permissao insuficiente ou CSRF invalido
429	Rate limit excedido
500	Erro interno do servidor
503	VictoriaLogs offline

Todas as respostas de erro seguem o formato:

{
    "error": "Descricao do erro"
}

GET /api/health.php

Verificar saude do sistema (nao requer autenticacao).

# Resposta
{
    "status": "ok",
    "victoria_logs": true,
    "database": true,
    "version": "1.2.0"
}

POST /api/v1/auth.php

Autenticar usuario e iniciar sessao.

Parametro	Tipo	Obrigatorio	Descricao
email	string	sim	E-mail do usuario
password	string	sim	Senha do usuario

# Resposta sucesso
{
    "ok": true,
    "user": { "id": 1, "nome": "Cesar", "role": "admin" },
    "csrf_token": "abc123..."
}

# Resposta erro
{
    "error": "E-mail ou senha incorretos."
}

POST /api/search.php

Buscar logs CGNAT por IP ou MAC address. Requer role admin ou operator.

Parametro	Tipo	Obrigatorio	Descricao
ip	string	sim*	IP publico (obrigatorio se nao usar MAC)
mac	string	nao	MAC address (formato AA:BB:CC:DD:EE:FF)
porta	int	nao	Porta (1-65535)
protocolo	string	nao	TCP, UDP, ICMP ou any (default: any)
data_inicio	datetime	sim	Inicio do periodo (YYYY-MM-DDTHH:MM)
data_fim	datetime	sim	Fim do periodo
tipo	string	nao	judicial, interna, auditoria
numero_oficio	string	nao	Numero do oficio judicial
offset	int	nao	Offset para paginacao (default: 0)
csrf_token	string	sim	Token CSRF

# Resposta
{
    "ok": true,
    "consulta_id": 42,
    "total": 87,
    "offset": 0,
    "has_more": false,
    "tempo_ms": 234,
    "resultados": [
        {
            "timestamp": "2026-03-22T14:30:00Z",
            "action": "forward",
            "src_mac": "AA:BB:CC:DD:EE:FF",
            "protocol": "TCP",
            "src_ip": "100.64.1.50",
            "src_port": 45123,
            "dst_ip": "200.150.100.50",
            "dst_port": 443,
            "raw": "forward: in:ether1 out:ether2..."
        }
    ]
}

GET /api/stats.php

Estatisticas de volume de logs (ultimas 24h por hora). Requer autenticacao.

Query Param	Descricao
quick=1	Retorna apenas contadores rapidos (logs_today, total_logs, disk_usage)

# Resposta completa
{
    "ok": true,
    "hourly": [
        { "label": "00:00", "count": 15420 },
        { "label": "01:00", "count": 12300 },
        ...
    ]
}

# Resposta quick
{
    "ok": true,
    "logs_today": 245000,
    "total_logs": 89000000,
    "disk_usage": "2.4 GB"
}

GET /api/check-sources.php

Status das fontes de log (equipamentos MikroTik). Requer autenticacao.

{
    "ok": true,
    "sources": [
        {
            "name": "CCR1036-Princesa",
            "status": "online",
            "last_seen": "22/03/2026 14:30:00",
            "last_log_preview": "forward: in:ether1 out:ether2..."
        }
    ]
}

GET /api/report.php

GET /api/report.php?id={consulta_id}

Gerar relatorio HTML para impressao/PDF de uma consulta. Requer autenticacao.

Este endpoint retorna HTML, nao JSON. Use Ctrl+P no navegador para salvar como PDF.

GET /api/export-csv.php

GET /api/export-csv.php?id={consulta_id}

Exportar resultados de uma consulta em CSV. Requer autenticacao.

POST /api/v1/subscribers.php

Sincronizar assinantes do ERP. Autenticacao via X-API-Key header.

Campo (JSON body)	Tipo	Obrigatorio	Descricao
subscribers	array	sim	Array de objetos subscriber
subscribers[].username	string	sim	Login PPPoE do cliente
subscribers[].external_id	string	nao	ID no sistema ERP
subscribers[].nome	string	nao	Nome completo
subscribers[].cpf	string	nao	CPF do cliente
subscribers[].plano	string	nao	Nome do plano
subscribers[].status	string	nao	ativo, bloqueado, cancelado
subscribers[].mac_address	string	nao	MAC do equipamento

# Header
X-API-Key: SUA_CHAVE_DE_INTEGRACAO

# Body
{"subscribers": [{"username": "fulano@isp.com.br", "nome": "Fulano", "cpf": "123.456.789-00", "plano": "100M"}]}

# Resposta
{"ok": true, "imported": 5, "updated": 3, "errors": 0, "total_subscribers": 150}

POST /api/v1/sessions.php

Sincronizar sessoes RADIUS/PPPoE. Autenticacao via X-API-Key header.

Campo (JSON body)	Tipo	Obrigatorio	Descricao
sessions	array	sim	Array de objetos session
sessions[].username	string	sim	Login PPPoE
sessions[].framed_ip	string	sim	IP atribuido ao cliente
sessions[].start_time	datetime	sim	Inicio da sessao (YYYY-MM-DD HH:mm:ss)
sessions[].stop_time	datetime	nao	Fim da sessao (null = ativa)
sessions[].nas_ip	string	nao	IP do NAS/concentrador
sessions[].mac_address	string	nao	MAC do equipamento

# Resposta
{"ok": true, "imported": 10, "updated": 2, "errors": 0, "total_sessions": 500}

GET /api/v1/lookup.php

GET /api/v1/lookup.php?ip={ip}&timestamp={timestamp}

Identificar assinante por IP CGNAT + timestamp. Autenticacao via JWT Bearer token.

Query Param	Tipo	Obrigatorio	Descricao
ip	string	sim	IP CGNAT (100.64.0.0/10)
timestamp	string	sim	Data/hora (YYYY-MM-DDTHH:mm:ss)

# Resposta com subscriber
{
    "ok": true, "ip": "100.80.2.175", "timestamp": "2026-03-22T10:00:00",
    "subscriber": {"username": "fulano@isp.com.br", "nome": "Fulano", "cpf": "123.456.789-00", "plano": "100M", "cidade": "Princesa Isabel"},
    "session": {"username": "fulano@isp.com.br", "start_time": "2026-03-22 08:30:00", "stop_time": null, "active": true}
}

Exemplos cURL

Login

curl -c cookies.txt -X POST https://natvault.ceritell.com.br/api/v1/auth.php \
    -d "email=cesar@ceritell.com.br" \
    -d "password=SuaSenha"

Health Check

curl https://natvault.ceritell.com.br/api/health.php

Buscar Logs por IP

curl -b cookies.txt -X POST https://natvault.ceritell.com.br/api/search.php \
    -d "ip=45.163.116.92" \
    -d "porta=443" \
    -d "protocolo=TCP" \
    -d "data_inicio=2026-03-22T00:00" \
    -d "data_fim=2026-03-22T23:59" \
    -d "tipo=interna" \
    -d "csrf_token=SEU_TOKEN"

Buscar por MAC

curl -b cookies.txt -X POST https://natvault.ceritell.com.br/api/search.php \
    -d "mac=AA:BB:CC:DD:EE:FF" \
    -d "data_inicio=2026-03-22T00:00" \
    -d "data_fim=2026-03-22T23:59" \
    -d "csrf_token=SEU_TOKEN"

Estatisticas Rapidas

curl -b cookies.txt https://natvault.ceritell.com.br/api/stats.php?quick=1

Sincronizar Subscribers (Integracao)

curl -X POST https://natvault.ceritell.com.br/api/v1/subscribers.php \
    -H "X-API-Key: SUA_CHAVE_AQUI" \
    -H "Content-Type: application/json" \
    -d {subscribers: [{username: cliente@isp.com.br, nome: Nome, cpf: 000.000.000-00, plano: 100M, status: ativo}]}

Sincronizar Sessoes (Integracao)

curl -X POST https://natvault.ceritell.com.br/api/v1/sessions.php \
    -H "X-API-Key: SUA_CHAVE_AQUI" \
    -H "Content-Type: application/json" \
    -d {sessions: [{username: cliente@isp.com.br, framed_ip: 100.80.2.175, start_time: 2026-03-22 10:00:00}]}

Lookup Cliente por IP

curl -H "Authorization: Bearer SEU_JWT_TOKEN" \
    "https://natvault.ceritell.com.br/api/v1/lookup.php?ip=100.80.2.175×tamp=2026-03-22T10:00:00"

NATVault v1.2.0 - Ceritell Tecnologia

Voltar ao sistema