Guia de instalación y configuración de AIScanConnect

Guía de instalación y configuración de AIScanConnect

Esta guía está pensada para usuarios no técnicos y explica cómo instalar, configurar y poner en marcha AIScanConnect en FacturaScripts.

AIScanConnect permite:

subir facturas manualmente;
analizarlas con AiScan;
revisar y corregir los datos antes de importar;
importar facturas de proveedor;
recoger automáticamente facturas desde una cuenta de correo;
recuperar facturas antiguas del buzón;
detectar documentos duplicados;
conservar el PDF original vinculado a la factura.

1. Requisitos previos

Antes de instalar AIScanConnect, la instalación debe disponer de:

FacturaScripts 2026 o posterior.
PHP 8.1 o posterior.
Plugin AiScan instalado y activado.
Al menos un proveedor de inteligencia artificial configurado en AiScan.
Para recoger facturas por correo: extensión IMAP de PHP habilitada.
El cron de FacturaScripts debe estar funcionando para que los documentos se procesen automáticamente en segundo plano.

AIScanConnect depende de AiScan, por lo que AiScan debe instalarse primero.

2. Instalar AiScan

En FacturaScripts, entra como administrador.

Ve a:

Administrador → Plugins

Sube el archivo ZIP de AiScan y actívalo.

Después abre la configuración de AiScan y comprueba que está habilitado.

Configurar el proveedor de IA

AiScan permite utilizar proveedores como:

OpenAI
Google Gemini
Mistral
xAI Grok
servicios compatibles con OpenAI

Para una configuración con OpenAI, por ejemplo, tendrás que introducir tu clave API de OpenAI.

Una configuración típica sería:

AiScan activado:       Sí
Proveedor:             OpenAI
Clave API:             tu clave API
Modelo:                el modelo que vayas a utilizar

No es necesario modificar el prompt de extracción.

Importante

AIScanConnect no tiene su propia clave de OpenAI.

Utiliza la configuración de AiScan.

AiScan
 └── Proveedor IA + API Key
             │
             ▼
      AIScanConnect

3. Comprobar AiScan antes de continuar

Antes de instalar AIScanConnect, recomiendo comprobar que AiScan puede analizar una factura.

Si AiScan reconoce correctamente una factura, ya puedes continuar.

Esto permite separar posibles problemas:

AiScan no funciona
→ primero solucionar AiScan

AiScan funciona
→ instalar AIScanConnect

4. Instalar AIScanConnect

Ve nuevamente a:

Administrador → Plugins

Sube el archivo ZIP de AIScanConnect y actívalo.

FacturaScripts detectará automáticamente que necesita AiScan.

Una vez activado aparecerá:

Compras → AIScanConnect

con estas opciones:

Bandeja
Importar documentos
Correo

También aparecerá una nueva configuración en:

Administrador → Panel de control → AIScanConnect

5. Primera configuración recomendada

Entra en:

Administrador → Panel de control → AIScanConnect

En el apartado de opciones de escaneo, selecciona cómo quieres que se procesen normalmente las facturas.

Para una instalación estándar recomiendo:

Modelo IA:
El modelo de AiScan que hayas probado

Modo de importación:
Factura detallada

Importar como:
Proveedor

Usar facturas anteriores como contexto:
Sí

Convertir imágenes a PDF:
Sí

Factura detallada

Es la opción que utilizaría normalmente.

AIScanConnect intenta obtener:

Artículo 1
Artículo 2
Artículo 3
...
Base imponible
IVA
Total

y después crea las líneas correspondientes en FacturaScripts.

Factura resumida

Utilízala únicamente cuando no necesites importar individualmente los artículos.

La factura se contabilizará principalmente a partir de sus bases e impuestos.

6. Proveedor o acreedor

AIScanConnect permite seleccionar:

Proveedor

para compras de mercancías o productos.

Acreedor

para determinados gastos o servicios.

Para la mayoría de facturas de compra, la opción adecuada será:

Proveedor

7. Usar facturas anteriores como contexto

La opción:

Usar facturas anteriores como contexto

