Ir al contenido principal
CaptainDNS

Documentación de la API pública de CaptainDNS

¿Quieres consultar los diagnósticos DNS, correo y web de CaptainDNS desde tu propio stack? La API pública expone 59 endpoints cuidadosamente seleccionados, protegidos por clave y medidos en créditos. Esta guía te lleva desde el primer curl hasta una integración lista para producción.

Qué obtienes

  • 59 endpoints que cubren DNS, correo y web: resolución DNS, propagación, DNSSEC, WHOIS, SPF/DKIM/DMARC/BIMI/MTA-STS/TLS-RPT/DANE, blacklist, SMTP, entregabilidad, análisis de cabeceras, verificación de URL, crawl de página, phishing, herramientas de texto y más.
  • Claves API en formato cdns_live_... y cdns_test_..., cada una con scopes y rotables sin interrupción.
  • Token bucket por clave y limitador por IP para suavizar picos.
  • Idempotencia estilo Stripe, ventana de 24 horas, reproduce la respuesta almacenada.
  • Medición por créditos: un lookup simple cuesta 1 crédito, un score de entregabilidad cuesta 30.
  • Overage facturado cada inicio de mes para los planes de pago que exceden su cupo.

URL base

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

Todas las rutas usan HTTPS. El sitio www.captaindns.com aloja el dashboard y el portal de documentación; api.captaindns.com aloja la API propiamente dicha.

Inicio rápido en cinco minutos

Crear una clave API

Inicia sesión en el dashboard de CaptainDNS, abre Account > API keys, haz clic en el botón de nueva clave. Elige un nombre, un entorno (live o test), los scopes necesarios y una fecha de expiración opcional. El secreto en claro se muestra una única vez: cópialo a tu gestor de secretos antes de cerrar el diálogo.

Lanzar la primera petición

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"}'

La respuesta contiene los registros solicitados y tres familias de cabeceras que guían al 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

Gestionar los errores

Todos los errores comparten la misma envoltura 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"
}

Los códigos más frecuentes se describen en la guía de errores. Presta atención a RATE_LIMITED (429) y QUOTA_EXCEEDED (403): el primero se resuelve con backoff, el segundo requiere cambiar de plan o esperar al mes siguiente.

Automatizar con idempotencia

Todas las peticiones POST aceptan una cabecera Idempotency-Key. Cualquier reintento idéntico en un plazo de 24 horas devuelve la respuesta original, con X-Idempotent-Replay: true. Ideal para reintentos de red en el cliente. Consulta la guía de idempotencia.

Mapa de la documentación

  • Autenticación: formato de clave, allowlist de IP, rotación, revocación.
  • Scopes: desglose de dns:read, mail:read, mail:write, web:read.
  • Créditos: coste por endpoint, cupos por plan, overage.
  • Rate limiting: token bucket por clave, backoff recomendado.
  • Idempotencia: reintentos POST, TTL de 24 h, hash del cuerpo.
  • Errores: tabla completa de códigos y acciones correctivas.
  • Referencia OpenAPI: especificación interactiva de cada endpoint.
  • Webhooks: canales de notificación del dashboard, firmados con HMAC-SHA256 y reintentados si fallan. Los webhooks de la API pública firmados por clave aún no están disponibles.
  • Changelog: historial de versiones y breaking changes.

Principios operativos

Nunca llames desde el navegador: tu frontend llama a tu propio backend, que a su vez invoca la API pública de CaptainDNS. Es una regla de seguridad: el secreto no debe abandonar tu servidor.

Observabilidad en primer lugar: la cabecera X-Request-Id se devuelve en cada respuesta. Se registra en CaptainDNS y sirve para abrir un ticket de soporte si algo falla.

Herramientas CaptainDNS relacionadas

Los mismos diagnósticos están disponibles como herramientas web, útiles para verificar manualmente el resultado de tu integración:

¿Listo para programar? Lee autenticación y pasa a rate limiting antes de tu primer despliegue en producción.