> ## Documentation Index
> Fetch the complete documentation index at: https://firespark.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Masivo

> Envía clientes por la Storefront API. Spark reenvía el perfil a Masivo solo cuando tú lo confirmas. Billetera y campañas quedan en tu canal.

Los cupones, la lealtad y los perfiles de clientes de Masivo comparten **una conexión de servidor** por comercio y entorno. Pegas una clave de API SERVER de Masivo en el panel, en **Configuración → Integraciones**. Spark guarda esa clave cifrada. Las plantillas de canal nunca la reciben.

## Qué hace la plantilla

Sigue usando los endpoints de clientes de la Storefront API:

* [Registrar un cliente](https://firespark.cloud/docs/es/storefront-api/customers/post.md)
* [Actualizar un cliente](https://firespark.cloud/docs/es/storefront-api/customers/\[id]/patch)
* [Identificar un cliente anónimo](https://firespark.cloud/docs/es/storefront-api/customers/\[id]/identify/anonymous/patch)

No agregues el SDK de Masivo, una clave de API de Masivo ni pantallas de producto de Masivo a una plantilla. La billetera, las campañas y las pantallas de cupones o lealtad propias de Masivo se implementan en tu canal, fuera de la plantilla.

Los canjes siguen siendo pagos de Fire spark. No son una pantalla de billetera de Masivo.

## Cuándo Spark reenvía un perfil

Después de un registro, una identificación o una actualización exitosos, Spark reenvía el perfil solo cuando la conexión de Masivo de ese entorno está **activa** y la opción que corresponde está activada:

1. **Sincronizar clientes registrados** cubre el registro, la identificación o la actualización de un cliente que no es anónimo. Queda activada por defecto cuando la preferencia no existe, y permanece apagada hasta que tú la guardes en la confirmación que aparece justo después de conectar.
2. **Sincronizar clientes anónimos** cubre el registro o la actualización de un cliente anónimo. Queda apagada por defecto.

Conectar no empieza a enviar. Spark te pregunta para confirmar: clientes registrados activados, clientes anónimos apagados y contactos de órdenes anónimas apagados. No enviamos nada hasta que guardes. Si eliges «Ahora no», las tres permanecen apagadas hasta que actives una en Configuración → Integraciones.

Activar una opción no reenvía a los clientes que ya existen. El siguiente registro, identificación o actualización que corresponda envía ese perfil. Si la conexión no está activa, ninguna de estas opciones envía nada.

Un fallo de Masivo no falla la escritura en Storefront. Spark conserva al cliente y registra el error de sincronización en la conexión. Spark reintenta un fallo temporal unas veces. Si esos reintentos se agotan, o Masivo rechaza la clave de API, la conexión requiere atención y Spark envía un correo a los administradores de la cuenta con la razón. Un contacto que Masivo rechaza por inválido o porque ya existe no pausa la conexión. Para volver a enviar, ingresa una clave de API válida o verifica la clave guardada. Desconectar es aparte: quita la conexión y también avisa por correo a los administradores.

## Cuándo Spark envía un contacto

**Sincronizar contactos de órdenes anónimas** permanece apagada hasta que tú la actives. Cuando una orden anónima se marca como cumplida por primera vez, y la conexión está activa, Spark envía un contacto a Masivo con los datos que esa orden ya tiene. Una actualización posterior de esa orden cumplida no vuelve a enviar. Las órdenes de clientes registrados no crean un contacto. Las órdenes cumplidas anteriores no se reenvían.

Si Masivo dice que el contacto no es válido o que ya existe, Spark conserva la orden y registra el error. No actualiza el contacto y no pausa el envío. Si Masivo rechaza la clave de API, o un fallo temporal se repite, la conexión requiere atención hasta que la verifiques o reemplaces la clave.

## Capacidades

Cupones y Lealtad siguen en Marketing. Desactivar una capacidad oculta la llamada a la acción de ese producto y deja la conexión en su lugar, incluida la desconexión.

[Obtener preferencias](https://firespark.cloud/docs/storefront-api/preferences/get.md) devuelve las seis capacidades y ningún secreto:

* `masivo.coupons_enabled`
* `masivo.loyalty_enabled`
* `masivo.sync_registered_customers_enabled`
* `masivo.sync_anonymous_customers_enabled`
* `masivo.sync_anonymous_order_contacts_enabled`
* `masivo.validate_orders_enabled`

Úsalas para saber si Spark va a sincronizar clientes. No son un cliente de Masivo.

## Validar pedidos con Masivo

**Validar pedidos con Masivo** está encendido hasta que lo apagues en Ajustes → Integraciones. Cuando está activo, el entorno tiene una conexión activa con Masivo y el pedido incluye recompensas, [Validar pedido](https://firespark.cloud/docs/es/storefront-api/orders/validate/post.md) le pide a Masivo que previsualice esas recompensas antes de confirmar el pedido.

Al conectar Masivo se crea un pago REDEMPTION de FireSpark para ese entorno y se guarda su id en `masivo_connections.redemption_payment_id` (`20261110210000_masivo_redemption_payment.sql`). El pago nuevo se llama Recompensas si el comercio es es o pt, y Rewards en cualquier otro caso. Volver a conectar reutiliza el pago enlazado, o un pago REDEMPTION de firespark de ese comercio y entorno, y no le cambia el nombre. Spark llama a [`PUT /api/storefront/v1/events/redeem/preview`](https://docs.masivo.ai/api-reference/events/redeem/preview/put) solo con los canjes de ese pago. Una recompensa PRODUCT no es un descuento: la línea del carrito conserva su precio, el total a pagar no baja y Spark la envía en el pedido, no en el producto. El envío son solo líneas FEE cuyo `metadata.fee_based_on` es una base de delivery (`DISTANCE_STRAIGHT`, `DISTANCE_STREET` o `COVERAGE_ZONE_TAG`). Cada rechazo vuelve como `MASIVO_REWARD_NOT_REDEEMABLE`. El cliente ve nuestro texto. El mensaje de Masivo queda en `detail`. Si ese pago falta, fue eliminado o está inactivo, el pedido se rechaza con `MASIVO_REDEMPTION_PAYMENT_REQUIRED`. Si no se puede contactar a Masivo, Spark rechaza el pedido con `MASIVO_UNAVAILABLE` y registra un evento de monitoreo `masivo.failed`. Una clave de API inválida pausa la conexión. Un tiempo de espera no. El preview usa el mismo valor, método de pago y envío que la compra que enviamos a Masivo.

## Enviar eventos de comportamiento

`@fire-spark/analytics-masivo` envía el cuerpo de [Emit event](https://docs.masivo.ai/api-reference/behavior/events/post) de Masivo desde tu canal con una publishable key. Es independiente de la conexión de servidor: no usa ningún secreto. Consulta cómo se mapea cada campo de Fire Spark en [Destinos de analítica](https://firespark.cloud/docs/es/guides/analytics/destinations.md#masivo).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.