permite que AIScanConnect utilice facturas anteriores del mismo proveedor para mejorar la interpretación de nuevas facturas.

Puede resultar especialmente útil cuando un proveedor siempre utiliza el mismo diseño.

Hay que tener en cuenta que puede implicar una segunda petición a la IA, por lo que aumenta ligeramente el consumo de API.

Mi recomendación para producción sería dejarla activada si se trabaja habitualmente con los mismos proveedores.

8. Realizar la primera prueba manual

Ve a:

Compras → AIScanConnect → Importar documentos

Puedes:

pulsar para seleccionar archivos;
o arrastrarlos directamente a la pantalla.

Se pueden seleccionar varios documentos simultáneamente.

Formatos admitidos:

PDF
JPG
JPEG
PNG
WebP

Para una primera prueba seleccionaría una única factura PDF sencilla.

Después pulsa:

Subir y analizar

9. Qué ocurre después de subirla

AIScanConnect guarda primero el documento y lo coloca en la cola.

Puedes ver estados como:

En cola
Procesando
Pendiente de revisión

No es necesario permanecer en la pantalla esperando.

Cuando termine aparecerá como:

Pendiente de revisión

en:

Compras → AIScanConnect → Bandeja

10. Comprobar que funciona el cron

Esta es una prueba especialmente sencilla para un usuario no técnico.

Sube una factura.

Si aparece:

En cola

y después de unos segundos o minutos cambia a:

Procesando
Pendiente de revisión

el cron está funcionando.

Si permanece indefinidamente en:

En cola

AIScanConnect probablemente está bien instalado, pero el cron de FacturaScripts no se está ejecutando.

En ese caso debe revisarlo el administrador del servidor o alojamiento.

11. Revisar una factura

Abre la factura desde la Bandeja.

A la izquierda podrás visualizar el documento original y a la derecha los datos detectados.

Conviene comprobar especialmente:

Proveedor
NIF/CIF
Número de factura
Fecha
Subtotal
Impuestos
Total
Líneas de artículos

AIScanConnect intenta encontrar automáticamente el proveedor en FacturaScripts mediante datos como el NIF/CIF.

Si existe una coincidencia clara lo seleccionará automáticamente.

12. Guardar, validar o importar

En la pantalla de revisión encontrarás distintas acciones.

Guardar

Guarda las modificaciones pero no crea todavía la factura de proveedor.

Úsalo cuando hayas corregido algún dato manualmente.

Validar

Comprueba que la factura es coherente.

Por ejemplo:

Subtotal
+ IVA
- Retenciones
= Total factura

También comprueba las líneas.

Validar e importar

Realiza las comprobaciones y, si todo está correcto, crea la factura en FacturaScripts.

Esta será normalmente la acción final.

13. Qué hacer si aparece un aviso rojo

AIScanConnect no modifica automáticamente una factura que no cuadra.

Por ejemplo puede mostrar:

Subtotal:       11,60 €
Impuestos:       3,00 €
Calculado:      14,60 €
Total factura:  17,29 €

Diferencia:      2,69 €

Esto significa que en el documento existe algún concepto que no está correctamente representado en las líneas.

Puede ser:

gastos de envío;
portes;
embalajes;
otros gastos;
descuentos;
cargos adicionales.

Revisa el PDF original.

Si, por ejemplo, aparecen 2,69 € de gastos de envío, añade manualmente una línea:

Descripción: Gastos de envío
Cantidad:    1
Precio:      2,69
IVA:         el IVA correspondiente

Y recuerda revisar también el Subtotal.

Por ejemplo:

Artículos         11,60 €
Gastos envío       2,69 €
────────────────────────
Subtotal          14,29 €
IVA                3,00 €
Total             17,29 €

Después:

pulsa Guardar;
comprueba que el subtotal es correcto;
pulsa Validar e importar.

14. Facturas duplicadas

AIScanConnect detecta automáticamente cuando se intenta introducir nuevamente el mismo documento.

Esto funciona tanto para:

archivos subidos manualmente;
como adjuntos recogidos por correo.

