Manual de Usuario #

ExencionesPro es un módulo addon para WHMCS que automatiza la gestión de exenciones fiscales mediante la validación de NIFs españoles y números VAT intracomunitarios. Esta guía te ayudará a instalar, configurar y utilizar todas las funcionalidades del módulo.

Introducción a ExencionesPro #

ExencionesPro valida automáticamente NIFs españoles y números VAT intracomunitarios, determinando de forma segura si un cliente puede acogerse a la exención de IVA según la normativa española y europea vigente.

El sistema integra validaciones en tiempo real con el servicio VIES de la Comisión Europea, determinando automáticamente las exenciones según la ubicación geográfica del cliente y el tipo de operación (intracomunitaria, extracomunitaria, zonas especiales de España).

¿Para quién es este módulo? #

• Empresas españolas que venden a clientes de la Unión Europea
• Operadores intracomunitarios registrados en VIES (NIF empieza por ES)
• Empresas ubicadas en zonas especiales (Canarias, Ceuta, Melilla)
• Empresas que venden a clientes extracomunitarios (exportaciones)
• Usuarios del módulo Verifactu (ExencionesPro viene incluido)

Características principales #

• Validación automática de VAT: Comprueba en tiempo real contra el servicio VIES
• Validación de NIF español: Verifica el formato de NIFs de personas físicas y empresas
• Exenciones automáticas: Determina y aplica la exención correcta según ubicación
• Textos legales en facturas: Genera automáticamente el motivo de exención
• Soporte OSS: Monitorización del umbral One Stop Shop (10.000€)
• Cola de validación: Reintenta validaciones cuando VIES no responde
• Logs de auditoría: Registro completo de todos los cambios de exención

Pestañas del módulo #

El módulo se organiza en las siguientes pestañas:

1. Configuración: Ajustes generales del módulo y licencia
2. OSS: Panel de monitorización One Stop Shop
3. Cola VAT: Validaciones pendientes de procesar
4. Logs: Historial de cambios de exención
5. Integración: Código para plantillas de facturas

ExencionesPro vs Verifactu #

ExencionesPro puede adquirirse de dos formas:

¿Cómo instalar el módulo? #

1. Sube los archivos del módulo a tu carpeta public_html/whmcs/modules/addons/exencionespro/
2. Ejecuta composer install dentro de la carpeta del módulo para instalar dependencias
3. Dirígete en WHMCS a Ajustes → Módulos Extra y activa el módulo “Exenciones Pro“
4. Introduce la Clave de Licencia (si no tienes Verifactu)
5. Selecciona la ubicación fiscal de tu empresa y configura las opciones necesarias

Requisitos #

• WHMCS 8.x o superior
• PHP 7.4 o superior
• Ioncube 15

Activación de licencia #

Al acceder al módulo por primera vez sin licencia, verás la pantalla de activación:

Introduce tu clave de licencia entregada en la compra y pulsa Activar Licencia.

Una vez activada la licencia, verás el estado en la cabecera del módulo:

¿Cómo desinstalar el módulo? #

1. Dirígete en WHMCS a Ajustes → Módulos Extra y desactiva el módulo “Exenciones Pro“
2. Dirígete a Ajustes → Campos personalizados y elimina el campo “Motivo de exención” y el campo “Tipo de cliente” si no los vas a utilizar más.
3. Si no quieres tener restos en la base de datos, elimina las tablas siguientes:
   
   

Configurar Crons #

El módulo utiliza dos tareas programadas (crons) para el procesamiento asíncrono:

Cron: Revalidar VAT #

Este cron se ejecuta mensualmente y comprueba todos los VAT intracomunitarios de tus clientes, añadiéndolos a la cola de procesamiento. Útil para detectar VATs que ya no son válidos.

Ejemplo: Cada día 1 del mes a las 00:00h

0 0 1 * * /usr/local/bin/php /home/whmcs/public_html/modules/addons/exencionespro/crons/revalidar_vat.php

Cron: Procesar Cola #

Este cron procesa la cola de validaciones VAT pendientes. Ejecuta las validaciones por lotes para evitar sobrecargar el servidor y el servicio VIES.

Ejemplo: Cada 10 minutos

*/10 * * * * /usr/local/bin/php /home/whmcs/public_html/modules/addons/exencionespro/crons/process_queue.php

Configuración #

Ubicación fiscal de tu empresa #

Selecciona dónde está ubicada fiscalmente tu empresa:

• Península: Territorio peninsular español (IVA 21%)
• Canarias: Islas Canarias (IGIC)
• Ceuta: Ciudad autónoma de Ceuta (IPSI)
• Melilla: Ciudad autónoma de Melilla (IPSI)

Esta configuración determina:

• Los textos legales que se aplicarán en las facturas
• Las reglas de exención para clientes de zonas especiales
• El tratamiento de operaciones entre zonas diferentes

Clientes a incluir en el recálculo #

Define qué clientes se incluirán cuando ejecutes una simulación o recálculo masivo:

• Solo Activos: Clientes con estado “Active”
• Activos + Inactivos: Clientes activos e inactivos
• Solo Inactivos: Solo clientes inactivos
• Solo Cerrados: Solo clientes cerrados
• Todos los clientes: Todos sin importar el estado

Validación VAT / VIES #

Habilitar validación de VAT #

Activa esta opción solo si tu empresa está registrada en el sistema VIES y dispones de un NIF intracomunitario válido (como ESB12345678).

Cuando está activado:

• Se validan automáticamente los VAT de clientes de la UE al registrarse o editar sus datos
• Los clientes con VAT válido de otro país UE se marcan como exentos automáticamente
• Se genera el texto de “Inversión del sujeto pasivo” en las facturas

Si tienes problemas con la validación de VAT, el servicio VIES puede tener incidencias temporales. Puedes consultar el estado actual con el botón Ver estado VIES.

Tipo de Cliente #

El campo “Tipo de cliente” permite distinguir entre Particulares y Autónomos/Empresas. Esta distinción es especialmente importante para zonas especiales.

Instalar campo “Tipo de cliente” #

Si el campo no existe, verás un botón para instalarlo:

Una vez instalado, puedes habilitar o deshabilitar su visibilidad para los clientes.

¿Por qué es importante? #

Cuando tu empresa está en la Península y vendes a un cliente de Canarias:

• Si el cliente es Particular: Exento con motivo “Operación no sujeta a IVA…”
• Si el cliente es Autónomo/Empresa: Exento con motivo adicional de “Inversión del sujeto pasivo”

Esta distinción asegura que cada tipo de cliente tenga el texto legal correcto en sus facturas.

Origen del VAT/NIF #

Selecciona de dónde tomará el módulo el número de identificación fiscal del cliente:

Opción 1: tax_id (campo por defecto) #

Usa el campo nativo de WHMCS tax_id. Esta es la opción recomendada para la mayoría de instalaciones.

Opción 2: Campo personalizado #

Si prefieres usar un campo personalizado que hayas creado previamente, selecciona esta opción y elige el campo del desplegable que aparecerá.

Logs y Depuración #

Eliminar logs más antiguos de #

Configura cuánto tiempo se conservarán los logs de cambios de exención:

• Conservar siempre: No se eliminan automáticamente
• X Días/Meses/Años: Se eliminan automáticamente los más antiguos

Activar modo debug de logs #

Registra información detallada en el Activity Log de WHMCS. Útil para diagnosticar problemas.

Cola de Validación VAT #

Límite de intentos de validación VIES #

Número máximo de intentos antes de dejar de intentar la verificación de un VAT mediante cron.

Valor recomendado: 5 intentos

Si un VAT supera este límite de intentos, permanecerá en la cola para revisión manual y no se seguirá intentando automáticamente.

Guardar configuración #

Después de realizar los cambios, pulsa el botón Guardar configuración en la parte inferior del formulario.

OSS (One Stop Shop) #

¿Qué es OSS? #

El One Stop Shop es el régimen especial de IVA de la Unión Europea para ventas B2C (consumidor final) intracomunitarias. Simplifica la declaración de IVA cuando vendes a consumidores de otros países de la UE.

Regla básica OSS #

Panel OSS: Estado y progreso #

Accede a la pestaña OSS para ver el estado de tu facturación B2C intracomunitaria:

Barra de progreso #

La barra de progreso muestra visualmente tu facturación acumulada del año actual respecto al umbral legal de 10.000€:

• Verde: Bajo el umbral, sin preocupaciones
• Amarillo: Acercándote al umbral, prepárate
• Rojo: Muy cerca o superado el umbral

Estados posibles #

Bajo umbral OSS: Puedes seguir aplicando IVA español (21%) a todas tus facturas B2C intracomunitarias.

Próximo al umbral: Te recomendamos ir preparando la transición al régimen OSS.

Has superado el umbral: Debes aplicar IVA del país destino y declarar trimestralmente en el portal OSS de la AEAT.

Facturación por país #

La tabla muestra el desglose de tu facturación B2C por cada país de la UE:

• País: Nombre y código ISO del país
• Facturado (€): Total facturado a ese país en el año
• IVA País (%): Tipo de IVA estándar de ese país

Notificaciones OSS #

Configura hasta 3 notificaciones por email para anticiparte al umbral legal:

Umbrales recomendados #

Cada notificación se envía una sola vez por año cuando se alcanza su umbral.

Email de destino #

Introduce el email donde quieres recibir las alertas OSS. Si lo dejas vacío, se enviará al email del administrador principal de WHMCS.

Gestión de Tipos de IVA #

Esta sección te permite configurar los tipos de IVA (tax rates) de cada país en WHMCS:

Consultar tipos de IVA actualizados #

Pulsa el botón Consultar Tipos de IVA Actualizados para obtener los tipos oficiales de cada país UE desde una fuente externa actualizada.

El sistema comparará los tipos actuales en tu WHMCS con los datos de la API y mostrará las diferencias:

Aplicar tipos seleccionados #

