Epic Numverify

Un plugin independiente de WordPress para validación de números de teléfono usando la API de Numverify. Este plugin extrae la funcionalidad de validación telefónica del plugin Forms VDI para uso independiente.

🌟 Características

• ✅ Validación de números de teléfono en tiempo real
• �🇸 Validación específica para números de USA (formato exacto)
• 📱 Formateo automático mientras escribes (XXX) XXX-XXXX
• �🌍 Soporte para múltiples países
• 📊 Panel de administración completo con estadísticas
• 📝 Sistema de logs detallado
• 🔧 API de desarrollador fácil de usar
• 📱 Validación automática en formularios
• 🚀 Shortcodes para uso flexible
• 🎯 Integración AJAX sin recarga de página
• ⚡ Soporte específico para Elementor Forms

📋 Requisitos

• WordPress 5.0 o superior
• PHP 7.4 o superior
• API Key de Numverify (obtener en numverify.com)

🚀 Instalación

1. Descargar el plugin
2. Subir a /wp-content/plugins/epic-numverify/
3. Activar el plugin desde el panel de administración
4. Configurar la API key en Epic Numverify > Settings

⚙️ Configuración

1. Ve a Epic Numverify > Settings en tu panel de WordPress
2. Ingresa tu API key de Numverify
3. Selecciona el país por defecto
4. Habilita el logging si deseas estadísticas
5. Prueba la conexión con el botón "Test API Key"

🔧 Uso

Función PHP

$result = epic_numverify_validate_phone('555-123-4567', 'US');
if ($result['valid']) {
    echo 'Número válido!';
} else {
    echo 'Número inválido: ' . $result['error'];
}

Shortcode

[epic_numverify_validate phone="555-123-4567" country="US" return="message"]

Parámetros del shortcode:

• phone: Número de teléfono a validar
• country: Código de país (opcional, por defecto US)
• return: Formato de respuesta (boolean, json, message)

Validación AJAX

EpicNumverify.validate('555-123-4567', 'US', function(isValid, data) {
    if (isValid) {
        console.log('Número válido!', data);
    } else {
        console.log('Error:', data.message);
    }
});

Validación Automática

Los campos de teléfono se validan automáticamente en estos casos:

<!-- Campos detectados automáticamente -->
<input type="tel" name="phone" data-country="US" />
<input type="text" name="user_phone" />
<input type="text" name="telephone" />
<input type="text" name="telefono" />

<!-- Soporte específico para Elementor -->
<input type="tel" name="form_fields[tel]" class="elementor-field" />

Formularios compatibles:

• ✅ Elementor Forms
• ✅ Contact Form 7
• ✅ Gravity Forms
• ✅ Formularios HTML personalizados

🇺🇸 Validación Específica para USA

Para números de USA, el plugin aplica validaciones adicionales:

Formato aceptado:

• 📱 4049387541 - 10 dígitos estándar
• 📱 14049387541 - Con código de país USA (1)
• 📱 +14049387541 - Formato internacional completo
• 📱 Salida formateada: 404-938-7541 - Compatible con Elementor

Todos los formatos se convierten automáticamente al formato estándar USA: XXX-XXX-XXXX

Reglas de validación:

• ✅ Exactamente 10 dígitos (sin código de país)
• ✅ Código de área no puede empezar con 0 o 1
• ✅ Código de intercambio no puede empezar con 0 o 1
• ❌ Códigos de área reservados (555, 911, 800, etc.)

<!-- El campo se formateará automáticamente para USA -->
<input type="tel" name="form_fields[tel]" data-country="US" />

🎨 Configuración Específica para Elementor

El plugin detecta automáticamente campos de Elementor y ajusta la validación:

Configuración automática:

• ✅ Actualiza el pattern para permitir formato USA: [\d\-\+]+
• ✅ Establece maxlength="12" para formato completo: 404-938-7541
• ✅ Cambia el title para mejor UX: "Enter USA phone number. Format: 404-938-7541"

En el Editor de Elementor:

1. Agrega un campo "Tel" a tu formulario
2. En "Advanced" → deja el "Pattern" por defecto
3. El plugin se encarga automáticamente de la configuración

