## Visión general

La **Recuperación de ventas** es la capa que garantiza que un evento de comercio **siempre se convierta
en una acción visible**. Antes, la tarjeta de recuperación podía morir en silencio: si el cliente no
tenía una conversación abierta, o si el mensaje caía fuera de la ventana de WhatsApp, no pasaba nada y
nadie se enteraba.

Ahora todo evento de ciclo de vida — proveniente de Kiwify, Hotmart, Nuvemshop o de la pasarela nativa
(Asaas / Mercado Pago) — pasa por tres garantías:

1. Un **resolvedor de conversación** decide a dónde va la tarjeta, con una **política** que tú eliges.
2. Una **guarda de ventana de envío** verifica si el canal acepta el mensaje en ese momento.
3. Un **resultado de entrega** queda registrado en **todos** los caminos de salida: `enviado`,
   `omitido` o `fallido`, siempre con un **motivo** legible.

El resultado práctico: abres la página **Recuperación de ventas** y ves cuántas oportunidades se
alcanzaron, cuántas no y **exactamente por qué** — en lugar de descubrir semanas después que una
cadencia entera nunca salió.

### Cuándo se dispara cada etapa

| Etapa | Se dispara cuando | ¿Accionable? |
|---|---|---|
| **Carrito abandonado** | el cliente armó el carrito/checkout y no lo concluyó | Sí |
| **Pago pendiente** | se generó un PIX o boleto y aún no se pagó | Sí |
| **Pago rechazado** | la tarjeta fue rechazada por el emisor o por el antifraude | Sí |
| **Vencido** | la fecha de vencimiento pasó sin pago | Sí |
| **Pedido creado** | el pedido quedó registrado en la plataforma y sigue pendiente | No (no liquida) |
| **Pago confirmado** | el pago fue aprobado | No (liquidación) |
| **Reembolsado** | el importe fue devuelto al cliente | No |
| **Chargeback** | el cliente disputó el cobro ante el emisor | No |
| **Suscripción atrasada** | la renovación de la suscripción falló o está atrasada | No |
| **Suscripción cancelada** | la suscripción fue finalizada | No |

Las cuatro etapas **accionables** son las que entran en el cálculo de la tasa de recuperación. Los
reembolsos y los chargebacks nunca cuentan como recuperación — son lo contrario.

`due_soon` sigue siendo un valor almacenado válido por compatibilidad, pero ningún conector o pasarela
nativa actual lo produce. Por eso no se ofrece en la recuperación automática ni en el selector de Follow-up.

## Requisitos previos

- La funcionalidad **Recuperación de ventas** (`commerce_recovery`) **habilitada en la cuenta**. Viene
  **desactivada por defecto**; solicita la activación a quien administra la instalación.
- Perfil de **administrador** o de **agente** en la cuenta. Ambos pueden abrir la página de recuperación,
  cambiar políticas y reenviar tarjetas — aquí no existe un permiso separado por módulo.
- Al menos una **fuente de comercio** conectada (Kiwify, Hotmart, Nuvemshop) o una **pasarela nativa**
  configurada (Asaas / Mercado Pago), para que los eventos lleguen.
- Para enviar fuera de la ventana de WhatsApp: una **plantilla aprobada** en la bandeja correspondiente.

Con la funcionalidad desactivada, la nueva página, el panel lateral y las métricas quedan ocultos. La
entrega en sí (política de conversación, resultado registrado) sigue funcionando en segundo plano — es
infraestructura de comportamiento preservado.

## Paso a paso

1. Abre **Recuperación de ventas** en el menú del módulo de comercio.
2. Revisa el **embudo accionable por etapa**: usa las mismas cuatro etapas que las métricas de intentos
   y recuperaciones; las liquidaciones, reembolsos y cancelaciones no entran en este embudo.
3. Mira el bloque de **entrega**: `enviado`, `omitido`, `fallido` y `no intentado`.
4. Abre la lista de **motivos** — viene ordenada del más frecuente al menos frecuente. Esa es tu lista
   de corrección, en orden de impacto.
5. Haz clic en un evento para ver la tarjeta, la conversación de destino y el historial de entrega.
6. Si la tarjeta no salió por un motivo ya corregido (canal reconectado, plantilla aprobada), usa
   **Reenviar**. Si necesitas saltarte la guarda de duplicidad, marca **forzar**.
7. Ajusta la **política de conversación** en la acción de automatización/macro para que el próximo
   evento del mismo tipo no caiga en el mismo motivo.

## Configuración y opciones

