• AIDocumentos — Guía de uso

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

1. Descarga AIDocumentos.zip.
2. En FacturaScripts ve a Administración → Plugins → Subir plugin.
3. Selecciona el ZIP y confirma la instalación.
4. 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:

1. NIF del receptor detectado en el documento → búsqueda en la tabla de empresas.
2. Nombre del receptor detectado → búsqueda parcial en empresas.
3. Empresa por defecto configurada aquí.

Subida manual de facturas

1. Ve a Compras → IA Documentos → pestaña «Escanear Documento».
2. Haz clic en el área de subida o arrastra el archivo (JPG, PNG, WEBP, PDF).
3. Pulsa «Analizar con IA» — en unos segundos verás los datos extraídos.
4. Revisa los campos: proveedor, NIF, fecha, base, IVA, IRPF, total.
5. 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.

Subida por lotes

Además de subir facturas de una en una, tienes la opción «Subida por lotes» para procesar varios archivos a la vez (PDF/JPG/PNG/WEBP). Cada archivo genera un borrador en el Historial que después revisas e importas por separado.

Editar los datos antes de importar

Si la IA no detecta bien algún dato (por ejemplo el proveedor, el CIF/NIF o el número de factura), puedes corregirlo antes de crear la factura:

1. Abre el borrador (desde el Historial o desde el resultado del escaneo) y ve a la pestaña «Datos extraídos».
2. Corrige los campos que necesites y pulsa Guardar. Importante: guarda la edición antes de pulsar «Aprobar y crear factura»; el plugin importa exactamente lo que quede guardado en el borrador.
3. Pulsa «Aprobar y crear factura»: la factura se crea con los datos revisados por ti, no con los que había detectado la IA.

Esto aplica tanto a la subida individual como a la subida por lotes.

Editar las líneas

En la pantalla de resultado puedes revisar y editar la tabla de líneas (descripción, cantidad, precio e IVA) y añadir o quitar líneas. Los cambios se respetan al crear la factura.

Modos de importación

En «Configuración IA» eliges cómo se crean las líneas de la factura:

| Modo | Cuándo usarlo | |------|----------------| | Líneas detalladas | La factura se crea con cada línea que detecta la IA. Ideal cuando el desglose es fiable. | | Solo totales | La factura se crea con una única línea por base/IVA/total. Más seguro cuando el desglose no cuadra (típico en tickets de combustible). |

Como salvaguarda, aunque elijas «Líneas detalladas», si las líneas extraídas no suman la base de la factura (con un 1 % de tolerancia) el plugin importa por totales para que el importe final coincida siempre con la vista previa.

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 | facturas@miempresa.com | | 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 de visión configurado (por defecto Qwen en Groq) 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.

¿Puedo editar el proveedor, el CIF o el número de factura antes de importar? Sí. Corrige los campos en la pestaña «Datos extraídos», pulsa Guardar y después «Aprobar y crear factura». La factura se crea con lo que hayas revisado.

¿El plugin usa solo Groq? No. Groq es el proveedor gratuito recomendado, pero también admite OpenAI, Gemini, Mistral y modelos locales compatibles con OpenAI (Ollama, LM Studio). Puedes elegir el proveedor activo en «Configuración IA».

En una instalación con varias empresas, ¿cómo fijo la forma de pago de cada una? El plugin asigna una forma de pago válida para la empresa receptora. Si quieres forzar una concreta por empresa, crea el ajuste codpago_empresa_<idempresa> con el código de forma de pago deseado.