Por tanto, recibir o subir dos veces el mismo PDF no debería generar dos documentos ni consumir nuevamente IA innecesariamente.

15. Configurar la recepción automática por correo

Esta parte es opcional.

Ve a:

Administrador → Panel de control → AIScanConnect

y pulsa:

Nueva cuenta

Encontrarás los datos del buzón.

Nombre

Es simplemente un nombre descriptivo.

Por ejemplo:

Facturas proveedores

Activado

Mi recomendación es no marcarlo todavía.

Primero configuraremos y probaremos la conexión.

Servidor

Es el servidor IMAP de tu proveedor de correo.

Por ejemplo, para Gmail:

imap.gmail.com

Puerto

Para conexiones SSL/TLS normalmente:

Seguridad

Normalmente:

SSL/TLS

Usuario

Normalmente es la dirección completa:

facturas@miempresa.es

Contraseña

Introduce la contraseña IMAP.

En Gmail, si la cuenta utiliza verificación en dos pasos, normalmente deberás utilizar una contraseña de aplicación, no la contraseña habitual de Gmail.

Carpeta

Normalmente:

INBOX

16. Ejemplo completo: configurar una cuenta de Gmail

Para Gmail, AIScanConnect puede conectarse mediante IMAP usando una contraseña de aplicación.

Google solo permite crear contraseñas de aplicación cuando la cuenta tiene activada la Verificación en dos pasos. Si la opción no aparece, puede deberse a la configuración de seguridad de la cuenta, a una cuenta administrada por una organización o a que esté activada Protección Avanzada.

16.1. Activar la verificación en dos pasos

Entra en tu Cuenta de Google.
Abre Seguridad e inicio de sesión.
Busca el apartado Cómo inicias sesión en Google.
Selecciona Verificación en dos pasos.
Sigue las instrucciones de Google hasta dejarla activada.

Si ya utilizas la verificación en dos pasos, puedes saltar este apartado.

16.2. Crear una contraseña de aplicación

Entra de nuevo en tu Cuenta de Google.
Accede a Seguridad.
Busca Contraseñas de aplicaciones.
Google puede pedirte que vuelvas a identificarte.
Crea una nueva contraseña para AIScanConnect.
Como nombre identificativo puedes utilizar, por ejemplo:

AIScanConnect

Google mostrará una contraseña específica para la aplicación.
Cópiala y guárdala temporalmente: Google normalmente solo la muestra una vez.

La contraseña de aplicación se utiliza en AIScanConnect en lugar de la contraseña normal de Gmail.

16.3. Configuración en AIScanConnect

En:

Administrador → Panel de control → AIScanConnect

crea o edita una cuenta de correo con estos datos:

Nombre:          Facturas Gmail
Servidor:        imap.gmail.com
Puerto:          993
Seguridad:       SSL/TLS
Usuario:         correo@gmail.com
Contraseña:      contraseña de aplicación de Google
Carpeta:         INBOX

Ejemplo:

Nombre:          Facturas proveedores
Servidor:        imap.gmail.com
Puerto:          993
Seguridad:       SSL/TLS
Usuario:         facturas.miempresa@gmail.com
Contraseña:      [contraseña de aplicación]
Carpeta:         INBOX

16.4. Probar la conexión

Antes de activar la cuenta:

pulsa Guardar;
pulsa Probar conexión;
comprueba que AIScanConnect confirma que la conexión IMAP es correcta.

Si la prueba falla:

comprueba que el usuario sea la dirección completa de Gmail;
asegúrate de utilizar la contraseña de aplicación y no la contraseña habitual;
verifica que la verificación en dos pasos esté activada;
si has cambiado recientemente la contraseña principal de Google, genera una nueva contraseña de aplicación, ya que Google puede revocar las anteriores.

Cuando la prueba sea correcta, ya puedes marcar:

Activado

y guardar la configuración.

17. Ejemplo completo: correo corporativo gestiontotalerp.es

AIScanConnect también puede utilizar una cuenta de correo corporativa alojada en el propio servidor o en el proveedor de correo de la empresa.

Como ejemplo utilizaremos:

facturas@gestiontotalerp.es

