Ir para o conteúdo principal
CaptainDNS

Documentação da API pública CaptainDNS

Quer consultar os diagnósticos DNS, email e web do CaptainDNS a partir do seu próprio tooling? A API pública expõe 59 endpoints selecionados, protegidos por chave e medidos em créditos. Este guia leva-o do primeiro curl a uma integração pronta para produção.

O que obtém

  • 59 endpoints cobrindo DNS, email e web: resolução DNS, propagação, DNSSEC, WHOIS, SPF/DKIM/DMARC/BIMI/MTA-STS/TLS-RPT/DANE, blacklist, SMTP, deliverability, análise de headers, verificação de URL, crawl de página, phishing, ferramentas de texto e muito mais.
  • Chaves API nos formatos cdns_live_... e cdns_test_..., cada uma com escopos e rotacionáveis sem downtime.
  • Token bucket por chave e limitador por IP para suavizar picos.
  • Idempotência estilo Stripe, janela de 24 horas, reproduz a resposta armazenada.
  • Cobrança por créditos: um lookup simples custa 1 crédito, um deliverability score custa 30.
  • Excedente cobrado no início de cada mês para planos pagos que ultrapassam a sua cota.

URL base

https://api.captaindns.com/public/v1

Todas as rotas usam HTTPS. O site www.captaindns.com aloja o dashboard e o portal de documentação, api.captaindns.com aloja a API propriamente dita.

Início rápido em cinco minutos

Criar uma chave API

Faça login no dashboard CaptainDNS, abra Account > API keys, clique no botão de nova chave. Escolha um nome, um ambiente (live ou test), os escopos necessários e uma data de expiração opcional. O segredo em texto claro é exibido apenas uma vez: copie-o para o seu gestor de segredos antes de fechar o diálogo.

Lançar a primeira requisição

curl -X POST https://api.captaindns.com/public/v1/resolve \
  -H "Authorization: Bearer cdns_live_a3f2XK7mN9QrVtZ4yP1sH6eL8cF2dB5aR3gW7kJxM" \
  -H "Content-Type: application/json" \
  -d '{"qname":"captaindns.com","qtype":"A"}'

A resposta contém os registos solicitados e três famílias de headers que guiam o cliente:

RateLimit-Policy: "default";q=60;w=60
X-RateLimit-Limit: 60
X-Credits-Limit: 50000
X-Credits-Remaining: 49998
X-Credits-Consumed: 1
X-Request-Id: req_a1b2c3d4

Lidar com os erros

Todos os erros partilham o mesmo envelope JSON:

{
  "code": "QUOTA_EXCEEDED",
  "message": "Monthly credits quota exceeded for plan 'starter'.",
  "details": {
    "tier": "starter",
    "credits_used": 50000,
    "credits_limit": 50000
  },
  "request_id": "req_a1b2c3d4",
  "documentation_url": "https://www.captaindns.com/en/docs/api/errors"
}

Os códigos mais comuns são descritos no guia de erros. Atenção especial a RATE_LIMITED (429) e QUOTA_EXCEEDED (403): o primeiro é resolvido com backoff, o segundo exige upgrade de plano ou aguardar o próximo período.

Automatizar com idempotência

Todas as requisições POST aceitam o header Idempotency-Key. Qualquer reexecução dentro de 24 horas retorna a resposta original, com X-Idempotent-Replay: true. Ideal para retries de rede no cliente. Veja o guia de idempotência.

Mapa da documentação

  • Autenticação: formato da chave, allowlist de IP, rotação, revogação.
  • Escopos: detalhamento de dns:read, mail:read, mail:write, web:read.
  • Créditos: custo por endpoint, cotas por plano, cobrança de excedente.
  • Rate limiting: token bucket por chave, backoff recomendado.
  • Idempotência: reexecuções POST, TTL 24 h, hash do corpo.
  • Erros: tabela completa de códigos e ações corretivas.
  • Referência OpenAPI: especificação interativa de cada endpoint.
  • Webhooks: canais de notificação do painel, assinados em HMAC-SHA256 e repetidos em caso de falha. Os webhooks da API pública assinados por chave ainda não estão disponíveis.
  • Changelog: histórico de versões e breaking changes.

Princípios operacionais

Nunca chame do navegador: o seu frontend do utilizador final chama o seu próprio backend, que por sua vez chama a API pública CaptainDNS. É uma regra de segurança: o segredo não deve sair do seu servidor.

Observabilidade em primeiro lugar: o header X-Request-Id é retornado em todas as respostas. É registado do lado do CaptainDNS e pode ser usado para abrir um ticket de suporte.

Ferramentas CaptainDNS relacionadas

Os mesmos diagnósticos estão disponíveis como ferramentas web, úteis para verificar manualmente a saída da sua integração:

Pronto para programar? Leia autenticação e passe para rate limiting antes do primeiro deploy em produção.