## Visión general

**Sync Studio** conecta plataformas externas de e-commerce y marketplaces a tu **catálogo nativo** en
Conversa Labs. Con él defines **fuentes de sincronización** que pueden:

- **Importar (entrada)** — traer los productos de la plataforma externa al catálogo nativo;
- **Publicar (salida)** — enviar productos del catálogo nativo a la plataforma externa;
- **Mantener las dos vías** — combinar importación y publicación en la misma fuente.

Sync Studio es distinto de otras dos funciones cercanas:

- La **Sincronización con el WhatsApp Business Catalog (Meta)** vincula el catálogo nativo al catálogo de
  Meta para enviar productos en WhatsApp — tiene su propio artículo.
- El **ciclo de vida de e-commerce** trata los **eventos de venta** (carrito abandonado, PIX pendiente,
  compra aprobada, reembolso) que se convierten en tarjetas en la conversación — también tiene su
  propio artículo.

Sync Studio se ocupa del **catálogo de productos**: lo que está a la venta, con nombre, precio e
imágenes.

## Requisitos previos

- El módulo **Catálogo y Comercio** habilitado para tu cuenta.
- Permiso de **administrador** para gestionar fuentes de sincronización.
- Una cuenta y las **credenciales de acceso** en la plataforma externa (token, claves de aplicación o
  autorización, según el conector).
- Recomendado: catálogo nativo ya organizado en categorías antes de publicar productos hacia afuera.

## Paso a paso

1. En el área de **Catálogo**, abre **Sync Studio** (fuentes de sincronización) y haz clic para crear
   una **nueva fuente**.
2. Elige el **conector/preset**: fuente Genérica, Shopify, WooCommerce, Magento, PrestaShop, Medusa,
   Mercado Libre, Nuvemshop, Hotmart, Kiwify u OLX.
3. Define la **dirección**: **Entrada** (importar), **Salida** (publicar) o **Dos vías**.
4. **Autentica** la fuente según el conector:
   - **Mercado Libre** — haz clic en **Autorizar**; te lleva a la pantalla de inicio de sesión de la
     plataforma y, al aprobar, te devuelve a la dirección fija `/catalog_oauth/callback`. Los tokens se
     guardan cifrados.
   - **Hotmart / Kiwify** — indica `client_id` y `client_secret` (además de `account_id` en Kiwify).
     El `basic_token` de Hotmart se acepta para fuentes antiguas, pero se deriva automáticamente cuando
     no fue informado. Kiwify recibe las credenciales como formulario y genera el token.
   - **Fuente Genérica, Shopify, WooCommerce, Magento, PrestaShop, Medusa** — elige autenticación
     Bearer, encabezado, **Basic** (usuario y contraseña) o **parámetro de URL**, y configura el mapeo.
   - **Nuvemshop** — pega el token de la tienda y el `store_id`.
5. Usa **Probar conexión** para una fuente Hotmart o Kiwify ya guardada. Para una fuente Genérica, usa la
   **vista previa en vivo** antes de guardar: realiza la misma llamada que la sincronización y muestra la
   respuesta, el formato leído, campos detectados, sugerencias de mapeo y el primer registro mapeado.
6. Guarda y haz clic en **Sincronizar ahora** para ejecutar la primera importación (o **Publicar ahora**
   en una fuente de salida).
7. Sigue el **historial de ejecuciones** paginado y filtrable para ver cada sincronización, con horarios
   en la zona de la cuenta, dirección y resultado (ítems leídos, creados, actualizados, ignorados o con
   error). La lista de fuentes también muestra contadores seguros y el último error sin exponer
   credenciales. Puedes exportar el historial filtrado o las ejecuciones seleccionadas explícitamente
   como CSV; una exportación parcial mantiene visibles los IDs que no se pudieron exportar.

## Configuración y opciones

- **Conector / preset (source_type)** — la plataforma de origen/destino.
- **Dirección** — entrada, salida o dos vías.
- **Credenciales** — guardadas **cifradas**, nunca mostradas de vuelta y nunca registradas en logs.
- **Intervalo de sincronización** — cada cuánto se sincroniza la fuente automáticamente (además de la
  sincronización manual bajo demanda).
- **Estado de la fuente** — una fuente deshabilitada sigue siendo editable, pero no acepta webhooks ni
  ejecuta **Sincronizar ahora**, **Publicar ahora** o trabajos de lectura, publicación y validación de
  Meta que ya estaban en cola. Vuelve a habilitarla solo después de revisar dirección, capacidades y
  credenciales.
- **Paginación** — los catálogos grandes se recorren por páginas automáticamente (Shopify sigue el
  encabezado `Link`, WooCommerce avanza por `página`); las fuentes JSON genéricas pueden configurar el
  estilo de paginación. Si una ejecución alcanza el límite de seguridad de 200 páginas y todavía hay
  una página siguiente, termina como **parcial/truncada** y conserva el cursor; la ejecución siguiente
  continúa desde ese punto. El cursor solo se limpia cuando la lectura llega realmente al final.
- **Formato y raíz de productos** — la fuente Genérica detecta JSON, NDJSON, XML, CSV o TSV por la
  respuesta; puedes elegir el formato manualmente. XML usa una raíz **XPath** (por ejemplo,
  `//products/product`); los otros formatos usan ruta con puntos.
- **Mapeo sugerido** — la vista previa propone, sin guardar por sí sola, coincidencias en portugués,
  inglés y español con confianza. Revísalas antes de aplicar. Además de nombre e ID puedes mapear precio,
  precio comparativo, moneda, SKU, stock, marca y URL externa; `items.0.price` elige la primera posición.
- **Webhook de la fuente** — cada fuente tiene su propia dirección de webhook
  (`/webhooks/catalog/:account_id/:source_id`). Donde la plataforma lo permite, Conversa Labs lo registra con un clic
  mediante **Registrar webhook** (Nuvemshop, Kiwify); en otras, pegas la dirección en el panel de la
  propia plataforma (Hotmart).
- **Secreto de sincronización de entrada** — usado por los clientes de la API de sincronización masiva y
  enmascarado en la lista. **Rotar secreto de entrada** invalida el anterior inmediatamente, registra la
  operación cuando la auditoría nativa está habilitada y revela el nuevo valor una sola vez; actualiza
  todos los remitentes.
- **Secreto del webhook de la plataforma** — valor proporcionado por la plataforma para verificar los
  eventos de comercio. Es write-only y nunca se devuelve. Para sustituirlo, pega el nuevo valor al
  editar la fuente y actualiza también el panel externo; Conversa Labs no inventa ni rota ese valor en la
  plataforma.
- **Fuente Genérica bidireccional** — configura el mapa de eventos y las rutas de campos en la propia
  pantalla. La entrada exige `X-Webhook-Signature: t=…,v1=…`, rechaza una fuente sin secreto, limita la
  ventana de replay y deduplica el ID de entrega. Una fuente solo de salida rechaza entregas entrantes.
  Para salida, informa un destino HTTP(S) sin credenciales, parámetros de consulta ni fragmentos; la
  autenticación usa el secreto HMAC compartido. Los eventos tienen historial con búsqueda, reintentos
  automáticos y reenvío manual individual o masivo confirmado.
  Una entrega que encuentra la fuente deshabilitada, eliminada, modificada o sin secreto falla antes de
  realizar cualquier solicitud externa y registra el motivo en ese historial.
- **Producto, variación y artículos del webhook genérico** — las rutas de producto y variación parten
  de la raíz del evento. Indica primero la ruta de la lista de artículos y luego mapea los campos
  relativos a cada artículo. Los campos vacíos nunca se infieren. Al mapearlos, los valores se conservan
  en el pedido del CRM y solo se envían a webhooks de cuenta que activaron **detalles de comercio**.
