Sincronizar el catálogo con tiendas y marketplaces (Sync Studio)

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.

• 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
• Sincronización y WhatsApp Business Catalog
• Ciclo de vida de e-commerce: webhooks Kiwify/Hotmart/Nuvemshop/Shopify