Si tienes problemas de validación:

<!-- Patrón manual en Elementor (si es necesario) -->
<!-- Pattern: [\d\-\+]+ -->
<!-- Permite: dígitos, guiones, signo + -->
<!-- Formato resultante: 404-938-7541 -->

📊 Panel de Administración

Settings

• Configurar API key
• Habilitar/deshabilitar validación
• Configurar país por defecto
• Controlar el logging

Logs & Stats

• Estadísticas de validaciones de los últimos 30 días
• Desglose por países
• Logs detallados de todas las validaciones
• Opción para limpiar logs

🔌 Hooks y Eventos

JavaScript Events

$('input[name="phone"]').on('epic_numverify_valid', function(event, data) {
    // Número válido
    console.log('Número válido:', data);
});

$('input[name="phone"]').on('epic_numverify_invalid', function(event, data) {
    // Número inválido
    console.log('Número inválido:', data);
});

WordPress Filters

// Modificar configuración por defecto
add_filter('epic_numverify_default_country', function($country) {
    return 'CA'; // Cambiar a Canadá
});

// Personalizar mensajes de error
add_filter('epic_numverify_error_message', function($message, $error_type) {
    if ($error_type === 'invalid_format') {
        return 'Por favor ingresa un número válido';
    }
    return $message;
}, 10, 2);

🎨 Personalización CSS

/* Campos válidos */
.epic-numverify-valid {
    border-color: #28a745 !important;
    background-color: #d4edda;
}

/* Campos inválidos */
.epic-numverify-invalid {
    border-color: #dc3545 !important;
    background-color: #f8d7da;
}

/* Mensaje de estado */
.epic-numverify-status {
    margin-top: 5px;
    font-size: 12px;
}

.epic-numverify-status.valid {
    color: #28a745;
}

.epic-numverify-status.invalid {
    color: #dc3545;
}

🔧 API de Desarrollador

Clase Principal

// Validar número
$validator = new Epic_Numverify_Validator();
$result = $validator::validate('555-123-4567', 'US');

// Probar conexión API
$test = $validator::test_api_connection();

// Obtener estadísticas
$stats = $validator::get_validation_stats(30); // últimos 30 días

Estructura de Respuesta

Array(
    'valid' => true/false,
    'data' => Array(
        'valid' => true/false,
        'number' => '15551234567',
        'local_format' => '(555) 123-4567',
        'international_format' => '+1 555 123 4567',
        'country_prefix' => '+1',
        'country_code' => 'US',
        'country_name' => 'United States of America',
        'location' => 'United States of America',
        'carrier' => 'T-Mobile USA, Inc.',
        'line_type' => 'mobile'
    ),
    'error' => 'Mensaje de error (si aplica)'
)

🐛 Resolución de Problemas

Error de API Key

• Verificar que la API key sea correcta
• Comprobar que no hayas excedido el límite de llamadas
• Usar el botón "Test API Key" en la configuración

No se Validan los Campos

• Verificar que el plugin esté activado
• Comprobar que la validación esté habilitada en Settings
• Revisar la consola del navegador por errores JavaScript

Problemas de Rendimiento

• Considerar deshabilitar la validación automática
• Usar validación manual con botones
• Ajustar el timeout en el código si es necesario

📝 Changelog

1.0.0

• Lanzamiento inicial
• Validación básica con Numverify API
• Panel de administración completo
• Sistema de logs y estadísticas
• Validación automática en formularios
• Shortcodes y API de desarrollador

🤝 Contribuir

1. Fork el repositorio
2. Crear una rama para tu feature (git checkout -b feature/nueva-funcionalidad)
3. Commit tus cambios (git commit -am 'Agregar nueva funcionalidad')
4. Push a la rama (git push origin feature/nueva-funcionalidad)
5. Crear un Pull Request

📄 Licencia

Este plugin está licenciado bajo GPL v2 o posterior.

🆘 Soporte

Para soporte técnico o reportar bugs:

• Crear un issue en GitHub
• Contactar a [tu email de soporte]

🙏 Créditos

Desarrollado por Mimer GT
Basado en la funcionalidad de validación del plugin Forms VDI
Utiliza la API de Numverify