- **Protección contra duplicados y bucle** — cada ítem importado guarda el identificador de origen
  (`external_id` / `retailer_id`) y la fuente. En sincronizaciones posteriores esto actualiza el mismo
  producto en lugar de recrearlo e impide devolver a la fuente un cambio que vino de ella.

## Importar ventas históricas de Hotmart o Kiwify

En una fuente Hotmart o Kiwify guardada, abre **Gestión → Importar ventas**. Selecciona ambas fechas
dentro de la ventana del proveedor: hasta 31 días naturales en Hotmart o 90 días en Kiwify. Puedes
filtrar por producto y por los valores documentados de estado/pago del proveedor; Kiwify también admite
el filtro de afiliado. Sin un filtro de estado de Hotmart, su API devuelve solo `APPROVED` y `COMPLETE`;
selecciona explícitamente otro estado documentado cuando lo necesites. Haz clic en
**Previsualizar ventas**: esta llamada es de solo lectura, usa la paginación oficial de cada proveedor y
no escribe contactos, organizaciones, eventos ni pedidos. Revisa la acción local de cada fila y
selecciona explícitamente entre 1 y 500 IDs antes de ponerla en cola. Omitir la selección nunca significa
“importar todo”.

La importación vincula únicamente contactos existentes de la cuenta mediante campos exactos de ese
endpoint de ventas. El historial de Hotmart proporciona el correo del comprador (nombre/ucode no se usan
como identidad); Kiwify `GET /sales` proporciona correo, móvil y CPF. Una organización solo se vincula por
la organización principal actual del contacto que coincidió exactamente. Nunca elige entre coincidencias
conflictivas ni inventa un campo CNPJ que la lista de Kiwify no documenta. Un comprador sin contacto
existente, o un estado sin equivalencia local fiel, se muestra como no importable; la importación histórica
nunca crea personas ni empresas. Los eventos de ciclo de
vida y Pedidos del CRM importados conservan las fechas de pedido/aprobación del proveedor y llevan la
marca histórica. Esto suprime mensajes al cliente, fan-out de automatizaciones, crédito de comisiones y
ranking, engagement, CAPI, efectos de stock y webhooks salientes de la cuenta, pero sí llena el registro
nativo de pedidos.

Usa el **Historial de ejecuciones** para revisar cantidades seleccionadas, creadas, actualizadas,
reparadas, omitidas y fallidas, los IDs exactos omitidos/con fallo y si el recorrido global del proveedor
fue truncado. Una solicitud idéntica reutiliza la ejecución activa y el proceso se bloquea por
cuenta/fuente. Una ejecución completa o parcial ofrece **Deshacer importación** solo mientras cada pedido
y evento creado localmente siga intacto y sin vínculos; la reversión es atómica, nunca llama a
Hotmart/Kiwify y nunca elimina contactos u organizaciones.

## Casos de uso

- Importar una tienda **Shopify** o **WooCommerce** al catálogo nativo y atender desde ahí.
- Publicar productos nativos en un **marketplace** (cuando el conector admite salida).
- Mantener **Mercado Libre** o **Nuvemshop** conectados para alimentar el catálogo nativo.
- Importar **infoproductos** de **Hotmart** o **Kiwify** y, además, recibir los eventos de venta en la
  conversación.

## Capacidades por plataforma

Cada conector declara lo que admite; la interfaz habilita la dirección y los botones según esa capacidad.

