API JSON

API pública do monitor, usada pelo próprio painel e disponível para integração com sistemas externos.

Endpoints públicos

Endpoint Descrição
GET /api/status Estado atual de todas as células do painel
GET /api/historico Série histórica de todas as UFs monitoradas
GET /api/uf/<uf>/historico Série histórica de uma UF específica
GET /health Saúde do monitor (sem rate limit nem anti-robô)

Estados e cores

Estado Valor Rótulo Cor Significado (cStat)
Operacional operacional Operacional #22C55E cStat 107
Instável instavel Instável #F59E0B cStat 108
Indisponível indisponivel Indisponível #EF4444 cStat 109
Sem dados sem_dados Sem dados #8A8585 Erro de coleta ou timeout

Como usar

Todas as respostas são em formato JSON com charset UTF-8. Exemplo de chamada:

// JavaScript (fetch)
fetch('/api/status')
  .then(response => response.json())
  .then(data => console.log(data));

Exemplo com curl:

curl https://seu-dominio.com/api/status

Nota: Quando o frontend está hospedado em domínio diferente da API, configure apiBaseUrl em frontend/js/config.js com a URL completa da API (ex.: https://api.exemplo.com).

Rate limit

As rotas /api/* aplicam limite de 30 requisições por minuto por endereço IP.

Ao exceder o limite, a resposta é:

  • Status HTTP 429
  • Header Retry-After: 60
  • Corpo: { "erro": "Limite de requisições excedido. Tente novamente em instantes." }

O limite pode ser ajustado em config.json, na chave rate_limit.api_requisicoes_por_minuto.

Anti-bot (Turnstile, opcional)

Quando habilitado, as rotas /api/* exigem o header CF-Turnstile-Token com um token válido do Cloudflare Turnstile.

Sem token válido, a resposta é:

  • Status HTTP 403
  • Corpo: { "erro": "Verificação anti-bot ausente." } ou { "erro": "Verificação anti-bot falhou." }

Para habilitar, configure TURNSTILE_SITE_KEY e TURNSTILE_SECRET_KEY no .env.

CORS

A API permite consumo de qualquer origem (CORS liberado):

  • Access-Control-Allow-Origin: *
  • Access-Control-Allow-Headers: CF-Turnstile-Token, Content-Type
  • Access-Control-Allow-Methods: GET, OPTIONS
  • Access-Control-Max-Age: 86400

Isso permite que um frontend estático hospedado em outro domínio consuma a API sem restrições.

Coleção Postman

Explorar a API no Postman

Importe a coleção oficial do Monitor Status DFe para testar todos os endpoints diretamente no Postman.

Abrir coleção no Postman

Especificação OpenAPI

Baixar o arquivo da especificação

O arquivo openapi.yaml descreve todos os endpoints, parâmetros e respostas da API — use-o em ferramentas como Swagger Editor, Redoc ou geradores de clientes.

Baixar openapi.yaml

Explorar (Swagger UI)

Documentação interativa gerada a partir da especificação OpenAPI: