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 1.2.3 - 2026-10-27

POST /public/v1/spf/lookup e /public/v1/spf/validate: o motivo de uma consulta DNS com falha agora vem de uma lista fechada: timeout, servfail, refused, nxdomain, io_error ou unexpected_rcode <RCODE>. Ele aparece no detail dos diagnósticos lookup_error, ainda no formato <context>: <reason>, e nos parâmetros das recomendações correspondentes. Até agora, esses campos traziam o texto de erro do resolvedor, por exemplo unexpected rcode SERVFAIL ou um erro de rede. Os problemas SPF de POST /public/v1/mail/domain-check seguem a mesma regra. A message dos erros ERR_DNS_IO e ERR_DOH_IO, por exemplo em POST /public/v1/resolve, agora vale timeout ou io_error.

ip_check.result agora vale temperror quando uma consulta DNS de um termo a ou mx alcançado pela avaliação falha de forma temporária (tempo esgotado, SERVFAIL, REFUSED). Até agora, o termo era pulado e a avaliação continuava, o que podia terminar em pass, fail ou neutral. Um termo que corresponde antes continua tendo prioridade, e um nome inexistente (NXDOMAIN) continua contando como ausência de correspondência.

Versão 1.2.2 - 2026-10-27

POST /public/v1/spf/lookup e /public/v1/spf/validate: um termo ptr continua contando nos lookups DNS, mas não envia mais consultas, porque a avaliação não verifica nenhum IP (RFC 7208 §5.5). Ele não gera mais lookup_error. Um registro longo demais em um destino de include agora gera um aviso record_too_long em vez de um erro; o registro do próprio domínio e um destino de redirect mantêm o erro. Os domínios afetados podem sair do estado permerror e mudar de pontuação, inclusive no componente spf de POST /public/v1/deliverability/score.

ip_check.result agora pode valer permerror ou temperror. Se o registro, ou um registro que ele inclui, tiver um erro permanente segundo a RFC 7208 (sintaxe inválida, limite de lookups excedido, destino sem SPF), qualquer IP recebe permerror, em vez de um pass causado por um termo lido antes do erro ou de um neutral. Os demais controles, como ip_allows_all, record_too_long ou unknown_modifier, não impedem a avaliação. Se a avaliação chegar a um include ou a um redirect cuja consulta DNS falhou de forma temporária, ou se a cota de consultas se esgotar após um erro desse tipo, o resultado é temperror. Um texto que não é um registro SPF retorna none.

POST /public/v1/mail/domain-check: no máximo 20 seletores DKIM distintos são inspecionados, na ordem de dkim_selectors; os seguintes são ignorados. Custo inalterado (10 créditos). Um registro SPF com mais de 450 caracteres agora sai com o código SPF_RECORD_TOO_LONG e não mais com SPF_SYNTAX_INVALID: erro para o registro do próprio domínio, aviso para um destino de include.

Versão 1.2.1 - 2026-10-27

POST /public/v1/spf/lookup e /public/v1/spf/validate: três novos códigos de diagnóstico, com state em permerror. dns_query_budget_exceeded indica uma cota de consultas DNS ultrapassada; mx_host_limit_exceeded, um termo mx com mais de 10 servidores MX (RFC 7208 §4.6.4); include_multiple_spf, um destino de include ou redirect que publica vários registros SPF (RFC 7208 §4.5).

A avaliação termina no terceiro void lookup: o código permanece void_lookup_limit_exceeded, mas os termos contados e a árvore podem encurtar. Se a cota se esgotar após erros de DNS temporários, state vale temperror (código lookup_error). Um include alcançado duas vezes é resolvido uma só vez.

Em validate sem resolve_includes (ausente ou false), apenas check_ip resolve os termos a e mx, sujeito à cota e ao limite MX. Custo inalterado (1 crédito).

Versão 1.2.0 - 2026-10-27

POST /public/v1/spf/lookup e POST /public/v1/spf/validate: os campos state e score agora estão descritos na especificação. state tem um novo valor, temperror: falha de DNS temporária, sem pontuação. Nesse caso, score não aparece em lookup e vale null em validate. Até agora, esse caso retornava invalid ou missing em lookup, e invalid em validate. Um NXDOMAIN no domínio consultado continua gerando missing. O componente spf de POST /public/v1/deliverability/score mantém sua pontuação; seu status pode passar de error para warning.

POST /public/v1/spf/validate: o campo opcional resolve_includes (booleano, false por padrão), já aceito, agora está descrito. Com true, os destinos de include e redirect são resolvidos via DNS. Sem esse campo, a análise é estática e state nunca vale temperror. Custo inalterado (1 crédito).

Versão 1.1.1 - 2026-09-24

POST /public/v1/tls-rpt/lookup: o texto de verdict_headline e verdict_sub para a faixa excellent foi reformulado. Ele descreve o registro publicado e esclarece que esta verificação não confirma o recebimento de relatórios. A pontuação, a faixa e os demais campos permanecem iguais. O mesmo texto aparece no componente tls_rpt de POST /public/v1/deliverability/score.

Versão 1.1.0 - 2026-09-16

POST /public/v1/deliverability/score adiciona o campo opcional advice. Ele contém cause, o problema prioritário identificado, e action, uma única ação sugerida. As pontuações e os campos existentes permanecem inalterados.

Versão 1.0.1 - 2026-09-14

Esta entrada atualiza a documentação que faltava: as seis operações a seguir já estavam disponíveis na API pública. A data é a desta página, não a de quando essas operações entraram em produção.

Adicionado

  • POST /public/v1/dns/idn: converte um nome de domínio entre Unicode e ASCII (Punycode). Escopo dns:read. Custo: 1 crédito.
  • POST /public/v1/http/qr: gera um código QR. A resposta bem-sucedida retorna diretamente os bytes da imagem, sem envelope JSON. A imagem nunca é armazenada. Escopo web:read. Custo: 2 créditos.
  • POST /public/v1/http/qr/decode: decodifica os códigos QR de uma imagem enviada. A imagem nunca é armazenada. Escopo web:read. Custo: 2 créditos.
  • POST /public/v1/http/headers-check: obtém os cabeçalhos HTTP de uma URL. Escopo web:read. Custo: 2 créditos.
  • POST /public/v1/http/hsts-check: avalia a implantação de HSTS em um domínio. Escopo web:read. Custo: 3 créditos.
  • POST /public/v1/certificates/ssl/check: inspeciona o certificado TLS de um host. Escopo web:read. Custo: 2 créditos.

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.