| Plataforma | Importar (entrada) | Webhook de eventos | Ventas históricas | Autenticación |
|---|---|---|---|---|
| Fuente Genérica (JSON, NDJSON, XML, CSV o TSV) | Sí | Sí (firma HMAC configurable) | No | Bearer, encabezado, Basic o parámetro de URL |
| Shopify | Sí | — | No | Token / encabezado |
| WooCommerce | Sí | — | No | Token / encabezado |
| Magento, PrestaShop, Medusa | Sí | — | No | Token / encabezado |
| Mercado Libre | Sí | — | No | OAuth (Autorizar) |
| Nuvemshop | Sí | Sí (auto-registro) | No | Token de la tienda (pegar) |
| Hotmart | Sí (productos) | Sí (en el panel de Hotmart) | Sí (vista previa y selección gobernadas) | Client credentials |
| Kiwify | Sí (productos) | Sí (auto-registro) | Sí (vista previa y selección gobernadas, hasta 90 días) | Client credentials |
| OLX | No (sin API de lectura) | — | No | Solo socios |

- La **publicación (salida)** hacia el **WhatsApp Business Catalog** tiene su propio artículo; los
  conectores de tienda/marketplace anteriores se centran en la **importación** en esta versión. **No toda
  plataforma es bidireccional.**
- Los **webhooks de eventos** anteriores entregan **eventos de venta** (no productos) y alimentan el
  **ciclo de vida de e-commerce** — consulta ese artículo.
- **OLX** no ofrece API pública de lectura: la integración existe solo para socios aprobados, que
  publican un feed de anuncios (autoupload). Por eso el conector OLX viene deshabilitado en Sync Studio
  hasta que se conceda el acceso de socio.

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

- Las **credenciales se quedan en el servidor**: están cifradas, nunca vuelven a la pantalla y no
  aparecen en logs. Los conectores OAuth (Mercado Libre) **renuevan el token por sí solos** mediante la
  autorización concedida.
- **Respeta la paginación y los límites** de la plataforma de origen; los catálogos muy grandes se leen
  en varias páginas y pueden tardar más en la primera importación.
- **La descripción llega como texto plano**: tiendas como Nuvemshop/Tiendanube y Shopify guardan
  la descripción del producto en HTML. Al importar, la plataforma la **convierte a texto**,
  conservando párrafos, saltos de línea y listas — las etiquetas nunca llegan ni a ti ni al
  cliente, ya que la descripción viaja como texto en el mensaje enviado en la conversación y en el
  catálogo de Meta. Una descripción que escribas tú se guarda tal como la escribiste.
- **Valores en unidades mayores**: los precios siguen en unidades mayores (`4,97` = R$4,97). La
  plataforma **no** divide por 100.
- Ejecuta la **primera importación fuera del horario pico** para revisar el resultado con calma.

## Solución de problemas

- **La autorización de Mercado Libre falló**: confirma que la aplicación de la plataforma usa la
  dirección de retorno fija `/catalog_oauth/callback` y rehaz el flujo de **Autorizar** (el `state` de la
  autorización caduca en pocos minutos).
- **Los productos no se importaron**: usa **Probar conexión** para ver la respuesta real; revisa el
  token/las claves, el `store_id`/`account_id` cuando aplique y si el conector elegido es el correcto.
  La vista previa genérica muestra el motivo de la plataforma con los secretos ocultos.
- **El webhook no se dispara**: confirma que la fuente fue **registrada** (Nuvemshop/Kiwify) o que la
  dirección se pegó en el panel de la plataforma (Hotmart), y que el **secreto del webhook** está
  completo.
- **Ítems duplicados**: la duplicación se evita por el identificador de origen (`retailer_id` /
  `external_id`); si aparecen duplicados, comprueba si los ítems llegaron con identificadores distintos a
  los que ya existían.

## Ver también

- [Catálogo nativo: productos, categorías, imágenes y precios](/hc/ajuda/articles/catalog-commerce-catalogo-nativo-es)
- [Sincronización y WhatsApp Business Catalog](/hc/ajuda/articles/catalog-commerce-sync-whatsapp-business-catalog-es)
- [Ciclo de vida de e-commerce: webhooks Kiwify/Hotmart/Nuvemshop/Shopify](/hc/ajuda/articles/catalog-commerce-commerce-lifecycle-es)