Ir al contenido principal
Integración SQL para Tiendas Físicas
Actualizado hace más de una semana

Introducción

Esta guía proporciona detalles sobre la integración de tiendas físicas con WoowUp mediante una conexión directa con su base de datos SQL. 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 base de datos SQL de la marca y la plataforma WoowUp:

WoowUp consultará y 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.

Requisitos para la Conexión

  • Seguridad: Implementar medidas de protección adecuadas, como la configuración de un firewall, es crucial para garantizar la seguridad de sus datos. Habilitar la IP fija del servidor

  • Restricciones:
    No es posible la conexión mediante una VPN.

    La base de datos debe contar con el protocolo de seguridad TLS 1.2 como mínimo.

  • Tiempo de respuesta:

Credenciales SQL

Para establecer la conexión, WoowUp necesitará las siguientes credenciales:

  • Motor de Base de Datos (SQL Server, MySQL, etc.)

  • Host

  • Port

  • Database Schema

  • User

  • Password


Configuración de Vistas

WoowUp maneja los datos divididos en las siguientes entidades: Tiendas, Clientes y Ventas. Es necesario desarrollar una vista para cada entidad. Los nombres de las columnas deben coincidir exactamente con los solicitados en esta documentación. Es preferible entregar vistas en lugar de tablas.

Ejemplos de Consultas 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.

Consulta SQL de Ejemplo

SELECT * FROM woowup_tiendas;

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.

Consulta SQL de Ejemplo

Se filtran los clientes actualizados y creados en las últimas 48 horas.

SELECT * FROM woowup_clientes 
WHERE updatetime >= ‘2024-04-14 00:00:00’
OR createtime >= '2024-04-14 00:00:00';

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

❗Los campos createtime y updatetime deben estar en horario UTC

Campos / Cabeceras de la entidad Clientes

Campo

Tipo

Descripción

Ejemplo

Obligatorio

document

String

Documento o cédula

30300300

Si

email

String

Email

Si

createtime

Datetime

Fecha creación del cliente [hora UTC]

2024-04-28 10:39:00

Si

updatetime

Datetime

Fecha actualización del cliente [hora UTC]

2024-06-22 20:52:00

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.

Consulta SQL de Ejemplo

Se filtran las ventas creadas en las últimas 48 horas.

SELECT * FROM woowup_ventas 
WHERE createtime >= ‘2024-04-14 00:00:00’;

❗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

Si

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.

Consulta SQL de Ejemplo

Se filtran los pagos de las ventas creadas en las últimas 48 horas.

SELECT * FROM woowup_pagos 
WHERE createtime >= ‘2024-04-14 00:00:00’;

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

createtime

String

Fecha y Hora de la Venta

2020-01-23 16:32:05

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 extraen y procesan los datos correspondientes a las últimas 48 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

Se hará una carga de datos históricos de hasta 2 años. Las vistas deben contener información desde esa fecha. 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 de la base de datos: Asegúrese de que la base de datos esté operativa y respondiendo a las consultas.

  2. Credenciales y habilitación de la IP: Verifique que las credenciales de acceso a la base de datos sean correctas y que la IP fija de WoowUp esté habilitada en su firewall.

  3. Disponibilidad de vistas: Confirme que las vistas necesarias ('Tiendas', 'Clientes', 'Ventas') estén disponibles y accesibles.

  4. Datos de ventas recientes: Verifique que se hayan registrado ventas en las últimas 24 horas.

Si la falla se resuelve en menos de 24 horas, WoowUp procesará automáticamente los datos en el siguiente ciclo programado.

Contacto con Soporte

Si la falla persiste, contactar a [email protected].


Recomendaciones para el Inicio del Proyecto

Preparación de Vistas

Comenzar con la generación de vistas 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 las vistas SQL configuradas 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.


La integración de su base de datos SQL con WoowUp ofrece una solución eficiente y segura para mantener los datos de sus tiendas físicas actualizados y listos para su análisis y uso en campañas de marketing. La implementación de esta integración fortalecerá su estrategia omnicanal, mejorando la experiencia del cliente y potenciando los resultados de sus campañas de marketing.

Para cualquier duda o soporte adicional, no dude en contactar a nuestro equipo técnico.

¿Ha quedado contestada tu pregunta?