## Visión general

El **ciclo de vida de e-commerce** conecta plataformas externas — **Kiwify, Hotmart, Nuvemshop y
Shopify** — para que los eventos de venta lleguen dentro de la atención. Cuando algo ocurre en la
plataforma externa (carrito abandonado, PIX/boleto generado, compra aprobada, rechazada o reembolsada),
ConversaLabs recibe el **webhook**, normaliza el evento y muestra una **tarjeta en la conversación** del
cliente, con los datos de pago cuando están disponibles.

Con esto, recuperas ventas sin cambiar de herramienta: el equipo ve la etapa de la compra en la propia
conversación y puede activar **Follow-ups** automáticos para reconquistar a quien no finalizó.

## Requisitos previos

- El módulo de **Catálogo y Comercio** habilitado y permiso para configurar fuentes de comercio.
- Acceso a la plataforma externa (Kiwify, Hotmart, Nuvemshop o Shopify) para configurar el webhook.
- Para la recuperación automática: el módulo de **Follow-ups** configurado con secuencias por evento.

## Paso a paso

1. En el área de **Catálogo y Comercio**, crea una **fuente de comercio** para la plataforma deseada.
2. Copia la **URL de webhook completa** generada para esa fuente. Incluye la cuenta y la fuente; no
   elimines ningún segmento. Configura también el **secreto de verificación**. En Kiwify, el registro
   automático puede generar y guardar el token; en Hotmart, indica el Hottok de la aplicación.
3. Pega la URL en el panel de la plataforma externa (o usa el **registro automático** cuando esté
   disponible, por ejemplo en Kiwify y Nuvemshop).
4. Realiza una venta de prueba (o un carrito de prueba) para confirmar que el evento llega.
5. Observa la **tarjeta del evento** aparecer en la conversación del cliente, con ítems, importes y el
   enlace/datos de pago según la etapa.
6. Configura **Follow-ups** activados por evento (por ejemplo, "carrito abandonado") para recuperar la
   venta automáticamente.

## Configuración y opciones

### El pago y el envío de la tarjeta son estados diferentes

En el panel **Comercio** de la conversación, el título describe el evento comercial registrado y
**Envío de la tarjeta** describe solo el intento de envío de esa tarjeta. **Pago confirmado** junto
con **No intentado** no significa que el pago esté pendiente: la confirmación financiera está
registrada, pero esa tarjeta de Comercio todavía no tiene un intento de envío registrado. Otros
mensajes de pago pueden estar ya en la conversación.

Usa **Ver tarjeta** para abrir el mensaje vinculado cuando exista, o **Abrir conversación** para
consultar el historial. **Enviar confirmación** o **Reenviar confirmación** abre un diálogo antes
del envío; puedes cancelar. Esta acción no crea un cobro ni cambia la confirmación financiera.
Reenviar una tarjeta existente requiere tu confirmación explícita. Sin conversación vinculada,
el servidor busca una conversación existente del contacto; este panel no abre una nueva.

Una tarjeta registrada en la conversación no demuestra que el cliente la recibió: revisa también
el estado del mensaje y del canal. Los fallos, envíos rechazados y respuestas no confirmadas no se
presentan como éxito. Los mensajes y boletos enviados antes del pago permanecen en el historial;
su presencia no convierte un pago confirmado en pendiente. No uses la imagen de un comprobante
para sustituir el estado financiero registrado por la pasarela o un operador autorizado.

- **Fuente de comercio**: una por plataforma, con su propia URL de webhook y secreto de verificación.
- **Registro automático del webhook**: disponible en algunas plataformas (ej.: Kiwify y Nuvemshop); en
  las demás, la configuración es manual en el panel de la propia plataforma.
- **Tarjeta del evento**: muestra la etapa de la compra y, cuando la plataforma lo expone, datos de
  PIX/boleto y el enlace de checkout.
- **Variables de comercio**: los datos del último evento quedan disponibles para usar en mensajes de
  Follow-up (enlace de pago, importe, código PIX/boleto, etc.).

### Elegir qué eventos recibir

Al editar la fuente en **Catálogo → Fuentes de sincronización → editar la fuente**, la sección **Eventos**
lista los eventos que envía esa plataforma y te permite mapear **cada uno** a una etapa del ciclo de vida
— o marcarlo como **Apagado (ignorar)** para descartarlo por completo.

Todo evento habilitado recorre el resto de la plataforma: **automatizaciones, flows, webhooks, Follow-up
y el CRM**. El mapeo es lo que decide **en qué etapa** entra.

Un botón destacado de **Recuperación de carrito abandonado** enciende y apaga el evento de carrito de la
plataforma — es el que alimenta la cadencia de recuperación en Follow-up (disparador
`commerce.cart_abandoned`).

Disponible para:

| Fuente | Eventos que mapeas |
|---|---|
| **Hotmart** | eventos de compra, carrito, suscripción y área de miembros |
| **Kiwify** | sus 10 disparadores reales: `compra_aprovada`, `pix_gerado`, `boleto_gerado`, `compra_recusada`, `compra_reembolsada`, `chargeback`, `carrinho_abandonado`, `subscription_renewed`, `subscription_late`, `subscription_canceled` |
| **Nuvemshop** | los valores de `payment_status` del pedido: `paid`, `authorized`, `pending`, `refunded`, `partially_refunded`, `abandoned` — el webhook de Nuvemshop trae solo el ID, así que la etapa viene del estado de pago del pedido |
| **Fuentes genéricas** | los nombres de evento documentados por tu sistema. Tú defines explícitamente el campo del evento, el ID, las rutas de comprador/producto/ítems y la etapa canónica; no se infiere nada por el nombre de una plataforma |