### La política de conversación (la elección más importante)

Cuando la tarjeta debe entregarse, la plataforma necesita saber **en qué conversación** escribir. Tienes
tres opciones:

| Política | Qué hace | Cuándo usarla |
|---|---|---|
| **Usar una conversación existente** *(por defecto)* | Entrega en la conversación más reciente del contacto. **Nunca crea** una. Si no hay ninguna, la tarjeta se omite con el motivo `no_conversation`. | El valor por defecto seguro — es exactamente el comportamiento actual. Nada cambia para quien ya lo usa. |
| **Crear una si es necesario** | Usa la conversación existente cuando la hay; **crea una nueva** cuando no la hay. | Cuando quieres alcance máximo y aceptas que una conversación nueva sea visible para el cliente. |
| **Solo esta conversación** | Entrega estrictamente en la conversación donde se disparó la regla. Nunca busca otra, nunca crea. | Cuando la tarjeta solo tiene sentido en el contexto de esa atención específica. |

> **Por qué "crear una si es necesario" es opt-in:** crear una conversación es una acción **visible para
> el cliente** y para la cola del equipo. Aparece en la bandeja, cuenta en los informes y puede generar
> notificaciones. Por eso Conversa Labs nunca lo hace por su cuenta — tienes que elegirlo.

### La ventana de 24 horas de WhatsApp (sin medias verdades)

WhatsApp solo permite mensajes libres dentro de **24 horas** desde el último mensaje del cliente. Fuera
de esa ventana:

- **Sin plantilla aprobada** → la tarjeta se **omite**, con el motivo `whatsapp_window_closed`. **No se
  entrega**. Conversa Labs prefiere registrar el motivo antes que encolar un mensaje que WhatsApp va a
  rechazar.
- **Con plantilla aprobada** → la entrega **degrada al mensaje único de la plantilla**. Alcanzas al
  contacto, pero **no** con la tarjeta rica completa: solo con lo que la plantilla aprobada permite.

**WhatsApp Web no tiene ventana.** Las bandejas de WhatsApp Web entregan normalmente en cualquier
momento — la restricción de 24 h pertenece a la API oficial de WhatsApp Business, no a la plataforma.

**Excepción: par híbrido.** Si tienes un par híbrido con Cloud como principal y enrutamiento fuera de la
ventana hacia WhatsApp Web, el envío sale completo como mensaje de sesión de Web — no se convierte en
plantilla ni se omite. En ese caso no esperes ver `whatsapp_window_closed`.

### Otros canales

La tarjeta siempre lleva el **enlace de pago en el cuerpo del mensaje**, nunca solo como adjunto. Esto
es deliberado: **LINE, TikTok y X (Twitter)** descartan o rechazan los adjuntos. Si el enlace viajara
solo en el adjunto, el cliente recibiría un mensaje sin lo único que importa.

### Entrega de las tarjetas y la fila de "no intentados"

El panel muestra el **desglose de la entrega** — enviadas, omitidas, con error y **no intentadas**. El
grupo "no intentadas" es el que nunca tuvo tarjeta: ninguna regla actuó sobre ese evento. Dejó de ser
un número suelto: ahora puedes **filtrar la línea de tiempo por él** y **encolar los pendientes** en
lotes limitados, del más antiguo al más nuevo, hasta 50 por vez.

La acción responde **aceptado/en cola**, no con un total de entregas. El procesamiento ocurre en segundo
plano y los resultados reales (`enviado`, `omitido` o `fallido`) aparecen después en la cronología.
Nunca abre una conversación nueva: un evento sin destino queda registrado como omitido con su motivo.
El historial importado o adoptado desde una pasarela siempre queda fuera de esta fila.

> **Por qué "Recuperaciones intentadas" puede marcar 0 con la lista llena.** La cuenta solo considera
> los eventos accionables **cuya tarjeta se registró como enviada**. Si no se envió ninguna, el denominador es
> cero — la página no está rota, te está diciendo que todavía nadie fue contactado.

### Recuperación automática por etapa (desactivada por defecto)

En **Mensajes → Recuperación automática por etapa**, activa solo las etapas en vivo que quieres que
Conversa Labs encole automáticamente. Todos los interruptores empiezan **desactivados**. El evento inmediato
encola la tarjeta y una verificación cada cinco minutos repara una entrega perdida a la cola. Ambos
caminos vuelven a comprobar el interruptor, reutilizan una conversación existente, respetan la ventana
de 24 horas de WhatsApp y aplazan el envío cuando el límite seguro de la conexión está lleno.