En una instalación con correo corporativo de gestiontotalerp.es, una configuración típica sería:

Nombre:          Facturas gestiontotalerp.es
Servidor:        mail.gestiontotalerp.es
Puerto:          993
Seguridad:       SSL/TLS
Usuario:         facturas@gestiontotalerp.es
Contraseña:      contraseña del buzón
Carpeta:         INBOX

17.1. Crear o preparar el buzón

Antes de configurar AIScanConnect, asegúrate de que existe una cuenta de correo dedicada, por ejemplo:

facturas@gestiontotalerp.es

Lo ideal es utilizar un buzón específico para recepción de facturas de proveedores.

También se puede utilizar una cuenta ya existente, pero un buzón dedicado simplifica mucho la gestión.

17.2. Comprobar los datos IMAP

Los datos habituales serían:

Servidor IMAP:   mail.gestiontotalerp.es
Puerto IMAP:     993
Seguridad:       SSL/TLS
Usuario:         dirección de correo completa
Contraseña:      contraseña del buzón
Carpeta:         INBOX

Si el correo de tu dominio está alojado en otro proveedor, utiliza el servidor IMAP indicado por ese proveedor. El nombre mail.gestiontotalerp.es es el ejemplo utilizado en esta guía para un correo corporativo propio.

17.3. Configurarlo en AIScanConnect

En:

Administrador → Panel de control → AIScanConnect

pulsa Nueva cuenta e introduce:

Nombre:          Facturas gestiontotalerp.es
Servidor:        mail.gestiontotalerp.es
Puerto:          993
Seguridad:       SSL/TLS
Usuario:         facturas@gestiontotalerp.es
Contraseña:      ********
Carpeta:         INBOX

Deja inicialmente:

Activado:        No

Guarda la cuenta y pulsa:

Probar conexión

Si la prueba es correcta, vuelve a editarla y marca:

Activado:        Sí

17.4. Si no conecta

Comprueba:

que el buzón existe;
que la contraseña sea correcta;
que el servidor sea mail.gestiontotalerp.es o el indicado por tu proveedor;
que se utilice el puerto 993;
que la seguridad sea SSL/TLS;
que el usuario sea la dirección completa, por ejemplo facturas@gestiontotalerp.es;
que el servidor tenga habilitado el servicio IMAP;
que el certificado SSL del servidor de correo sea válido.

No utilices los puertos SMTP 465 o 587 en esta configuración: esos puertos son para enviar correo. AIScanConnect necesita IMAP para leer los mensajes recibidos.

19. Días iniciales

El campo:

Días iniciales

indica cuánto correo debe revisar AIScanConnect la primera vez que conecta con ese buzón.

Recomiendo:

30 días

Esto evita que al conectar una cuenta antigua por primera vez AIScanConnect tenga que recorrer años de correo.

Importante

Este valor solo afecta a la primera sincronización.

Cambiar posteriormente de 30 a 120 días no hará que la sincronización normal retroceda automáticamente 120 días.

Para eso existe Recuperar histórico.

18. Histórico de correo

El campo:

Días de recuperación histórica

puede dejarse, por ejemplo, en:

120 días

Después, desde:

Compras → AIScanConnect → Correo

podrás usar:

Recuperar histórico

cuando quieras buscar facturas antiguas.

Esta operación:

busca mensajes anteriores;
ignora los mensajes ya procesados;
detecta documentos duplicados;
añade únicamente documentos nuevos;
no modifica el horario de recogida diaria.

20. Configurar la hora automática

En la configuración del buzón encontrarás:

Hora
Minuto

Por ejemplo:

Hora:    06
Minuto:  30

AIScanConnect intentará recoger el correo una vez al día a partir de esa hora.

No necesita acertar exactamente a las 06:30.

Si el cron se ejecuta, por ejemplo, a las 06:32:

06:30 prevista
06:32 cron
→ realiza la recogida

pero no volverá a realizarla automáticamente ese mismo día.

21. Activar finalmente el buzón

Una vez que:

la conexión IMAP funciona;
el modelo de IA está seleccionado;
el horario es correcto;