Las fuentes administradas sin un contrato verificado de ciclo de venta, como **Mercado Libre y OLX**,
no muestran un selector de eventos. Las fuentes atendidas por el conector genérico — incluida una
configuración propia de Shopify/API — muestran la configuración del webhook genérico firmado y reciben
solo los eventos que mapees explícitamente.

Los valores por defecto ya son sensatos: solo cambia el mapeo si quieres una etapa distinta o si quieres
ignorar un evento.

### Quién aparece como autor de la tarjeta de recuperación

Cuando un **asistente de IA o bot activo** envía la tarjeta de recuperación, el mensaje queda registrado
con el propio bot como autor. Debe estar activo en la **bandeja de entrada de la conversación**, en la
**misma cuenta**, y el evento usado para la recuperación debe pertenecer al **mismo contacto de la conversación**.

Cuando un **agente** envía la tarjeta, el mensaje queda registrado con el propio agente como autor.

## Casos de uso

- **Carrito abandonado**: dispara una secuencia de Follow-up recordando al cliente que concluya.
- **PIX/boleto pendiente**: reenvía el código de pago y hace seguimiento hasta confirmar.
- **Compra aprobada**: confirma con el cliente y libera el siguiente paso de la atención.
- **Reembolso/rechazo**: alerta al equipo para tratar el caso en la propia conversación.

## Consejos, límites y buenas prácticas

- **Lo que expone cada plataforma varía**: algunas envían el **código PIX y la línea del boleto** en el
  evento (recuperación completa dentro de la conversación); otras solo proporcionan el **enlace de
  checkout** — en esos casos, la tarjeta muestra el enlace para que el cliente concluya.
- **Los importes y formatos difieren por plataforma**: ConversaLabs normaliza cada evento; no necesitas
  preocuparte por la conversión — la tarjeta ya muestra el importe correcto.
- **Secreto de verificación**: mantenlo configurado para que solo se acepten eventos legítimos de la
  plataforma. Los webhooks de Hotmart, Kiwify, Nuvemshop y los genéricos se rechazan si no hay un secreto
  configurado. Un emisor genérico también debe enviar la firma con marca de tiempo y un ID de entrega
  estable por evento.
- Combínalo con Follow-ups para automatizar la recuperación en lugar de depender de la acción manual.

Un mensaje registrado o una tarjeta visible en la conversación no confirma la entrega por el canal
del cliente. Antes de informar que el cliente lo recibió, comprueba el **estado de entrega del mensaje**
y la **conexión del canal**.

## Solución de problemas

- **Un reenvío no tuvo respuesta confirmada**: el servidor puede haber aceptado la tarjeta. El panel
  bloquea otro intento y ofrece **Revisar resultado registrado**, que solo consulta registros.
  Si todavía no se puede verificar el resultado, revise la conversación; esta consulta no reenvía.
  La protección permanece al cerrar y reabrir la confirmación. Con el almacenamiento de sesión
  disponible, también sobrevive a recargar en la misma pestaña; si el navegador lo deniega, dura
  mientras el panel está montado. No prueba entrega ni protege entre pestañas diferentes.
- **El estado del cobro cambió**: un evento antiguo de confirmación no se reenvía si el cobro nativo
  actual está reembolsado, cancelado o en otro estado incompatible. Revise **Pagos**.
- **PIX/boleto desaparecieron después del pago**: los instrumentos anteriores permanecen en el
  historial, pero no se ofrecen para cobros liquidados, reembolsados, cancelados o archivados. Un
  reembolso parcial no crea una deuda nueva. Las cuotas realmente abiertas conservan sus acciones.
- **Una confirmación no puede enviarse fuera de la ventana de WhatsApp**: utiliza una plantilla
  aprobada de confirmación sin botón de pago configurado. No se reutiliza una plantilla de cobro para
  un cobro liquidado. Comprueba que su contenido y botones estáticos aprobados sean de confirmación.

- **El evento no aparece**: verifica que la URL completa de webhook se pegó correctamente en la
  plataforma y que el secreto de verificación está configurado y coincide.
- **No veo PIX/boleto en la tarjeta**: no todas las plataformas exponen esos datos; cuando no los hay,
  la tarjeta trae el enlace de checkout.
- **Eventos duplicados**: las entregas genéricas con el mismo ID se procesan una sola vez. Si algo se ve
  extraño, confirma que el emisor reutiliza ese ID en los reintentos y que solo hay un webhook
  configurado para la misma fuente.
- **El bot no envía la tarjeta de recuperación**: comprueba que esté activo en la bandeja de entrada
  de la conversación, en la misma cuenta, y que el evento pertenezca al mismo contacto de la conversación.
- **La tarjeta aparece, pero el cliente no la recibió**: comprueba el estado de entrega del mensaje
  y la conexión del canal antes de confirmar la recepción al cliente.

## Ver también

- [Visión general de Catálogo y Comercio](/hc/ajuda/articles/catalog-commerce-overview-es)
- [Enviar producto y recibir pedidos en la conversación](/hc/ajuda/articles/catalog-commerce-enviar-produto-pedido-na-conversa-es)
- [Catálogo nativo: productos, categorías, imágenes y precios](/hc/ajuda/articles/catalog-commerce-catalogo-nativo-es)