Introducción
Esta guía proporciona los detalles necesarios para integrar datos con Midway utilizando la integración SFTP (mediante archivos CSV). Este método permite una transferencia diaria y eficiente de información clave, particularmente útil para integrar datos de tiendas físicas y/o e-commerces sin integración directa.
Conexión típica
A continuación, se presenta un diagrama que ilustra una conexión típica entre los datos de la compañía y la plataforma Midway:
Entidades en color verde son requeridas.
Entidades en color celeste son opcionales.
Midway procesará los datos según la frecuencia definida por el cliente en la integración. Este procesamiento asegura que la información esté siempre actualizada y disponible para su análisis y uso en campañas de marketing.
Consideraciones para la conexión
Autenticación: Se realiza mediante usuario y contraseña.
Proceso de subida de archivos: Los archivos CSV deben subirse de manera automatizada y periódica al servidor SFTP.
Servidor SFTP: Midway proporcionará un servidor SFTP específico para cada cliente. (costos asociados)
Credenciales del SFTP
Midway proporcionará los siguientes datos específicos para cada cliente para la conexión al servidor SFTP:
Host (El puerto utilizado para la conexión es el predeterminado de SFTP (22)).
Usuario y contraseña.
Estructura del SFTP
El SFTP de Midway está estructurado en cuatro carpetas principales, cada una con una función específica en el flujo de datos:
Pending: Aquí se colocan los archivos que están en espera de ser procesados. Estos archivos serán procesados en el próximo ciclo de procesamiento.
Processing: Esta carpeta contiene los archivos que están siendo procesados en ese momento. Dependiendo del resultado del procesamiento, los archivos se moverán a las carpetas Processed o Failed.
Processed: Contiene los archivos que han sido procesados exitosamente.
Failed: Aquí se encuentran los archivos que no pudieron ser procesados correctamente. Es importante revisar estos archivos para identificar y corregir los errores antes de volver a subirlos.
Requisitos de archivos CSV
Los datos deben ser proporcionados en archivos CSV, con un archivo por cada entidad (Audience; Sales; Content; Categories; Carts).
Codificación y Formato de Archivos:
Codificación: UTF-8
Separador de campos: ; (punto y coma)
Nombres de los archivos CSV
Cada archivo CSV debe seguir una convención de nombres específica para asegurar la correcta identificación y procesamiento automático. Los nombres deben estar formados por el tipo de entidad y la fecha y hora de los datos. La estructura es la siguiente:
Entidad | Formato del nombre |
Audience | audience_#fecha_#hora.csv |
Sales | sales_#fecha_#hora.csv |
Content | content_#fecha_#hora.csv |
Categories | categories_#fecha_#hora.csv |
Carts | carts_#fecha_#hora.csv |
Donde:
#fecha es la fecha de los datos en formato YYYYMMDD.
#hora es la hora de los datos en formato HHMMSS.
Ejemplo:
Audience: audience_20241228_132144.csv
Sales: sales_20241228_132144.csv
Content: content_20241228_132144.csv
Categories: categories_20241228_132144.csv
Carts: carts_20241228_132144.csv
Configuración de archivos
Midway maneja los datos divididos en las siguientes entidades: Audience; Orders; Products; Categories; Carts. Es necesario enviar un archivo para cada entidad. Los nombres de las columnas deben coincidir exactamente con los solicitados en esta documentación.
Ejemplos de archivos y campos disponibles
Cada entidad debe incluir campos obligatorios y opcionales, con la posibilidad de agregar campos adicionales específicos de la marca, conocidos como "campos dinámicos". A continuación se presentan ejemplos y campos necesarios:
Audience (Clientes)
Integración de datos completos de su audiencia que serían sus clientes, incluyendo el identificador de email y datos adicionales como geográficos, de género y de cumpleaños.
Archivo de ejemplo
Se envían los clientes actualizados y creados en las últimas 24 a 48 horas. En caso de enviar información que ya envió previamente, los datos se combinaran con los ya existentes.
Campos / Cabeceras de la entidad audience
Campo | Tipo | Descripción | Ejemplo | Obligatorio |
| Si | |||
firstname |
| Nombre | Christian | No |
lastname |
| Apellido | Vitale | No |
birthdate |
| Fecha de nacimiento | 01/09/1996 | No |
gender |
| Género (“male”, “female”, ““) | male | No |
phone |
| Telefono | +5491173682446 | No |
city |
| Ciudad | CABA | No |
province |
| Provincia | Buenos Aires | No |
country |
| Departamento | Argentina | No |
postal_code |
| Código postal | 1419 | No |
address |
| Código Postal | Av. Gral. Mosconi 3424 | No |
created_at |
| Fecha de creación del registro | 2024-03-13 12:29:04 | No |
updated_at |
| Fecha de actualización del registro | 2024-03-13 12:29:04 | No |
👉 Información adicional: Esta entidad permite agregar campos dinamicos. ¿Qué son? Son campos que no son nativos en Midway, como tipo de membresía, tienda de registro o deporte favorito. Para parametrizarlos en Midway, puedes seguir las Instrucciones.
El nombre del campo para un campo dinámico se envía en formato custom.{nombre_atributo}. Ese atributo se va a crear en Midway con el nombre que se encuentre en la cabecera. Por ejemplo, si deseas crear el atributo para Clientes "membresia_gold", el campo sería custom.membresia_gold.
Sales (ventas)
Integración de datos de ventas, incluyendo identificador del comprador, datos de la venta y productos comprados. Cada línea representa un producto distinto de la misma venta.
Archivo de ejemplo
Se envían las ventas actualizadas y creadas en las últimas 24 a 48 horas. En caso de enviar información que ya envió previamente, los datos se combinaran con los ya existentes.
Campos / Cabeceras de la entidad sales
Campo | Tipo | Descripción | Ejemplo | Obligatorio |
sale_id |
| ID de la venta | 1 | Si |
channel |
| Canal de venta | Offline | Si |
status |
| Género ("pending", "invoiced", "cancelled", "refunded" or "credit_note") | invoiced | Si |
store |
| Tienda | Tienda 1 | No |
seller |
| Vendedor | Vendedor 1 | No |
customer_id |
| ID del cliente | 1 | No |
customer_email |
| Si | ||
customer_firstname |
| Nombre del cliente | Cristian | No |
customer_lastname |
| Apellido del cliente | Vitale | No |
payment_name |
| Nombre del medio de pago | Tarjeta de crédito | No |
payment_value |
| Valor del pago | 1000 | No |
payment_bin |
| Primero 6 dígitos de la tarjeta | 451769 | No |
payment_bank |
| Banco emisor (en caso de pagar con tarjeta) | Banco Galicia | No |
shipping_price |
| Costo de envío | 100 | No |
shipping_country |
| País del envío | Argentina | No |
shipping_city |
| Ciudad del envío | CABA | No |
shipping_address |
| Dirección del envío | Av. Gral. Mosconi 3424 | No |
shipping_method |
| Método de envío | Delivery | No |
shipping_state |
| Provincia/Estado del envío | Buenos Aires |
|
subtotal |
| Total sin descuentos aplicados | 1000 | No |
total |
| Total con descuentos aplicados | 1000 | Si |
tax |
| Impuestos | 0 | No |
created_at |
| Fecha de creación de la venta | 2024-03-13 12:29:04 | Si |
updated_at |
| Fecha de actualización de la venta | 2024-03-13 12:29:04 | No |
product_id |
| ID del producto | 1 | Si |
sku |
| SKU del producto | SKU001 | Si |
name |
| Nombre del producto | Remera | Si |
price |
| Precio de lista del producto | 1000 | Si |
price_sale |
| Precio con descuentos del producto | 1000 | Si |
quantity |
| Cantidad de productos agregados del mismo | 1 | Si |
category_ids |
| ID de categorías del producto | 1|2 | No |
category_names |
| Nombre de categorías del producto | Indumentaria|Remeras | No |
Para cargar una orden, el cliente tiene que hacerlo de la siguiente manera:
En la primera fila debe estar la información general de la venta y es la que será tomada en cuenta en el guardado, luego en las próximas lineas puede repetirse o no, en caso de no repetirla se deberá dejar vacío el campo, lo importante a destacar es que solo se tomara esta información de la primer fila.
Campos: sale_id, channel, store, seller, customer_id, customer_email, customer_firstname, customer_lastname, payment_name, payment_value, payment_bin, payment_bank, shipping_price, shipping_country, shipping_city, shipping_address, shipping_method, shipping_state, subtotal, total, tax, created_at, updated_at.
En la siguientes filas debe estar la información de cada producto de la venta, y es muy importante repetir el valor del sale_id para saber todos los productos que pertenecen a esa venta.
Campos: sale_id, product_id, sku, name, price, price_sale, quantity, category_ids, category_names.
Referencias importantes:
Enviar el email para identificar al cliente.
Si esta subiendo información de tiendas físicas:
Los SKUs deben coincidir con los del E-commerce.
No enviar ventas del E-commerce.
Content (productos)
Integración de datos de productos. Cada línea representa un producto distinto.
Archivo de ejemplo
Es posible enviar el catálogo de productos de manera parcial o completa. Si se reenvían datos previamente enviados, estos se combinarán automáticamente con los ya existentes.
La configuración de la integración incluye un atributo que define si se enviará solo el catálogo parcial (con las modificaciones realizadas en las últimas horas) o el catálogo completo. Por defecto, esta configuración estará desactivada, lo que significa que esperamos recibir el catálogo completo.
Cuando se envía el catálogo completo, Midway desactiva automáticamente los productos que ya no figuran en el archivo pero que estaban registrados previamente. Esto garantiza que solo los productos activos y notificados permanezcan visibles. Además, si el catálogo completo incluye productos sin stock, estos también se desactivarán correctamente.
En caso de enviar únicamente los productos que sufrieron modificaciones, Midway actualizará, creará o activará los productos según los parámetros proporcionados, desactivando aquellos que correspondan según la notificación recibida.
Campos / Cabeceras de la entidad content
Campo | Tipo | Descripción | Ejemplo | Obligatorio |
item_id |
| ID del producto | 1 | Si |
sku |
| SKU del producto | SKU001 | Si |
name |
| Nombre del producto | Remera | Si |
description |
| Descripción del producto | Remera deportiva | No |
image |
| Link a la imagen del producto | imagen1.jpg | Si |
link |
| Si | ||
tags |
| Tags/Colecciones a las que pertenece el producto | verano|nuevo | No |
category_ids |
| ID de las categorías del producto | 1|5 | No |
category_names |
| Nombre de las categorías del producto | Calzado|Zapatillas | No |
price |
| Precio de lista | 100 | Si |
price_sale |
| Precio con descuento | 80 | Si |
brand_id |
| ID de marca | 1 | No |
brand_name |
| Nombre de la marca | Nike | No |
made_in |
| Origen del producto | Argentina | No |
price_details |
| Información extra de precios (detalle-monto) | IVA-1399 | No |
parent_id |
| ID del producto padre | 1111 | Si |
parent_attributes_name |
| Nombre de los atributos del producto padre | género|material | No |
parent_attributes_value |
| Valor de los atributos del producto padre | niños|sintético | No |
sku_attributes_name |
| Nombre de los atributos del producto | Color|Talle | No |
made_in |
| Origen del producto | Buenos Aires, Argentina | No |
price_details |
| Detalle de los precios promocionales del producto | nombre-valor-porcentaje(opcional) | No |
sku_attributes_value |
| Valor de los atributos del producto | Amarillo|45 | No |
is_active |
| ¿Está activo? | 1 | No |
dimensions |
| Dimensiones del producto | length|width|height | No |
created_at |
| Fecha de creación | 2023-03-10 18:04:03 | No |
updated_at |
| Fecha de actualización | 2023-03-10 18:04:03 | No |
Categorías (categories)
Integración de datos de categorías. Cada línea representa una categoría distinta.
Archivo de ejemplo
Es posible enviar el listado completo de categorías o únicamente las que fueron creadas o actualizadas en las últimas 24 horas. Si se reenvían datos previamente enviados, estos se combinarán automáticamente con la información existente.
Campos / Cabeceras de la entidad categories
Campo | Tipo | Descripción | Ejemplo | Obligatorio |
category_id |
| ID de la categoría | 1 | Si |
name |
| Nombre de la categoría | Indumentaria | Si |
url |
| Link a la categoría | Si |
Carritos abandonados (carts)
Integración de datos de carritos abandonados. Cada línea representa un carrito abandonado distinto.
¿Como funciona?
Se envían los carritos abandonados que fueron creados en las últimas horas. Si se reenvían datos previamente enviados, estos se combinarán automáticamente con la información existente para mantener la consistencia de los datos.
Archivo de ejemplo
Incluye los detalles de los carritos abandonados que se desean notificar, siguiendo el formato especificado.
Campos / Cabeceras de la entidad carts
Campo | Tipo | Descripción | Ejemplo | Obligatorio |
cart_id |
| ID del carrito | 1 | Si |
url_recovery |
| URL para recuperar el carrito |
| No |
customer_email |
| Email del usuario | Si | |
customer_firstname |
| Nombre del usuario | John | No |
customer_lastname |
| Apellido del usuario | Sánchez | No |
product_id |
| ID del producto | 1234 | Si |
sku |
| SKU del producto | SKU1234 | Si |
name |
| Nombre del producto | Remera | No |
price |
| Precio de lista del producto | 1200 | Si |
price_sale |
| Precio con descuento del producto | 1043.40 | Si |
quantity |
| Cantidad de productos agregados del mismo | 1 | Si |
image |
| Imagen del producto | imagen1.jpg | Si |
link |
| Link al producto | Si | |
created_at |
| Fecha de creación | 2023-03-10 18:04:03 | No |
updated_at |
| Fecha de actualización | 2023-03-10 18:04:03 | No |
Para cargar un carrito abandonado, el cliente tiene que hacerlo de la siguiente manera:
En la primera fila debe estar la información general del carrito abandonado y es la que será tomada en cuenta en el guardado, luego en las próximas lineas puede repetirse o no, en caso de no repetirla se deberá dejar vacío el campo, lo importante a destacar es que solo se tomara esta información de la primer fila.
Campos requeridos: cart_id, url_recovery, customer_email, customer_firstname, customer_lastname, created_at, updated_at.
En las siguientes filas debe estar la información de cada producto de la venta, y es muy importante repetir el valor del sale_id para saber todos los productos que pertenecen a esa venta.
Campos requeridos: cart_id, product_id, sku, name, price, price_sale, quantity, image, link.
Buenas prácticas
Para garantizar una integración eficiente y precisa, se recomienda seguir estas buenas prácticas:
Entidad audience
Evitar enviar clientes sin identificar. Cada cliente debe incluir información clave que permita su correcta asociación y gestión.
Entidad sales
No enviar ventas sin datos del cliente. Toda venta debe incluir información completa del cliente asociado para asegurar un procesamiento adecuado.
Si estás subiendo información de tiendas físicas:
Asegúrate de que los SKUs coincidan con los del E-commerce.
No incluyas ventas provenientes del E-commerce para evitar duplicados.
Entidad content
La URL debe coincidir exactamente con la página del producto en el E-commerce. Esto asegura que los usuarios puedan acceder al producto correcto al interactuar con las campañas o la personalización web.
Proceso de sincronización de datos
Midway sincroniza los datos según la frecuencia configurada por el cliente en la integración. Durante este proceso, se procesan únicamente los archivos que contienen información válida, asegurando la actualización continua de los datos en la plataforma.
Este enfoque garantiza que las empresas siempre cuenten con información actualizada y precisa, optimizando sus estrategias de marketing y mejorando la segmentación de audiencias.
Proceso histórico de datos
Para integrar datos históricos de hasta dos años, se realizará una carga de estos datos en la carpeta pending del SFTP. Los archivos requeridos deberán incluir "historical" en sus nombres para diferenciarlos de los datos regulares.
Archivos necesarios
Master de Clientes: Contiene todos los clientes creados en los últimos dos años.
Archivos de Ventas: Deben estar separados mes a mes, especificando el mes en el nombre del archivo y comenzando desde hace dos años.
Ejemplo de nombres de archivos
Clientes: audience_historical.csv
Ventas:
sales_enero2023_historical.csv
sales_febrero2023_historical.csv
sales_marzo2023_historical.csv
El procesamiento se realizará durante el sprint pactado en la “Reunión Técnica”. Una vez finalizada, será necesaria una validación de los datos por parte del cliente. En caso de una demora en la entrega de los datos, se modificará el deadline del proyecto.
Validación de datos
Audience
En Midway, ir a Audiencia > Perfiles. Puede haber más clientes que en su base de datos debido a la creación de clientes a partir de ventas.
Sales
En Midway, ir a Audiencia > Perfiles > Seleccionar un contacto y visualizar la información histórica de ventas para ese perfil.
Content
En Midway, ir a Contenido > Productos.
Carts
En Midway, ir a Audiencia > Perfiles > Seleccionar un contacto y visualizar la información de carrito abandonado.
Contingencias
Procedimiento en caso de fallos
En caso de no procesar los datos, se enviará una notificación por email. Se recomienda validar los siguientes puntos:
Funcionamiento del proceso de subida de archivos: Asegúrese de que el proceso que sube los archivos al SFTP esté operativo y enviando los archivos correctamente.
Envío de todas las entidades: Confirme que se ha enviado un archivo para cada entidad requerida.
Archivos no vacíos: Verifique que los archivos contengan datos y no estén vacíos.
Datos de ventas recientes: Asegúrese de que se hayan registrado ventas en las últimas 24 horas y que estos datos estén presentes en el archivo de ventas con el createtime correcto.
Reporte de Sincronización: Puedes obtener más datos de la falla accediendo a Integraciones > Buscar la integración SFTP > Detalles.
Acciones correctivas
En caso de que se identifique y corrija algún problema, puede volver a subir los archivos a la carpeta pending en el SFTP. Los archivos serán procesados de forma automática en el siguiente ciclo de procesamiento.
Contacto con soporte
Si la falla persiste, contactar a [email protected].
Recomendaciones para el Inicio del Proyecto
Preparación de archivos
Es crucial comenzar generando archivos con columnas que coincidan exactamente con las especificadas en la documentación. Para resolver cualquier duda, consulta los archivos de ejemplo.
Desarrollo inicial
Se recomienda iniciar el desarrollo con la entidad más sencilla: Audience. Esto permitirá establecer una base sólida antes de avanzar con entidades más complejas.
Documentación de procesos
Es fundamental documentar cada paso del proceso de integración. Esto garantizará una comprensión clara del flujo de datos y servirá como referencia para futuras necesidades.
Monitoreo y optimización
Implementa un sistema de monitoreo desde el inicio para verificar que la integración se realice correctamente. Además, optimiza el proceso según los resultados obtenidos, asegurando una integración más eficiente a lo largo del tiempo.
Timeline del proyecto de integración
Para asegurar una integración exitosa de los datos con la plataforma Midway, se ha definido un timeline detallado con fechas aproximadas que guiará el proceso desde el inicio hasta la finalización.
Kickoff
Esta es la fase inicial del proyecto donde se establece el alcance y los objetivos de la integración.
Día 0.
Reunión Técnica
Reunión entre los equipos técnicos de Midway y el cliente para revisar los requisitos, definir las tecnología de integración y resolver cualquier duda técnica.
+3 días desde el Kickoff.
Primer Entregable
Entrega inicial de los archivos CSV configurados según los requisitos establecidos durante la reunión técnica.
+20 días desde la Reunión técnica.
Entrega de Datos Históricos
Provisión de datos históricos de hasta 2 años de antigüedad por parte del cliente. Estos datos se utilizarán para poblar la base de datos de Midway.
+10 días desde el primer entregable.
Procesamiento de Datos Históricos
Midway procesa y valida los datos históricos entregados por el cliente, asegurándose de que todos los datos se han integrado correctamente. Paralelamente comienza el proceso de información diaria.
Duración de tarea: 14 días desde la entrega de datos históricos
Finalización del Setup
Validación final y ajustes necesarios. Esta fase incluye la revisión de la integración completa y la confirmación de que todos los datos se procesaron correctamente en Midway.