API para desenvolvedores

Com a API, seus sistemas (ou seu painel de hospedagem) criam e consultam monitores, incidentes e relatórios de disponibilidade sem entrar no portal. Ela fica no mesmo endereço do portal, em /api/v1. A especificação completa (OpenAPI 3.1) está em /api/v1/openapi.json.

Token

  1. Um administrador da empresa, com segundo fator ativo, abre a aba API e cria um token.
  2. Escolha as permissões: Somente leitura ou Leitura e escrita (ou permissões avulsas) e a validade.
  3. Copie o token: ele é mostrado uma única vez. Guarde-o como um segredo (gerenciador de senhas, variável de ambiente), nunca no código.

Envie o token em cada requisição:

Authorization: Bearer tdx_...

O token pertence à empresa, não a uma pessoa. Se vazar ou não for mais usado, revogue-o na mesma aba.

Permissões

  • monitors:read: listar e ver monitores e seu status.
  • monitors:write: criar, editar, pausar e retomar monitores.
  • incidents:read: incidentes dos últimos 1 a 90 dias.
  • reports:read: relatório mensal de disponibilidade.
  • providers:read / providers:write (planos Profissional e Agência): SLA de fornecedores, seu relatório mensal de descumprimento com o crédito devido e a evidência em PDF ou CSV (GET /api/v1/providers/{id}/reports/{AAAA-MM} e /evidence.pdf; a impressão SHA-256 vem no cabeçalho X-Content-SHA256).

Exemplos

Listar os monitores:

curl -H "Authorization: Bearer $TOKEN" https://<portal>/api/v1/monitors

Criar um monitor de site (com Idempotency-Key, uma nova tentativa não cria outro):

curl -X POST https://<portal>/api/v1/monitors \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1234" \
  -d '{"name": "Loja", "type": "http", "url": "https://www.suaempresa.com.br/", "expected_text": "Bem-vindo", "interval": "5m"}'

Tipos: http (url, expected_text), tcp (host, port), ping (host) e certificate (host, port, warn_days). Os intervalos e a quantidade de monitores dependem do seu plano. Só são aceitos destinos públicos.

Pausar e retomar: POST /api/v1/monitors/{id}/pause e /resume. Nada é apagado: um monitor pausado deixa de medir e de alertar, e pode ser retomado.

Relatório do mês: GET /api/v1/reports/2026-09 (os mesmos números do relatório do portal; horário do Chile).

Status de um monitor

up funcionando · down em falha · degraded a última verificação falhou · starting aguardando a primeira medição · unmeasurable não pode ser medido pela internet · no_checks sem verificações · paused pausado (paused_reason: user ou plan).

Limites de uso

Por token e por minuto: Grátis 60, Básico 120, Profissional 300 requisições; as escritas, 10 por minuto. Cada resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; ao ultrapassar você recebe 429 com Retry-After.

Erros

Os erros vêm em JSON (RFC 9457) com um code estável e um detail no seu idioma (Accept-Language: es, en ou pt). Códigos principais:

  • invalid_token (401): o token está ausente, não existe, expirou ou foi revogado.
  • insufficient_scope (403): o token não tem a permissão.
  • managed_account (403): numa conta gerenciada pela TECDEX os monitores são somente leitura.
  • not_found (404): não existe ou não é da sua empresa.
  • validation_failed (422): dados inválidos; o detalhe vem em errors.
  • invalid_month (422): o mês deve ser AAAA-MM e não pode ser futuro.
  • plan_limit (409): você atingiu o máximo de monitores do seu plano.
  • plan_type_not_included (403): seu plano não inclui esse tipo de monitor (Grátis: apenas http; Básico e Profissional: também tcp, ping e certificate).
  • already_paused, not_paused, paused_by_plan (409): estado de pausa.
  • rate_limited (429): aguarde o indicado em Retry-After.
  • service_unavailable (503): tente novamente em um minuto.

Entrar · Criar conta