Ir para o conteúdo principal
CaptainDNS

Changelog da API pública

Esta página lista as mudanças maiores da API pública CaptainDNS. Adições não destrutivas (novos endpoints, campos opcionais) são documentadas aqui sem aviso formal. Breaking changes são anunciados com pelo menos 30 dias de antecedência via esta página e por email aos detentores de chaves ativas.

Política de versionamento

  • Compatibilidade para trás: adicionar campos opcionais e novos endpoints não quebra clientes existentes.
  • Depreciações: um campo ou endpoint depreciado permanece funcional por pelo menos 6 meses após o anúncio.
  • Quebras: breaking changes são anunciados com 30 dias de antecedência e implantados numa URL versionada (por exemplo /public/v2/*). A URL V1 continua a operar durante o período de migração.
  • Identificador de versão: a especificação OpenAPI carrega o seu próprio número (info.version). O número maior segue a URL versionada, o menor segue as adições retrocompatíveis.

Versão 0.4.0 - 2026-07-21

Modificado

  • POST /public/v1/certificates/csr/parse passa da família mail:read para a família web:read. Um CSR não tem nada especificamente de mail: o endpoint junta-se a url/check, page/crawl-check, phishing/check, http/headers-check, http/hsts-check e certificates/ssl/check. Nenhuma chave existente quebra: durante o período de transição, é aceite uma chave que tenha mail:read ou web:read. O uso apenas do escopo mail:read fica registado, e esse escopo herdado será retirado no fim da transição, anunciada aqui com 30 dias de antecedência. Ação a prever: crie as suas novas chaves com web:read e acrescente web:read às chaves existentes que chamam este endpoint.
  • Custo de POST /public/v1/certificates/csr/parse elevado de 1 para 2 créditos. O endpoint já não se limita a descodificar um CSR: devolve um veredicto de conformidade assente nos CA/Browser Forum Baseline Requirements, na Mozilla Root Store Policy e nos RFC aplicáveis, com deteção ROCA (CVE-2017-15361), deteção de chave fraca Debian (CVE-2008-0166) e impressão digital SPKI SHA-256. Este preço alinha-o com os restantes endpoints que devolvem um diagnóstico estruturado (dane/lookup, bimi/lookup, rdap/lookup, ip/whois, certificates/ssl/check). Um aumento de custo não faz falhar nenhuma chamada, mas duplica o consumo de créditos de qualquer integração que use este endpoint: reveja o dimensionamento da sua quota antes de se expor a um excedente.

Versão 0.3.1 - 2026-05-19

Adicionado

  • POST /public/v1/dmarc/validate: resposta enriquecida com scoring e recomendações. Novos campos opcionais aditivos: state, score, score_band, verdict_headline, verdict_sub, score_factors, score_breakdown, recommendations, passed_checks, parsed_tags. O contrato existente (DMARCAnalysis no nível raiz) é estritamente preservado. Custo inalterado (1 crédito), escopo inalterado (mail:read).

Versão 0.3.0 - 2026-04-14

Modificado

  • Payload webhook: agora com schema_version: "2". Novos campos event_id, delivery_id, attempt. User-Agent agora CaptainDNS-Webhook/2.0.
  • Novos cabeçalhos em cada POST: X-CaptainDNS-Event-ID, X-CaptainDNS-Delivery-ID, X-CaptainDNS-Attempt (formato n/6), X-CaptainDNS-Event-Type. Os cabeçalhos existentes X-CaptainDNS-Signature e X-CaptainDNS-Timestamp permanecem inalterados.
  • Política de tentativas: se o seu endpoint retornar 5xx, 408, 429 ou um timeout/erro de rede, 6 tentativas são feitas com backoff 10s, 1min, 10min, 1h, 6h, 24h. As demais respostas 4xx vão direto para failed_permanent sem nova tentativa.
  • event_id estável em todas as tentativas e reenvios manuais: chave de deduplicação recomendada no recetor.

Versão 0.2.0 - 2026-04-09

Adicionado

  • 51 endpoints públicos sob /public/v1/* cobrindo DNS, email, web e texto:
    • DNS: resolve, resolve/propagation, dnssec/check, ip/whois, ip/nslookup, ip/netmask, rdap/lookup, domain/dns-check.
    • Email: spf/lookup, spf/validate, dkim/lookup, dkim/validate, dmarc/lookup, dmarc/validate, dmarc/generate, dmarcbis/check, dmarcbis/migrate, dmarc/report/analyze, bimi/lookup, bimi/validate, bimi/logo/lookup, mta-sts/lookup, tls-rpt/lookup, dane/lookup, blacklist/ip, smtp/check, mail/header-audit, mail/header-analyze, mail/domain-check, deliverability/score, certificates/csr/parse, certificats/bimi/parse, certificats/bimi/lookup.
    • Web: url/check, page/crawl-check, phishing/check.
    • Texto: text/lower, text/upper, text/stats, text/slug, text/base64/encode, text/base64/decode, text/password/generate, text/urlencode, text/urldecode, text/json/format, text/json/to-yaml, text/yaml/format, text/yaml/to-json, text/hash, text/regex/test.
  • Gestão de chaves API pelo dashboard CaptainDNS: listar, criar, revogar, rotacionar e consultar uso.
  • Esquema OpenAPI PublicAPIError com 10 códigos canónicos para todos os erros.
  • Header Idempotency-Key estilo Stripe, replay 24 horas, 409 IDEMPOTENCY_CONFLICT em body divergente.
  • Headers X-Credits-Limit/Remaining/Consumed retornados em todas as respostas bem-sucedidas.
  • Headers RateLimit-Policy, X-RateLimit-Limit, X-RateLimit-Remaining (este último é emitido apenas em caso de recusa 429).
  • Header X-Request-Id retornado em todas as respostas para facilitar o suporte.
  • 5 planos de cobrança: Free, Starter, Pro, Business, Enterprise com cotas e excedente por tier.
  • Cobrança de excedente opt-in com teto orçamental mensal configurável pelo dashboard.
  • Notification channels (webhooks, Slack) no dashboard do perfil, com assinatura HMAC-SHA256 opcional e 22 tipos de eventos. Veja a página dedicada.

Não entregue na V1

  • Webhooks da API pública assinados por chave (tabela webhook_endpoints) para enviar os eventos da sua conta aos seus sistemas.

Fique atualizado

  • Blog CaptainDNS: as releases maiores são publicadas em artigos dedicados em captaindns.com/pt/blog.
  • Email: os detentores de chaves ativas recebem uma notificação automática para qualquer breaking change.
  • Esta página: toda a adição ou correção é registada aqui, em ordem cronológica inversa.
  • Especificação OpenAPI: o campo info.version é incrementado a cada release. Monitorizar o seu valor permite disparar regenerações automáticas de SDK.

Próximo passo: volte ao quickstart para começar a integrar, ou explore a referência OpenAPI para ver todos os esquemas em detalhe.