1. Marca los países que quieres actualizar con los checkboxes
2. Opcionalmente, personaliza el nombre del TAX para cada país
3. Pulsa Aplicar X países seleccionados a tbltax

Aplicar 21% a todos (No OSS) #

Si NO estás acogido al OSS y facturas menos de 10.000€ anuales a la UE, puedes aplicar IVA español (21%) a todos los países con un solo clic:

Pulsa Aplicar 21% a Todos (No OSS) para configurar todos los países con:

• Tipo de IVA: 21%
• Nombre: TAX

¿Qué hacer si supero el umbral? #

Si superas los 10.000€ de facturación B2C a la UE:

1. Regístrate en el portal OSS de la AEAT: Portal OSS AEAT
2. Configura los tipos de IVA de cada país en WHMCS usando la herramienta de “Consultar tipos actualizados”
3. Declara trimestralmente tus ventas OSS mediante el Modelo 369
4. Consulta con tu asesor fiscal si tienes dudas sobre tu situación particular

Enlaces útiles #

• Portal OSS de la AEAT
• Portal OSS de la Comisión Europea
• Tipos de IVA por país en la UE

Herramientas #

Simulación y Recálculo de Exenciones #

Esta herramienta está diseñada para la primera puesta en marcha del módulo o cuando tu empresa cambie su ubicación fiscal.

Simular recálculo #

Al pulsar Simular recálculo, el módulo analiza todos los clientes según el filtro configurado y genera un informe con los cambios propuestos, sin modificar ningún dato real.

El simulador muestra:

• Clientes con cambios pendientes: Aquellos cuya exención cambiaría
• Estado actual: Si actualmente está exento o no
• Estado propuesto: Cómo quedaría después del recálculo
• Motivo de exención: El texto legal que se aplicaría

Mostrar todos los clientes #

Por defecto, solo se muestran clientes con cambios pendientes. Marca la casilla “Mostrar todos los clientes” para ver el estado de todos los clientes, incluso los que no tienen cambios.

Aplicar cambios simulados #

Una vez revisada la simulación, pulsa Aplicar cambios para ejecutar los cambios propuestos. Esta acción:

• Actualiza el estado de exención de cada cliente
• Asigna el motivo de exención correspondiente
• Registra cada cambio en los logs
• Elimina el archivo temporal de simulación

¿Cuándo usar el simulador? #

• Primera puesta en marcha: Para sincronizar todos tus clientes existentes
• Cambio de ubicación fiscal: Si tu empresa cambia de Península a Canarias, por ejemplo
• Verificación periódica: Para comprobar que todo está correcto (sin aplicar cambios)

Logs y Auditoría #

Cola de Validación VAT #

Accede a la pestaña Cola VAT para ver las validaciones pendientes de procesar:

Estadísticas #

En la parte superior verás un resumen:

• Total en cola: Número total de registros
• Pendientes: Aún no procesados
• Procesados: Ya verificados (pero pueden seguir en la lista)

Tabla de la cola #

La tabla muestra cada registro con:

• ID Cliente: Enlace a la ficha del cliente
• VAT: El número VAT a validar
• Intentos: Cuántas veces se ha intentado validar
  
  
• Estado: Pendiente o Procesado
• Fecha: Cuándo se añadió a la cola
• Acciones: Eliminar registro individual

¿Cómo funciona la cola? #

Los VAT que no pueden validarse inmediatamente (por timeout o error temporal de VIES) se agregan a esta cola. El cron process_queue.php procesa estos registros periódicamente hasta alcanzar el límite de intentos configurado.

Acciones disponibles #

• Eliminar individual: Quita un registro específico de la cola
• Borrar toda la cola: Elimina todos los registros pendientes

Visor de Logs #

Accede a la pestaña Logs para ver el historial de cambios de exención:

¿Qué registran los logs? #

Cada vez que un cliente cambia de estado de exención (ya sea por los hooks ClientAdd, ClientEdit o por el cronjob), se registra:

• ID Cliente: Identificador del cliente
• Nombre: Nombre del cliente (enlace a su ficha)
• Estado anterior: Exento / No exento
• Estado nuevo: Exento / No exento
• Motivo de exención: El texto legal aplicado (si pasó a exento)
• Fecha: Cuándo ocurrió el cambio
• Origen: ClientAdd, ClientEdit, Cronjob, etc.

Filtrar logs #

Usa el buscador para filtrar por nombre o ID de cliente. También puedes configurar cuántos registros mostrar por página (10, 25, 50, 100).

Borrar logs #

Pulsa Borrar todos para eliminar todos los registros del log. Esta acción requiere confirmación.

La configuración de retención automática de logs se realiza desde la pestaña Configuración.

Soporte y Ayuda #

Si necesitas ayuda o tienes dudas sobre ExencionesPro:

• Consulta la documentación de integración en la pestaña Integración del módulo
• Revisa los logs de actividad en WHMCS para diagnosticar problemas
• Contacta con soporte técnico incluyendo los logs relevantes
• Asegúrate de que tus crons están configurados correctamente

Última actualización: Diciembre 2025