AIDocumentos — Guía de uso
Requisitos previos
| Requisito | Detalle |
|---|---|
| FacturaScripts | 2025 o superior |
| PHP | 8.0 o superior |
| API Key Groq | Gratuita en console.groq.com/keys |
| Conversión PDF | Extensión PHP Imagick o comando pdftoppm (poppler-utils) |
| Lectura de correo | Extensión PHP IMAP (opcional) |
Instalación
- Descarga AIDocumentos.zip.
- En FacturaScripts ve a Administración → Plugins → Subir plugin.
- Selecciona el ZIP y confirma la instalación.
- Activa el plugin desde la lista de plugins instalados.
Configuración inicial
Ve a Compras → IA Documentos y despliega el panel «Configuración IA».
API Key de Groq
Pega tu API Key (empieza por gsk_...) y pulsa Guardar. Usa el botón «Guardar y probar» para verificar que la clave funciona antes de continuar.
La API de Groq es gratuita para un uso normal (facturas de empresa). No se necesita tarjeta de crédito para el plan gratuito.
Empresa receptora por defecto (si tienes varias empresas)
Si FacturaScripts tiene más de una empresa configurada, aparecerá un selector. Elige la empresa a la que irán las facturas cuando la IA no detecte el NIF receptor en el documento. El plugin intentará siempre identificar la empresa por este orden:
- NIF del receptor detectado en el documento → búsqueda en la tabla de empresas.
- Nombre del receptor detectado → búsqueda parcial en empresas.
- Empresa por defecto configurada aquí.
Subida manual de facturas
- Ve a Compras → IA Documentos → pestaña «Escanear Documento».
- Haz clic en el área de subida o arrastra el archivo (JPG, PNG, WEBP, PDF).
- Pulsa «Analizar con IA» — en unos segundos verás los datos extraídos.
- Revisa los campos: proveedor, NIF, fecha, base, IVA, IRPF, total.
- Si todo es correcto pulsa «Aprobar y crear factura». Si no, edita los campos directamente y vuelve a aprobar. Para descartar el borrador pulsa «Rechazar».
Consejo: Si la extracción es incorrecta (documento borroso, rotado, etc.) puedes pulsar «Re-analizar con IA» para volver a procesar el mismo archivo sin necesidad de subirlo de nuevo.
Automatización por correo (IMAP)
El plugin puede leer adjuntos de facturas de tu buzón de entrada automáticamente.
Configuración IMAP
Ve a Compras → IA Documentos → «Configuración Correo (IMAP)»:
| Campo | Ejemplo |
|---|---|
| Servidor IMAP | imap.gmail.com |
| Puerto | 993 |
| Usuario | [email protected] |
| Contraseña | tu contraseña o contraseña de aplicación |
| Carpeta | INBOX (o la carpeta donde recibes facturas) |
| SSL | Activado (recomendado) |
| Carpeta de exportación | /var/backups/facturas (opcional) |
Pulsa «Guardar y probar conexión» para verificar. Después pulsa «Revisar correos ahora» para un primer procesamiento manual.
Cron automático
Activa «Revisión automática por cron» y selecciona la hora diaria de procesamiento. FacturaScripts ejecutará la revisión automáticamente cada día a esa hora.
Los adjuntos válidos son: PDF, JPG, PNG, WEBP y GIF. Se procesa el primero que se encuentre en cada correo.
Revisar y gestionar documentos
Todos los documentos procesados (manuales y de correo) aparecen en el Historial con uno de estos estados:
| Estado | Significado |
|---|---|
| Borrador | Extraído por IA, pendiente de revisión humana |
| Importado | Factura de proveedor creada en FacturaScripts |
| Descartado | Rechazado manualmente |
| Duplicado | Detectado como factura ya existente (mismo NIF + fecha + importe) |
Haz clic en cualquier fila del historial para abrir el detalle, que tiene dos pestañas:
- Vista previa — muestra el documento original (PDF o imagen) junto con los datos extraídos y los botones de acción.
- Datos extraídos — formulario editable con todos los campos; también tiene los botones de acción.
Botones de acción
| Botón | Qué hace |
|---|---|
| Aprobar y crear factura | Crea la factura de proveedor en FacturaScripts y marca el documento como Importado |
| Rechazar | Marca el documento como Descartado (pide confirmación) |
| Re-analizar con IA | Vuelve a procesar el archivo guardado con la IA y actualiza todos los campos |
Filtros del historial
El historial permite filtrar por: Estado (borrador, importado, descartado, duplicado), Origen (manual, email), Proveedor (búsqueda por texto) y Rango de fechas de factura. Y ordenar por: fecha de procesamiento, fecha de factura, importe total o nivel de confianza.
Indicador de confianza
La IA devuelve un porcentaje de confianza (0–100) que indica qué tan legible era el documento:
| Rango | Interpretación |
|---|---|
| 80–100 | Alta confianza — datos probablemente correctos |
| 50–79 | Confianza media — conviene revisar fecha e importes |
| 0–49 | Baja confianza — documento borroso o poco estructurado; revisar todo |
Preguntas frecuentes
¿Cuánto cuesta la API de Groq? El plan gratuito de Groq permite miles de peticiones al mes, más que suficiente para el volumen habitual de facturas de una pyme. Consulta los límites actuales en console.groq.com.
¿Mis facturas se almacenan en los servidores de Groq? No. Según la política de privacidad de Groq, las imágenes enviadas a su API no se almacenan ni se usan para entrenar modelos.
El plugin no convierte PDFs. ¿Qué hago?
Instala la extensión PHP Imagick (recomendado) o el paquete poppler-utils en tu servidor (proporciona el comando pdftoppm). En cPanel/Plesk suele estar disponible en las extensiones PHP. En servidores propios: apt install poppler-utils (Debian/Ubuntu) o yum install poppler-utils (CentOS).
¿Funciona con facturas en otros idiomas? Sí. El modelo Llama 4 Scout entiende facturas en español, inglés, francés, portugués e italiano, entre otros.
¿Se detectan facturas con IGIC (Canarias)? Sí. El plugin detecta los tipos 7% y 3% de IGIC además de todos los tipos de IVA peninsular.
¿Qué pasa si apruebo una factura duplicada? El sistema la detecta antes de crearla y la marca como Duplicada en lugar de generar una factura repetida.