Ir al contenido principal
Integración de Tiendas Físicas con Archivos CSV
Actualizado hace más de una semana

Introducción

Esta guía proporciona detalles sobre la integración de tiendas físicas con WoowUp utilizando archivos CSV. Esto permite una experiencia de CRM omnicanal, integrando datos de manera diaria y eficiente.


Conexión Típica

A continuación, se presenta un diagrama que ilustra una conexión típica entre la marca y la plataforma WoowUp:

WoowUp procesará los datos una vez por día en un horario preestablecido o pactado con el cliente. Este procesamiento diario 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

  • Protocolo SFTP con clave SSH: El protocolo utilizado para la transferencia de archivos será SFTP (Secure File Transfer Protocol), donde la autenticación se realizará mediante una clave SSH en lugar de un usuario y contraseña.

  • Clave SSH: Se deberá generar una clave SSH que debe ser utilizada para la autenticación en el servidor SFTP. El cliente deberá configurar el proceso de subida de archivos utilizando esta clave.

  • Proceso de subida de archivos: Los archivos CSV deben subirse de manera automatizada y periódica al servidor SFTP.

  • Servidor SFTP Proporcionado por WoowUp: WoowUp ofrecerá un servidor SFTP donde se depositarán los archivos CSV.

  • IP Fija: La IP desde la cual se subirán los archivos debe ser fija y whitelisteada por WoowUp.

Credenciales del SFTP

WoowUp 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).

De su parte, deberán proporcionar los siguientes datos:

  • Clave SSH pública

  • IP fija del servidor


Pasos para generar una clave SSH

Para autenticarte en el servidor SFTP mediante una clave SSH, sigue estos pasos:

  1. Generar el par de claves SSH
    En tu terminal, ejecuta el siguiente comando para crear un par de claves SSH (privada y pública):

    ssh-keygen -t rsa -b 4096 -C "[email protected]"

    Esto generará dos archivos:

    • Clave privada: Esta se guarda localmente y no debe compartirse.

    • Clave pública: Esta es la que deberás proporcionar a WoowUp.

  2. Elegir el nombre y ubicación de la clave
    Se te pedirá que elijas un nombre para los archivos generados. Presiona Enter para aceptar la ubicación predeterminada (~/.ssh/id_rsa), o proporciona una ruta personalizada si prefieres guardar la clave en otro lugar.

  3. Enviar la clave pública a WoowUp
    La clave pública es el archivo con la extensión .pub (por ejemplo, id_rsa.pub). Envía este archivo a WoowUp para que pueda ser registrado en el servidor SFTP.

  4. Configurar la conexión SFTP
    Una vez que WoowUp haya registrado tu clave pública, puedes configurar tu cliente SFTP para que use la autenticación por clave SSH. Asegúrate de especificar la ruta a tu clave privada en la configuración del cliente SFTP.

  5. Verificar la conexión
    Para probar la conexión, puedes ejecutar el siguiente comando en tu terminal, reemplazando host y puerto con los detalles proporcionados por WoowUp:

    sftp -i ~/.ssh/id_rsa usuario@host -P puerto

Estructura del SFTP

El SFTP de WoowUp está estructurado en cinco carpetas principales, cada una con una función específica en el flujo de datos:

  1. 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.

  2. 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.

  3. Processed: Contiene los archivos que han sido procesados exitosamente.

  4. 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.

  5. Historical: Aquí deberán ser depositados los archivos históricos a procesar durante la etapa del onboarding.


Requisitos de Archivos CSV

Los datos deben ser proporcionados en archivos CSV, con un archivo por cada entidad (Tiendas, Clientes y Ventas).

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, el nombre de la marca y la fecha de los datos. La estructura es la siguiente:

  • Tiendas: tiendas_#marca_#fecha.csv

  • Clientes: clientes_#marca_#fecha.csv

  • Ventas: ventas_#marca_#fecha.csv

