> For the complete documentation index, see [llms.txt](https://docs.mensajerodigital.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mensajerodigital.app/beneficios/entrega-masiva-de-beneficios.md).
# Entrega masiva de beneficios
## ¿Qué es la entrega masiva?
La **entrega masiva** le permite entregar un beneficio a muchas personas de una sola vez. Usted importa un archivo **CSV** con los datos de las personas o entidades, indica cuántas unidades recibe cada una, y el sistema:
1. Valida que el archivo esté correcto y que haya inventario suficiente.
2. Descuenta las unidades del inventario del producto.
3. Asigna a cada persona sus documentos PDF.
4. Envía un correo a cada persona con sus documentos adjuntos.
A diferencia del flujo por formulario, aquí **no se genera un radicado ni se requiere aprobación**: quien ejecuta la entrega es el responsable del módulo.
{% hint style="info" %}
**Ejemplo.** Su empresa compró 200 boletas de cine para el Día de la Familia y va a entregar 2 a cada uno de sus 100 asociados. En lugar de aprobar 100 solicitudes una por una, importa el listado y el sistema envía los 100 correos con sus 2 boletas cada uno.
{% endhint %}
## Antes de empezar
Para poder ejecutar una entrega masiva necesita, desde la pestaña **Productos**:
* Un **producto activo** que tenga marcada la opción de **documento por unidad**.
* Los **documentos PDF cargados** en el punto de redención desde el que va a entregar.
* **Unidades disponibles** suficientes en el inventario del producto.
{% hint style="warning" %}
La entrega masiva **solo aplica a productos con documento PDF por unidad**, porque lo que se envía en el correo es precisamente ese documento (la boleta, el bono, el vale). Si el producto no tiene esa opción activa, no aparecerá en la lista del asistente.
{% endhint %}
## Cómo acceder
1. Ingrese al módulo **Beneficios** (ruta `/beneficios`).
2. Abra la pestaña **Entregas masivas**.
3. Haga clic en **Nueva entrega**.
La pestaña muestra el histórico de todas las entregas realizadas, con su producto, punto de redención, cantidad de personas, enviados, errores y estado.
## El archivo CSV
### Columnas requeridas
| Columna | Obligatoria | Descripción |
| ----------- | ----------- | ---------------------------------------------------------------- |
| **cedula** | Sí | Número de identificación. Solo dígitos, máximo 15. |
| **nombre** | Sí | Nombre de la persona o entidad. Aparece en el saludo del correo. |
| **correo** | Sí | Dirección a la que se envían los documentos. |
| **celular** | No | Número de contacto. Se guarda con la entidad. |
Los nombres de las columnas **no distinguen mayúsculas ni tildes**, y se aceptan estas variantes:
* `cedula`, `identificacion`, `documento`, `nit`, `cc`
* `nombre`, `nombres`, `nombre completo`
* `correo`, `email`, `correo electronico`, `mail`
* `celular`, `telefono`, `movil`, `numero`
### Ejemplo
```csv
cedula;nombre;celular;correo
1020304050;Ana Maria Restrepo;3001112233;ana.restrepo@ejemplo.com
8090807060;Carlos Andres Gomez;3014445566;carlos.gomez@ejemplo.com
4350607080;Luisa Fernanda Diaz;3125556677;luisa.diaz@ejemplo.com
```
{% hint style="success" %}
Se acepta indistintamente el separador **coma (`,`)** o **punto y coma (`;`)**. Excel en español exporta con punto y coma, así que puede guardar directamente desde Excel como "CSV" sin conversiones.
{% endhint %}
### Validaciones del archivo
Al cargar el archivo, el sistema revisa **fila por fila**:
* Que la cédula esté presente, contenga dígitos y no supere 15 caracteres.
* Que la cédula **no esté repetida** dentro del mismo archivo.
* Que el nombre esté presente.
* Que el correo tenga un **formato válido**.
{% hint style="danger" %}
**Un solo registro inválido bloquea todo el archivo.** El asistente muestra la lista de errores con el número de fila, el campo y el motivo, y no permite continuar hasta que cargue un archivo corregido. Esto evita entregas parciales sin que usted se entere.
Use el botón **Descargar errores** para obtener el listado en CSV, corregir el archivo original y volver a cargarlo.
{% endhint %}
## Paso a paso
{% stepper %}
{% step %}
### Producto y punto de redención
Seleccione el **beneficio** que va a entregar y el **punto de redención** del que se tomarán los documentos PDF.
Al elegirlos, el asistente muestra dos indicadores que conviene revisar antes de seguir:
* **Unidades disponibles del producto**: el saldo del inventario.
* **Documentos PDF libres en el punto**: cuántos archivos sin asignar quedan en ese punto.
{% hint style="info" %}
Estos dos números son **independientes** y pueden diferir. El primero es el contador de inventario del producto; el segundo cuenta los PDF realmente cargados y disponibles. Para poder entregar, **ambos** deben alcanzar.
{% endhint %}
{% endstep %}
{% step %}
### Cargue el archivo
Seleccione o arrastre el archivo CSV. El sistema lo lee, valida los registros y muestra la vista previa.
En la columna **Entidad** verá, para cada persona:
* **Existe**: la cédula ya está registrada como entidad en su empresa.
* **Se creará**: la cédula no existe y se creará automáticamente con el nombre, el correo y el celular del archivo.
{% hint style="info" %}
Las entidades que **ya existen no se modifican**: el sistema respeta la información que usted ya tiene registrada y solo crea las que faltan.
{% endhint %}
{% endstep %}
{% step %}
### Defina la cantidad
Indique cuántas unidades recibe **cada** persona. La cantidad es la misma para todo el lote (entre 1 y 50).
El asistente calcula las **unidades requeridas** (personas × cantidad) y las compara contra los dos inventarios. Si no alcanza, muestra exactamente cuánto falta y no permite continuar:
> **Inventario insuficiente.** Faltan 5 documento(s) PDF en el punto de redención (hay 5).
Para resolverlo puede reducir la cantidad por persona, cargar más documentos PDF en el punto o dividir la entrega en varios lotes.
{% endstep %}
{% step %}
### Ejecute la entrega
Revise el resumen (producto, punto, personas, unidades por persona y total a entregar) y haga clic en **Ejecutar entrega**.
El proceso avanza por bloques y muestra una **barra de progreso** con el número de correos enviados y de errores.
{% hint style="warning" %}
**No cierre la ventana mientras el proceso esté en marcha.** Si la cierra, el lote queda en estado *En proceso* y podrá continuarlo después con el botón **Reanudar** del detalle: las personas que ya recibieron su beneficio no lo reciben dos veces.
{% endhint %}
{% endstep %}
{% endstepper %}
## Qué hace el sistema con cada persona
```mermaid
flowchart TD
A[Fila del archivo] --> B[Reserva los PDF del punto de redencion]
B --> C[Registra la asignacion y descuenta el inventario]
C --> D[Crea la entidad si no existe]
D --> E[Envia el correo con los documentos adjuntos]
E --> F[Enviado]
B -.->|sin documentos disponibles| G[Error de asignacion]
E -.->|el correo no pudo salir| H[Error de envio]
```
Cada persona se procesa de forma **independiente**: si una fila falla, las demás continúan normalmente.
## Estados
### Estado del lote
| Estado | Significado |
| -------------------------- | ------------------------------------------------ |
| **Validado** | El lote se creó pero aún no se ha ejecutado. |
| **En proceso** | La entrega está en curso o quedó a medias. |
| **Completado** | Todas las personas recibieron su beneficio. |
| **Completado con errores** | La entrega terminó, pero algunas filas fallaron. |
| **Cancelado** | El lote se anuló antes de ejecutarse. |
### Estado de cada persona
| Estado | Significado | Qué pasó con el inventario |
| ----------------------- | ------------------------------------------------------------------------------ | -------------------------- |
| **Pendiente** | Aún no se ha procesado. | No se ha descontado. |
| **Enviado** | Recibió su correo con los documentos. | Descontado. |
| **Error de asignación** | No se pudo reservar el beneficio (por ejemplo, se agotaron los PDF del punto). | **No se descontó nada.** |
| **Error de envío** | El beneficio quedó asignado pero el correo no pudo enviarse. | Ya se descontó. |
## Después de la entrega
Desde la pestaña **Entregas masivas**, el botón **Ver detalle** abre el resultado del lote persona por persona, con su estado, el número de intentos, la observación del error y la fecha de envío.
| Acción | Cuándo aparece | Qué hace |
| ----------------------- | ----------------------------------- | ------------------------------------------------------------ |
| **Reanudar** | Cuando quedan personas pendientes. | Continúa el proceso donde se quedó. |
| **Reintentar fallidos** | Cuando hay filas con error. | Vuelve a procesar solo las que fallaron. |
| **Exportar resultados** | Siempre. | Descarga el detalle completo en CSV para archivar o auditar. |
| **Cancelar** | Solo si el lote no se ha ejecutado. | Anula el lote. |
{% hint style="success" %}
**El reintento nunca entrega dos veces.** Si la persona ya tenía su beneficio asignado y lo único que falló fue el correo, el reintento **solo reenvía el correo**: no vuelve a descontar inventario ni a consumir documentos PDF.
{% endhint %}
## El correo que recibe la persona
Cada persona recibe **un solo correo** con el asunto **"Beneficio asignado – \"**, que incluye el logo de su empresa, el nombre del beneficio, la cantidad asignada y **los documentos PDF adjuntos**.
{% hint style="info" %}
El envío de estos correos **no tiene costo adicional** y no consume créditos de su plan.
{% endhint %}
## Límites y consideraciones
| Aspecto | Límite |
| --------------------- | ------------ |
| Registros por archivo | 1.000 |
| Tamaño del archivo | 2 MB |
| Unidades por persona | Entre 1 y 50 |
Los correos se envían de forma espaciada para respetar los límites del servicio de correo, por lo que un lote grande puede tardar varios minutos.
{% hint style="warning" %}
El inventario es compartido con el flujo de solicitudes por formulario. Si mientras usted ejecuta una entrega masiva alguien aprueba solicitudes del mismo producto y punto, los documentos disponibles pueden agotarse a mitad de camino. En ese caso las filas afectadas quedan en **Error de asignación**, sin descontar nada, y podrá reintentarlas después de cargar más documentos.
{% endhint %}
## Preguntas frecuentes
**¿Se genera un radicado por cada persona?**\
No. La entrega masiva no crea radicados ni solicitudes. La trazabilidad queda en el detalle del lote y en la pestaña **Movimientos** del módulo.
**¿Puedo entregar cantidades distintas a cada persona?**\
No en un mismo lote: la cantidad es única para todo el archivo. Si necesita cantidades distintas, cree un lote por cada cantidad.
**¿Qué pasa si una persona aparece dos veces en el archivo?**\
El sistema lo reporta como error de cédula duplicada y no permite ejecutar el lote hasta que corrija el archivo.
**¿Puedo usar un producto sin documentos PDF?**\
No. La entrega masiva solo lista productos con documento por unidad, porque el PDF es lo que se adjunta al correo.
**Cerré el navegador a la mitad, ¿perdí la entrega?**\
No. El lote queda en estado *En proceso*; abra **Ver detalle** y presione **Reanudar** para terminarlo.
**¿Cómo sé a quién se le entregó qué?**\
En el detalle del lote, con opción de exportar a CSV. Los movimientos de inventario también quedan registrados en la pestaña **Movimientos** del módulo de Beneficios.