Ir al contenido principal
CaptainDNS

Changelog de la API pública

Esta página lista los cambios mayores de la API pública de CaptainDNS. Las adiciones no destructivas (nuevos endpoints, campos opcionales) se documentan aquí sin aviso formal. Los cambios de ruptura se anuncian con al menos 30 días de antelación por esta misma vía y por email a los titulares de claves activas.

Política de versiones

  • Compatibilidad hacia atrás: añadir campos opcionales y nuevos endpoints no rompe los clientes existentes.
  • Deprecations: un campo o endpoint marcado como obsoleto permanece operativo al menos 6 meses tras el anuncio.
  • Rupturas: los cambios de ruptura se anuncian 30 días antes y se despliegan en una URL versionada (por ejemplo /public/v2/*). La URL V1 sigue operativa durante el período de migración.
  • Identificador de versión: la especificación OpenAPI lleva su propio número (info.version).

Versión 0.4.0 - 2026-07-21

Modificado

  • POST /public/v1/certificates/csr/parse pasa de la familia mail:read a la familia web:read. Un CSR no tiene nada específicamente de mail: el endpoint se une a url/check, page/crawl-check, phishing/check, http/headers-check, http/hsts-check y certificates/ssl/check. Ninguna clave existente se rompe: durante el período de transición se acepta una clave que lleve mail:read o web:read. El uso del scope mail:read en solitario queda registrado, y ese scope heredado será retirado al final de la transición, anunciada aquí con 30 días de antelación. Acción a prever: crea tus nuevas claves con web:read y añade web:read a las claves existentes que llaman a este endpoint.
  • Coste de POST /public/v1/certificates/csr/parse elevado de 1 a 2 créditos. El endpoint ya no se limita a decodificar un CSR: devuelve un veredicto de conformidad basado en los CA/Browser Forum Baseline Requirements, la Mozilla Root Store Policy y los RFC aplicables, con detección ROCA (CVE-2017-15361), detección de clave débil Debian (CVE-2008-0166) y huella SPKI SHA-256. Este precio lo alinea con los demás endpoints que devuelven un diagnóstico estructurado (dane/lookup, bimi/lookup, rdap/lookup, ip/whois, certificates/ssl/check). Una subida de coste no hace fallar ninguna llamada, pero duplica el consumo de créditos de toda integración que use este endpoint: revisa tu dimensionamiento de cuota antes de exponerte a un exceso.

Versión 0.3.1 - 2026-05-19

Añadido

  • POST /public/v1/dmarc/validate: respuesta enriquecida con scoring y recomendaciones. Nuevos campos aditivos y opcionales: state, score, score_band, verdict_headline, verdict_sub, score_factors, score_breakdown, recommendations, passed_checks, parsed_tags. El contrato existente (DMARCAnalysis a nivel raíz) se preserva estrictamente. Coste sin cambios (1 crédito), scope sin cambios (mail:read).

Versión 0.3.0 - 2026-04-14

Modificado

  • Payload webhook: ahora con schema_version: "2". Nuevos campos event_id, delivery_id, attempt. User-Agent ahora CaptainDNS-Webhook/2.0.
  • Nuevas cabeceras en cada POST: X-CaptainDNS-Event-ID, X-CaptainDNS-Delivery-ID, X-CaptainDNS-Attempt (formato n/6), X-CaptainDNS-Event-Type. Las cabeceras existentes X-CaptainDNS-Signature y X-CaptainDNS-Timestamp no cambian.
  • Política de reintentos: si tu endpoint devuelve 5xx, 408, 429 o un timeout/error de red, se realizan 6 intentos con backoff 10s, 1min, 10min, 1h, 6h, 24h. Las demás respuestas 4xx pasan directamente a failed_permanent sin reintentar.
  • event_id estable en todos los intentos y reenvíos manuales: clave de deduplicación recomendada en el receptor.

Versión 0.2.0 - 2026-04-09

Añadido

  • 51 endpoints públicos bajo /public/v1/* que cubren DNS, correo, web y texto:
    • DNS: resolve, resolve/propagation, dnssec/check, ip/whois, ip/nslookup, ip/netmask, rdap/lookup, domain/dns-check.
    • Correo: 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.
  • Gestión de claves API desde el dashboard CaptainDNS: listado, creación, revocación, rotación y consulta de uso.
  • Esquema OpenAPI PublicAPIError con 10 códigos canónicos para todos los errores.
  • Cabecera Idempotency-Key estilo Stripe, replay a 24 horas, 409 IDEMPOTENCY_CONFLICT ante body divergente.
  • Cabeceras X-Credits-Limit/Remaining/Consumed en cada respuesta exitosa.
  • Cabeceras RateLimit-Policy, X-RateLimit-Limit, X-RateLimit-Remaining (esta última se escribe únicamente ante un rechazo 429).
  • Cabecera X-Request-Id en todas las respuestas para facilitar el soporte.
  • 5 planes de facturación: Free, Starter, Pro, Business, Enterprise, con cuotas y excedente por tier.
  • Facturación de excedente opt-in con tope presupuestario mensual configurable desde el dashboard.
  • Notification channels (webhooks, Slack) en el dashboard de perfil, con firma HMAC-SHA256 opcional y 22 tipos de eventos. Ver la página dedicada.

No incluido en V1

  • Webhooks de la API pública firmados por clave (tabla webhook_endpoints) para empujar los eventos de tu cuenta hacia tus sistemas.

Mantenerse al día

  • Blog CaptainDNS: las releases mayores se publican en artículos dedicados en captaindns.com/es/blog.
  • Email: los titulares de claves activas reciben una notificación automática ante cualquier cambio de ruptura.
  • Esta página: toda adición o corrección se consigna aquí, en orden cronológico inverso.
  • Especificación OpenAPI: el campo info.version se incrementa en cada release. Monitorizar su valor permite disparar las regeneraciones de SDK.

Siguiente paso: vuelve al quickstart para empezar a integrar, o explora la referencia OpenAPI para ver todos los esquemas en detalle.