Donde:

  • #marca es el nombre de tu marca.

  • #fecha es la fecha de los datos en formato YYYYMMDD.

Ejemplo:
tiendas_tumarca_20240625.csv

clientes_tumarca_20240625.csv

ventas_tumarca_20240625.csv


Configuración de Archivos

WoowUp maneja los datos divididos en las siguientes entidades: Tiendas, Clientes y Ventas. 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 "atributos extendidos". A continuación se presentan ejemplos y campos necesarios:

Tiendas

Integración de tiendas donde los clientes pueden realizar compras, excluyendo depósitos de mercadería o la tienda eCommerce. Se pueden incluir canales web como MercadoLibre o tiendas de bancos.

Archivo de Ejemplo

Campos / Cabeceras de la entidad Tiendas

Campo

Tipo

Descripción

Ejemplo

Obligatorio

name

String

Identificador único de la tienda

A101

display_name

String

Nombre de la tienda

Sucursal Palermo

branch_zone_code

String

Código de la zona

13

No

branch_zone_name

String

Nombre de la zona

Buenos Aires

No

En esta entidad no es posible incluir atributos extendidos


Clientes

Integración de datos completos de los clientes, incluyendo identificadores (document y/o email) y datos adicionales como geográficos, de género y de cumpleaños.

Archivo de Ejemplo

Se envían únicamente los clientes actualizados y creados en las últimas 24 horas.

❗Debes enviar al menos un identificador del cliente (document y/o email)

Campos / Cabeceras de la entidad Clientes

Campo

Tipo

Descripción

Ejemplo

Obligatorio

document

String

Documento o cédula

30300300

Si

email

String

Email

Si

first_name

String

Nombre

Christian

No

last_name

String

Apellido

Vitale

No

telephone

String

Telefono

1173682446

No

birthdate

Date

Fecha de Nacimiento (sin hora)

1992-03-31

No

gender

Enum

Género ["M", "F", ""]

M

No

street

String

Calle

ohm 2220

No

city

String

Ciudad

CABA

No

state

String

Estado

CABA

No

department

String

Departamento

Villa Urquiza

No

country

String

País

Argentina

No

postcode

String

Código Postal

1431

No

points

Integer

Puntos

100

No

mailing_enabled

Enum

Habilitación para enviar mail ["enabled", "disabled"]

disabled

No

sms_enabled

Enum

Habilitación para enviar sms ["enabled", "disabled"]

disabled

No

👉 Esta entidad permite agregar Atributos Extendidos. ¿Qué son? Son campos que no son nativos en WoowUp, como tipo de membresía, tienda de registro o deporte favorito. Para parametrizarlos en WoowUp, puedes seguir las Instrucciones.

El nombre del campo para un atributo extendido se envía en formato custom_attributes.{nombre_atributo}. Ese atributo se va a crear en WoowUp 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_attributes.membresia_gold.


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.

Archivo de Ejemplo

Se envían las ventas creadas en las últimas 24 horas.

❗No enviar las ventas del ecommerce

❗Los campos Total, Gross, Discount, Tax y Cost deben ser los globales de toda la factura. Para un mismo invoice_number deben repetirse línea a línea (ver ejemplo)

❗Enviar al menos un identificador de cliente (document y/o email)

Campos / Cabeceras de la entidad Ventas

Campo

Tipo

Descripción

Ejemplo

Obligatorio

document

String

Documento o cédula del cliente

36872489

Si

email

String

Email del cliente

Si

invoice_number

String

Número de la Factura (ID)

FAC0230321

Si

createtime

String

Fecha y Hora de la Venta

2020-01-23 16:32:05

Si

channel

Enum

Canal de venta ["web", "in-store"]

in-store

Si

branch_name

String

Código de la tienda donde se realizó la venta. Se debe utilizar el campo 'name' del archivo de Tiendas.

A101

Si

points

Integer

Puntos otorgados de la venta

100

No

shipping

Float

Costo de Envío

500

No

gross

Float

