Documentación de la API

Base URL: https://app.jdaudiovisual.online · Versión 1

🔑 Autenticación

Todas las llamadas requieren tu API key en el header X-API-Key (o Authorization: Bearer):

curl -H "X-API-Key: vm_live_TU_API_KEY" \
  https://app.jdaudiovisual.online/api/v1/validate?email=cliente@ejemplo.com

Consigue la tuya gratis (100 validaciones/mes) en /precios.

✅ POST /api/v1/validate

Valida un email en tiempo real (respuesta en milisegundos).

curl -X POST https://app.jdaudiovisual.online/api/v1/validate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: vm_live_TU_API_KEY" \
  -d '{"email":"cliente@ejemplo.com"}'

# Respuesta 200
{
  "email": "cliente@ejemplo.com",
  "valid": true,
  "score": 95,
  "checks": { "syntax": true, "domain": true, "mx": true,
              "disposable": false, "role": false, "free": true },
  "mxRecords": ["gmail-smtp-in.l.google.com"],
  "suggestion": null,
  "reason": "ok",
  "smtp": "unknown",
  "meta": { "quota_used": 42, "quota_limit": 10000, "plan": "pro" }
}

📦 POST /api/v1/bulk

Valida hasta 100 emails por llamada (planes Pro y Escala).

curl -X POST https://app.jdaudiovisual.online/api/v1/bulk \
  -H "Content-Type: application/json" \
  -H "X-API-Key: vm_live_TU_API_KEY" \
  -d '{"emails":["a@ejemplo.com","b@gmial.com"]}'

🧭 Códigos de respuesta

200  Validación procesada (revisa el campo "valid")
400  Body inválido (falta "email" o formato incorrecto)
401  API key ausente, inválida o revocada
402  Cuota mensual agotada → sube de plan en /precios
429  Rate limit excedido → reintenta con backoff

🏷️ Motivos (reason)

ok                  Válido
sintaxis_invalida   Formato incorrecto
dominio_inexistente El dominio no existe en DNS
sin_mx              El dominio no acepta correo
desechable          Email temporal/desechable
posible_typo        Probable error de escritura (ver "suggestion")
cuenta_de_rol       info@, ventas@, soporte@…
buzon_inexistente   El servidor rechazó el buzón (SMTP)

🐍 Ejemplo en Python

import requests

def email_valido(email: str) -> bool:
    r = requests.post(
        "https://app.jdaudiovisual.online/api/v1/validate",
        headers={"X-API-Key": "vm_live_TU_API_KEY"},
        json={"email": email},
        timeout=10,
    )
    r.raise_for_status()
    data = r.json()
    if data["suggestion"]:
        print("¿Quisiste decir", data["suggestion"] + "?")
    return data["valid"] and data["score"] >= 70

🟢 Ejemplo en Node.js

export async function emailValido(email: string): Promise<boolean> {
  const res = await fetch("https://app.jdaudiovisual.online/api/v1/validate", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": process.env.VALIDAMAIL_KEY!,
    },
    body: JSON.stringify({ email }),
  });
  if (res.status === 402) throw new Error("Cuota agotada");
  if (!res.ok) throw new Error(`Error ${res.status}`);
  const data = await res.json();
  return data.valid === true && data.score >= 70;
}

🚦 Rate limits

120 validaciones/minuto por API key en el endpoint simple y 10 lotes/minuto en bulk. Los headers X-RateLimit-* te dicen tu estado. Usa backoff exponencial ante un 429.

🔐 Gestión de keys

# Revocar una key comprometida
curl -X POST https://app.jdaudiovisual.online/api/license/revoke \
  -H "Content-Type: application/json" \
  -d '{"api_key":"vm_live_TU_API_KEY"}'

💳 Facturación

Los planes se gestionan con Lemon Squeezy: suscríbete y recibe tu API key para empezar a validar. Si ya eres cliente y necesitas ayuda con tu suscripción, escríbenos a jdaudiovisual.online@gmail.com.

🔗 Insignia “powered by”

¿Usas ValidaMail en tu producto? Muestra la insignia y consigue backlinks (y nosotros te destacamos en el directorio de integraciones):

<a href="https://app.jdaudiovisual.online" target="_blank" rel="noopener">
  <img src="https://app.jdaudiovisual.online/badge.svg"
       alt="Email verificado con ValidaMail" height="20" />
</a>