Los cobros importados o adoptados son historial: siguen visibles para auditoría e informes con la
etiqueta **Histórico — envío bloqueado**, pero quedan fuera de cualquier envío al cliente. La
recuperación automática, el drenaje manual, la verificación, Follow-up, el reenvío forzado, las
automatizaciones y Maestro no pueden atravesar esta protección.

### El orden de los mensajes de la tarjeta

La tarjeta es una secuencia: resumen → botón de pago → PIX copiar y pegar → código QR → boleto →
línea digitable. Ese orden ahora está **garantizado en la entrega** — antes cada mensaje salía por su
cuenta y podían llegar desordenados (el código PIX crudo llegando antes del mensaje que pide copiarlo).

En **Mensajes → Entrega** defines la **pausa entre los mensajes de la tarjeta**. Déjala en blanco para
usar el valor del canal: en WhatsApp conectado por celular (WazMeow) es 1 segundo, para espaciar la
ráfaga y no parecer un envío automático; en los demás canales no hay pausa.

### Abrir la conversación y reenviar

Cada fila activa tiene **Abrir conversación** (va directo al chat de ese cliente) y **Reenviar tarjeta**. El
reenvío apunta a la conversación por su identificador público — nunca puede caer en el cliente
equivocado. Si el evento todavía no tiene conversación, el diálogo lo avisa antes de confirmar que se
abrirá una con el cliente. Las filas históricas no muestran el reenvío y la API también lo rechaza,
incluso con **forzar**.

## Casos de uso

- **Un PIX pendiente que se enfrió**: el cliente generó el PIX ayer y desapareció. La tarjeta reenvía el
  código en la conversación existente, sin crear ruido nuevo.
- **Una ola de rechazos de tarjeta**: un emisor tumbó varias transacciones. Filtras por
  `payment_declined`, ves que todas se omitieron con `channel_unavailable`, reconectas el canal y
  reenvías en lote.
- **Un carrito abandonado de alguien que nunca te habló**: contacto nuevo, sin conversación. Con la
  política "crear una si es necesario", la tarjeta abre la conversación e inicia la atención.
- **Auditoría de cadencia**: la lista de motivos muestra que el 60% de los envíos murió en
  `whatsapp_window_closed` — la señal clara de que esa cadencia necesita una plantilla aprobada.

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

### Los resultados de entrega y qué hacer con cada uno

Todo evento termina en uno de estos estados: **enviado**, **omitido**, **fallido** — o **no intentado**,
cuando ninguna regla actuó sobre él.

| Motivo | Qué significa | Qué hacer |
|---|---|---|
| `no_contact` | El evento llegó sin un contacto identificable (la plataforma de origen no envió teléfono/correo utilizable). | Revisa el mapeo de identificación en la fuente de comercio. Sin contacto no hay a quién enviar. |
| `no_conversation` | El contacto existe, pero no hay conversación para recibir la tarjeta y la política es "usar una conversación existente". | Si quieres alcanzar esos casos, cambia la política a **crear una si es necesario**. |
| `no_channel_inbox` | No existe una bandeja del canal que pidió la acción. | Conecta la bandeja de ese canal, o apunta la acción a una bandeja que exista. |
| `whatsapp_window_closed` | Fuera de la ventana de 24 h y sin plantilla aprobada. | Adjunta una **plantilla aprobada** a la acción. O mueve la cadencia dentro de la ventana. |
| `throttled` | Se alcanzó el límite de envío del canal en ese momento. | Espacia la cadencia. Las ráfagas grandes en WhatsApp también aumentan el riesgo de bloqueo. |
| `channel_unavailable` | El canal está desconectado, expirado o no disponible. | Reconecta la bandeja y reenvía los eventos afectados. |
| `sequence_not_published` | La secuencia de Follow-up sigue en borrador. | Publica la secuencia. Un borrador nunca envía — es intencional. |
| `already_sent` | La guarda de duplicidad lo bloqueó: ese evento ya tuvo una tarjeta registrada como enviada. | Nada, en la mayoría de los casos. Si realmente debes enviar otra vez, usa **Reenviar** con **forzar**. |

### Integración con sistemas externos

Cada resultado de entrega — enviado, omitido o fallido — también se emite como el evento de webhook de
cuenta `commerce_card_delivery`, con el motivo canónico incluido. Así es como un sistema externo (n8n,
un CRM) reacciona sin sondear: abrir una tarea cuando el motivo sea `no_conversation`, o intentar otro
canal cuando sea `whatsapp_window_closed`. Actívalo en **Configuración → Integraciones → Webhooks**.