Subtotal (Sin impuestos, sin envíos y sin descuentos)

9000

Si

tax

Float

Impuestos de la Factura

1400

No

discount

Float

Descuento de la factura

2000

No

total

Float

Total de la Factura

9400

Si

payment_type

Enum

Medio de pago ['credit', 'debit', 'mercadopago', 'todopago', 'cash', 'other']

debit

Si

payment_brand

String

Marca de la Tarjeta

Visa

No

payment_bank

String

Banco emisor de la tarjeta

Banco Galicia

No

payment_installments

Integer

Cantidad de cuotas

6

No

payment_total

Float

Total por medio de pago

9400

No

seller_name

String

Nombre del Vendedor

Gil Gunderson

No

seller_email

String

Email del vendedor

No

seller_external_id

String

Id externo del vendedor

10

No

SKU

String

Código del producto (productReferenceCode de Vtex)

AB123324

Si

product_name

String

Nombre del producto

Celular Moto Z

Si

brand

String

Marca del producto

Motorola

No

quantity

Integer

Cantidad de unidades

2

Si

unit_price

Float

Precio unitario del producto (Sin impuestos y descuentos)

1000

Si

variations

String

Características por las que se puede agrupar productos. Por ejemplo: color, talle, temporada (Formato llave valor, separados por pipes "|")

Color: Blanco | Talle: XXXL

No

👉 Esta entidad permite agregar Atributos Extendidos. ¿Qué son? Son campos que no son nativos en WoowUp, como la promoción utilizada o si usó un cupón de descuento. Para parametrizarlos en WoowUp, puedes seguir las Instrucciones.

El nombre del campo para un atributo extendido se envía en formato custom_attributes.{nombre_atributo}. Ese atributo se va a crear en WoowUp con el nombre que se encuentre en la cabecera. Por ejemplo, si deseas crear el atributo para Ventas "cupon_descuento", el campo sería custom_attributes.cupon_descuento.


Pagos (Opcional)

La entidad de pagos es opcional y resulta útil cuando se requiere integrar un gran número de ventas con más de un medio de pago. Permite asignar a un número de factura específico múltiples medios de pago.

Los archivos deben ser nombrados pagos_#marca_#fecha.csv.

Archivo de Ejemplo

Se envían los pagos de las ventas creadas en las últimas 24 horas.

Campos / Cabeceras de la entidad Ventas

Campo

Tipo

Descripción

Ejemplo

Obligatorio

invoice_number

String

Numero de factura tal cual esta en el archivo Orders

FAC0123213

Si

branch_name

String

Tienda donde realizo la venta

A101

Si

type

Enum

Tipo de pago, valores posibles ['credit', 'debit', 'cash', 'mercadopago', 'other']

Credit

Si

brand

String

Marca de la tarjeta

VISA

No

bank

String

Banco emisor de la Tarjeta

Banco Galicia

No

total

Float

Total pagado por este medio de pago

1299

Si

installments

Integer

Cantidad de Cuotas

2

No

card_first_digits

String

Primeros 6 números de la tarjeta

12321

No


Buenas Prácticas

Para asegurar una integración eficiente y precisa, se deben seguir las siguientes buenas prácticas:

Entidad Tiendas

  • No enviar almacenes o tiendas donde el cliente no hará compras.

Entidad Clientes

  • Enviar al menos un identificador del cliente.

  • No enviar emails genéricos (ej. [email protected]). En caso de ser un dato obligatorio, enviar [email protected].

  • No enviar documentos genéricos.

  • No enviar clientes sin identificar.

Entidad Ventas

  • No enviar ventas sin datos del cliente.

  • Los SKUs deben coincidir con los del eCommerce.

  • La combinación invoice_number + branch_name debe ser única.

  • No enviar ventas del eCommerce.

  • Devoluciones o notas de crédito deben tener valores numéricos negativos.

  • Los campos Gross, Discount, Tax, Total deben repetirse línea a línea para un mismo número de factura.


