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 em uma URL versionada (por exemplo /public/v2/*). A URL V1 continua operando durante o período de migração.
  • Identificador de versão: a especificação OpenAPI carrega 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, é aceita uma chave que tenha mail:read ou web:read. O uso apenas do escopo mail:read fica registrado, 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 não se limita mais a decodificar um CSR: devolve um veredicto de conformidade baseado nos CA/Browser Forum Baseline Requirements, na Mozilla Root Store Policy e nos RFC aplicáveis, com detecção ROCA (CVE-2017-15361), detecção de chave fraca Debian (CVE-2008-0166) e impressão digital SPKI SHA-256. Este preço alinha-o com os demais 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 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 receptor.

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 toda resposta bem-sucedida.
  • Headers RateLimit-Policy, X-RateLimit-Limit, X-RateLimit-Remaining (este último é emitido apenas em caso de recusa 429).
  • Header X-Request-Id retornado em toda resposta 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çamentário 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/br/blog.
  • Email: os detentores de chaves ativas recebem uma notificação automática para qualquer breaking change.
  • Esta página: toda adição ou correção é registrada aqui, em ordem cronológica inversa.
  • Especificação OpenAPI: o campo info.version é incrementado a cada release. Monitorar 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.