### La guarda de duplicidad y el reenvío explícito

Un mismo evento crea y despacha localmente la tarjeta **una sola vez**. Si una automatización y una
macro intentan enviar la misma tarjeta, la segunda se omite con `already_sent` — esa es la guarda local
de duplicidad. La entrega final del proveedor todavía debe comprobarse en el estado del mensaje o de
la conversación del canal.

El **reenvío** siempre es explícito y humano: abres el evento y haces clic en **Reenviar**. Conserva el
registro del primer envío (fecha y mensaje originales) y solo incrementa el contador de reenvíos — el
historial nunca se borra. Para atravesar la guarda a propósito, marca **forzar**.

### Cómo leer la tasa de recuperación (con honestidad)

La tasa de recuperación es la **proporción de intentos accionables registrados como enviados y
atribuidos a una liquidación posterior del mismo contacto y del mismo pedido**.

Con precisión:

- **Denominador**: eventos accionables (carrito abandonado, pendiente, rechazado, vencido)
  **cuya tarjeta se registró como enviada**.
- **Numerador**: liquidaciones posteriores con el **mismo contacto, origen e identificador externo del
  pedido/cobro**. Pagar otro pedido no recupera el primero.
- Una liquidación cuenta **una sola vez**. Si el mismo pedido recibió varias tarjetas accionables, se
  atribuye de forma determinista al último intento registrado como enviado antes de liquidar.
  **Pedido creado nunca liquida ingresos**: solo `payment_confirmed` entra en el numerador.
- Los eventos cuya tarjeta nunca se registró como enviada quedan fuera de **ambos lados**. El estado
  `enviado` confirma la creación y el despacho local; todavía no es un recibo final del proveedor.
- Cuando **nada** se intentó en el período, la tasa aparece como **—**, no como 0%. Cero por ciento
  significaría "lo intentamos y fallamos"; la raya significa "no hubo intento".

> **Esto es correlación, no causalidad.** La métrica dice "el cliente pagó después de que lo
> contactamos", no "el cliente pagó **porque** lo contactamos". Parte de esas personas habría pagado de
> todos modos. Usa el número para comparar cadencias entre sí y seguir una tendencia — no lo presentes
> como ingresos atribuidos a una campaña.

Los **ingresos recuperados usan el valor y la moneda de la liquidación**, no el valor mostrado en la
tarjeta. Los totales se muestran separados por moneda: BRL y USD nunca se suman ni se rotulan como si
todo fuera BRL. Los valores permanecen en la **unidad principal** de cada moneda, sin conversión
oculta. Si el origen no informó la moneda, la interfaz deja explícita esa ausencia.

## Solución de problemas

- **"No intentado" en muchos eventos**: ninguna regla está actuando sobre esa etapa. Crea una
  automatización o una secuencia de Follow-up para la etapa en cuestión.
- **Todo omitido con `no_conversation`**: tu base son contactos sin conversación abierta y la política es
  la predeterminada. Cambia a **crear una si es necesario** — recordando que la conversación nueva es
  visible para el cliente.
- **Todo omitido con `whatsapp_window_closed`**: la cadencia se ejecuta fuera de la ventana de 24 h.
  Aprueba una plantilla y adjúntala a la acción, o adelanta el disparo.
- **Tarjeta entregada, pero "pobre"**: estás fuera de la ventana **con** plantilla. Es el comportamiento
  correcto — WhatsApp solo acepta la plantilla aprobada en esa situación.
- **`channel_unavailable` intermitente**: la bandeja se está cayendo. Verifica la conexión del canal
  antes de reenviar en lote, si no los reenvíos fallarán por el mismo motivo.
- **El cliente lo recibió dos veces**: verifica si hay una automatización **y** una secuencia de
  Follow-up cubriendo la misma etapa, o si alguien usó **forzar** en el reenvío.
- **La tasa aparece como "—"**: ninguna tarjeta de recuperación se registró como enviada en el período
  filtrado. Amplía el período o revisa la lista de motivos.
- **La página no aparece**: la funcionalidad `commerce_recovery` está desactivada en la cuenta, o tu
  usuario no es administrador ni agente en ella.

## Ver también

- [Ciclo de vida de e-commerce: webhooks Kiwify/Hotmart/Nuvemshop/Shopify](/hc/ajuda/articles/catalog-commerce-commerce-lifecycle-es)
- [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)