Proceso Diario de Datos

WoowUp realiza un procesamiento de los datos de forma periódica en el horario especificado por el cliente, o a medianoche si no se especifica un horario. Durante este proceso, se procesan los archivos que deben contener datos de las últimas 24 horas. Este enfoque garantiza que los datos de las tiendas físicas, clientes y ventas se mantengan continuamente actualizados en la plataforma WoowUp, permitiendo a las empresas disponer de la información más reciente para sus estrategias de marketing y 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 Historical del SFTP. Los archivos requeridos deberán incluir "historical" en sus nombres para diferenciarlos de los datos regulares.

Archivos Necesarios

  1. Master de Clientes: Contiene todos los clientes creados en los últimos dos años.

  2. Master de Tiendas: Incluye todas las tiendas de los últimos dos años, incluso aquellas que ya no están activas.

  3. 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: clientes_tumarca_historical.csv

  • Tiendas: tiendas_tumarca_historical.csv

  • Ventas:

    • ventas_tumarca_enero2023_historical.csv

    • ventas_tumarca_febrero2023_historical.csv

    • ventas_tumarca_marzo2023_historical.csv

El procesamiento se realizará durante el sprint pactado en la “Reunión Técnica de Tiendas Físicas”. 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

Cantidad de Clientes

En WoowUp, ir a Segmentos y, sin aplicar ningún filtro, hacer clic en el símbolo de “#”. Puede haber más clientes que en su base de datos debido a la creación de clientes a partir de ventas.

Cantidad de Ventas y Totales

Para validar la cantidad de ventas en WoowUp, ir a Analytics > Listado de Facturas. Establecer las fechas y tiendas a analizar, asegurándose de quitar la tienda de eCommerce.

Validación de Tiendas

Acceder a la configuración de la cuenta, sección Tiendas en el menú lateral, para visualizar y modificar las tiendas procesadas.

En caso de que encuentres una falta de datos, consulta este artículo: LINK


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:

  1. 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.

  2. Credenciales y habilitación de la IP: Verifique que las credenciales de acceso al SFTP sean correctas y que la IP fija con la que intentan acceder sea la habilitada por WoowUp.

  3. Envío de todas las entidades: Confirme que se ha enviado un archivo para cada entidad requerida: "Tiendas", "Clientes" y "Ventas".

  4. Archivos no vacíos: Verifique que los archivos tiendas_*.csv, clientes_*.csv y ventas_*.csv contengan datos y no estén vacíos.

  5. 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.

  6. Reporte de Sincronización: Puedes obtener más datos de la falla accediendo a Configuración -> Sincronizaciones.

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

Comenzar con la generación de archivos con columnas que coincidan exactamente con las especificadas en la documentación. Consulta los archivos de ejemplo para despejar dudas.

Se recomienda iniciar el desarrollo por la entidad más sencilla: Tiendas.

Documentación de Procesos

Documentar cada paso del proceso de integración para futuras referencias y para asegurar una comprensión clara del flujo de datos.

Monitoreo y Optimización

Implementar un sistema de monitoreo para asegurar que la integración se realice de manera correcta y optimizar el proceso en función de los resultados obtenidos.


Timeline del Proyecto de Integración

Para asegurar una integración exitosa de los datos de las tiendas físicas con la plataforma WoowUp, se ha definido un timeline detallado con fechas aproximadas que guiará el proceso desde el inicio hasta la finalización del setup.

  1. Kickoff

    Esta es la fase inicial del proyecto donde se establece el alcance y los objetivos de la integración.

    Día 0.

  2. Reunión Técnica Tiendas Físicas

    Reunión entre los equipos técnicos de WoowUp 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.

  3. 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.

  4. 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 WoowUp.

    +10 días desde el primer entregable.

  5. Procesamiento de Datos Históricos

    WoowUp 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

  6. 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 WoowUp.


Parrafo para cerrar el articulo

¿Ha quedado contestada tu pregunta?