marca:

Activado

y pulsa Guardar.

A partir de ese momento la recogida será automática.

22. Probar la recogida sin esperar al horario

Ve a:

Compras → AIScanConnect → Correo

Selecciona la cuenta y pulsa:

Recoger ahora

AIScanConnect:

conecta al buzón
      ↓
busca nuevos mensajes
      ↓
extrae adjuntos válidos
      ↓
detecta duplicados
      ↓
envía documentos nuevos a la cola
      ↓
aparecen en Bandeja

El correo original no se elimina ni se mueve.

AIScanConnect tampoco necesita marcarlo como leído.

23. Recuperar facturas antiguas

Desde:

Compras → AIScanConnect → Correo

localiza:

Recuperar histórico

Indica, por ejemplo:

120 días

y pulsa el botón.

Puede tardar un poco dependiendo de la cantidad de correos.

Los documentos ya conocidos se detectarán como duplicados.

24. Trabajo diario recomendado

Una vez configurado, para el usuario el proceso diario debería reducirse prácticamente a:

1. Entrar en Compras
2. AIScanConnect
3. Bandeja
4. Abrir primera factura pendiente
5. Revisar
6. Validar e importar
7. AIScanConnect abre automáticamente la siguiente

Así sucesivamente hasta que aparezca:

No quedan facturas pendientes de revisión.

25. Qué pasa con el PDF original

Cuando una factura se importa en FacturaScripts, AIScanConnect reutiliza el mismo documento original.

No crea otra copia innecesaria.

AIScanConnect ───────┐
                     ├── mismo PDF
FacturaProveedor ────┘

El documento seguirá disponible desde la factura importada.

26. Restablecer AIScanConnect

En:

Administrador → Panel de control → AIScanConnect

existe al final una zona denominada:

Mantenimiento / Restablecer AIScanConnect

Esta opción está pensada principalmente para:

instalaciones de prueba;
demostraciones;
preparar una instalación antes de entregarla al cliente.

Para utilizarla hay que escribir exactamente:

RESTABLECER

y confirmar nuevamente la operación.

Se eliminan:

Bandeja de AIScanConnect
Revisiones pendientes
Configuración IMAP
Credenciales IMAP
Historial de correo
Estadísticas
Trabajos de AIScanConnect
Archivos exclusivos del plugin

Muy importante

Las facturas ya importadas en FacturaScripts NO se eliminan.

Tampoco se elimina el PDF si sigue vinculado a una factura de proveedor.

27. Configuración recomendada para una instalación nueva

Para un usuario normal partiría de:

AIScan
────────────────────────────
Activado                  Sí
Proveedor IA              OpenAI / proveedor elegido
Modelo                    modelo probado


AIScanConnect
────────────────────────────
Factura detallada         Sí
Importar como             Proveedor
Usar histórico            Sí
Convertir imágenes PDF    Sí


Correo IMAP
────────────────────────────
Activado                  Sí, después de probar
Carpeta                    INBOX
Primera sincronización     30 días
Recuperación histórica    120 días
Recogida automática       1 vez/día

28. Regla de trabajo recomendada

AIScanConnect automatiza la lectura de las facturas, pero antes de importar siempre conviene revisar:

proveedor;
número de factura;
fecha;
líneas;
subtotal;
impuestos;
total.

Si aparece un aviso rojo, no debe forzarse la importación.

Hay que corregir la factura hasta que los importes cuadren.

29. Resumen de puesta en marcha

La secuencia recomendada para una instalación nueva es:

1. Instalar y activar AiScan
2. Configurar proveedor de IA
3. Probar AiScan con una factura
4. Instalar y activar AIScanConnect
5. Configurar opciones de escaneo
6. Subir una factura manualmente
7. Comprobar que pasa de En cola a Pendiente de revisión
8. Revisar e importar la factura
9. Configurar la cuenta IMAP
10. Probar conexión
11. Probar Recoger ahora
12. Activar la cuenta
13. Configurar horario diario
14. Usar Recuperar histórico si es necesario

Con esto AIScanConnect queda listo para trabajar en producción.