Introducción
Esta guía detalla el proceso de integración de tiendas físicas con WoowUp mediante archivos CSV depositados en un servidor SFTP. La integración permite construir una experiencia de CRM omnicanal, unificando los datos de tiendas físicas con los canales digitales.
El procesamiento de datos se realiza una vez por día en un horario preestablecido, asegurando que la información esté siempre actualizada y disponible para su uso en campañas de marketing, automatizaciones y segmentaciones.
Conexión Típica
A continuación se describe el flujo de datos 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 y Acceso al SFTP
Datos que provee WoowUp
Servidor (Host): sftp.woowup.com
Puerto: 22 (predeterminado de SFTP)
Usuario: asignado por WoowUp, específico por cliente.
Para cuentas con más de una marca: en caso de integraciones con múltiples marcas, WoowUp provee un SFTP independiente por cada cuenta. Los archivos de cada cuenta deben depositarse en su SFTP correspondiente.
Datos que provee el cliente
Clave SSH pública (archivo con extensión .pub).
IP fija desde la cual se realizará la conexión, para que WoowUp la habilite en el whitelist.
Pasos para generar una clave SSH
Para autenticarte en el servidor SFTP mediante una clave SSH, sigue estos pasos:
Generar el par de claves SSH (Solo una opción de las siguientes)
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]"
ECDSA de 521 bits ( ECDSA admite tamaños de clave de 256, 384 y 521 bits):
ssh-keygen -t ecdsa -b 521 -f key_name
Claves ED25519
ssh-keygen -t ed25519 -f key_name
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.
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.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.Configurar la conexión SFTP
Una vez que WoowUp haya registrado tu clave pública, te otorgara el acceso al SFTP. Asegúrate de especificar la ruta a tu clave privada en la configuración del cliente SFTP.Verificar la conexión
Para probar la conexión, puedes ejecutar el siguiente comando en tu terminal, reemplazandohostypuertocon 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:
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.
History: Aquí deberán ser depositados los archivos históricos a procesar durante la etapa del onboarding.
Importante sobre la carpeta history: esta carpeta no tiene un proceso automático corriendo sobre ella. Al depositar archivos históricos, es necesario notificar al equipo de WoowUp para que los procese manualmente.
Requisitos de los Archivos CSV
Los datos deben ser proporcionados en archivos CSV, con un archivo por cada entidad (Tiendas, Clientes, Ventas, y opcionalmente Pagos, Productos y Categorías).
Análisis de datos previo
Antes de comenzar con la construcción de los archivos, se realiza una instancia de análisis de datos en conjunto entre WoowUp y los equipos participantes del lado del cliente. El objetivo de esta etapa es:
Relevar las fuentes de datos disponibles (ERP, POS, SQL).
Validar que los campos mínimos obligatorios estén disponibles en origen.
Identificar reglas de negocio particulares (devoluciones, notas de crédito, ventas multi-medio de pago, clientes genéricos).
Definir el esquema de entidades a enviar (Tiendas, Clientes, Ventas, Pagos, Productos, Categorías).
Acordar el horario del ciclo de procesamiento diario.
Codificación y formato
Codificación: UTF-8
Separador de campos: ; (punto y coma)
Nomenclatura de archivos
Cada archivo CSV debe seguir una convención de nombres específica para asegurar su correcta identificación y procesamiento automático. La estructura es:
{entidad}_{YYYYMMDD}.csv
Ejemplos:
tiendas_20240625.csv
clientes_20240625.csv
ventas_20240625.csv
pagos_20240625.csv
productos_20240625.csv
categorias_20240625.csv
Tamaños de archivo y rendimiento
Cada archivo CSV depositado en el SFTP debe pesar menos de 30 MB. Los archivos que superen ese límite no se procesan y se mueven directamente a la carpeta failed.
Carga diaria: el volumen de 24 horas rara vez se acerca a los 30 MB. Si se excede, revisar si el job no está enviando por error datos acumulados o históricos en la carpeta pending.
Carga histórica: los archivos de ventas históricas deben enviarse spliteados mes a mes (un archivo por mes por entidad), tanto para mantenerse por debajo del límite de 30 MB como para facilitar el procesamiento y la validación por parte del equipo de WoowUp.
❗ Importante: si un archivo aparece en la carpeta failed sin errores evidentes de formato, validar el peso del archivo: si supera los 30 MB, hay que splitearlo (por ejemplo, por mes, por sucursal o por día) y reenviarlo a pending.
Entidades soportadas
WoowUp maneja las siguientes entidades dentro de la integración por CSV:
Tiendas (obligatoria)
Clientes (obligatoria)
Ventas (obligatoria)
Pagos (opcional, se utiliza cuando una venta tiene múltiples medios de pago)
Productos (opcional, solo si la información proviene del ERP y no del ecommerce)
Categorías (opcional, solo si la información proviene del ERP y no del ecommerce)
Configuración de Archivos por Entidad
Los nombres de las columnas deben coincidir exactamente con los solicitados en esta documentación. Cada entidad incluye campos obligatorios, opcionales y, en algunos casos, la posibilidad de agregar atributos extendidos.
Tiendas
Tiendas
Integración de las tiendas donde los clientes pueden realizar compras. Incluye tiendas físicas, canales web equivalentes (como MercadoLibre) y tiendas de bancos cuando aplique.
Recomendación: excluir la tienda de ecommerce de este archivo. Las ventas y la tienda del ecommerce se toman directamente desde la API del ecommerce mediante el conector correspondiente.
❗En esta entidad no es posible incluir atributos extendidos
Campos / Cabeceras de la entidad Tiendas
Campo | Tipo | Descripción | Ejemplo | Obligatorio |
name |
| Identificador único de la tienda. | A101 | Sí |
display_name |
| Nombre de la tienda tal cual se visualiza en WoowUp. | Sucursal Palermo | Sí |
branch_zone_code |
| Código de la zona comercial a la que pertenece la tienda. | 13 | No |
branch_zone_name |
| Nombre de la zona comercial. | Buenos Aires | No |
Buenas prácticas
No enviar almacenes ni depósitos donde el cliente no realiza compras.
Excluir la tienda de ecommerce; WoowUp la obtiene desde la API del ecommerce.
Usar un name estable en el tiempo. Cambiar el name implica que WoowUp interprete la tienda como nueva.
Archivo de Ejemplo
Clientes
Clientes
Integración de datos de clientes, incluyendo identificadores (document y/o email), datos de contacto, datos geográficos, de género, cumpleaños y preferencias de comunicación. Se envían únicamente los clientes creados o actualizados en las últimas 24 horas.
❗ Debes enviar al menos un identificador del cliente: document y/o email.
Clientes sin identificador: si el POS/ERP no captura al menos un identificador, se debe enviar un document genérico (siempre el mismo, por ejemplo 99999999) para que todas esas ventas queden consolidadas bajo un mismo cliente genérico. Notificar al equipo de WoowUp sobre el uso de este criterio.
❗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 |
| Documento o cédula del cliente. Para clientes genéricos usar un valor único (ej: 99999999). | 30300300 | Si |
| Email del cliente. No utilizar emails genéricos (ver Buenas Prácticas). | Si | ||
first_name |
| Nombre del cliente. | Christian | No |
last_name |
| Apellido del cliente. | Vitale | No |
full_name |
| Nombre completo. Usar este campo cuando el origen no tiene nombre y apellido separados. | Christian Vitale | No |
telephone |
| Teléfono con formato E.164 internacional: código de país + código de área + número, sin espacios ni símbolos. Ej: Argentina +54 9 11 7368 2446 → 5491173682446. | 5491173682446 | No |
birthdate |
| Fecha de nacimiento (sin hora). Formato YYYY-MM-DD. | 1992-03-31 | No |
gender |
| Género. Valores permitidos: M, F, vacío. | M | No |
street |
| Calle y número de la dirección. | ohm 2220 | No |
city |
| Ciudad. | CABA | No |
state |
| Provincia/Estado. | CABA | No |
department |
| Barrio o departamento. | Villa Urquiza | No |
postcode |
| Código postal. | 1431 | No |
points |
| Puntos del programa de loyalty. Ver nota abajo. | 100 | No |
mailing_enabled |
| Habilitación para envíos por email. Valores: enabled, disabled. | enabled | No |
sms_enabled |
| Habilitación para envíos por SMS. Valores: enabled, disabled. | disabled | No |
whatsapp_enabled |
| Habilitación para envíos por WhatsApp. Valores: 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.
¿Qué atributos extendidos puedo agregar según mi vertical? Consultar la guía por industria: https://help.woowup.com/es/articles/12693179-atributos-extendidos-por-industria
Nota sobre document / RUT / documentos extranjeros
El campo document admite distintos tipos de documento según el país del cliente. Debe enviarse siempre como string (sin puntos, guiones ni espacios, salvo que el formato del país lo requiera)
Nota sobre points (loyalty)
El campo points debe enviarse únicamente si el cliente tiene contratado el programa de Loyalty de WoowUp. Si el programa de puntos se maneja fuera de WoowUp, los puntos deben enviarse como atributo extendido (ej: custom_attributes.puntos_externos) y no como campo nativo points.
*El uso de este campo puede aplicar cargos adicionales.
Buenas prácticas
Enviar al menos un identificador (document o email) por cliente.
No enviar emails genéricos (ej: [email protected]). Si el POS obliga a cargar un email, usar [email protected] o dejar el campo vacío.
Para clientes no identificados, consolidar bajo un único document genérico (ej: 99999999) y notificar al equipo de WoowUp.
Enviar el teléfono en formato internacional E.164 (sin espacios, guiones ni símbolos).
Cuando la base no separa nombre y apellido, usar el campo full_name en lugar de first_name/last_name.
Archivo de Ejemplo
Se envían únicamente los clientes actualizados y creados en las últimas 24 horas.
Ventas
Ventas
Integración de los datos de ventas, incluyendo identificador del comprador, datos de la factura y productos comprados. Cada línea del CSV representa un producto distinto dentro de una misma factura. Se envían las ventas creadas en las últimas 24 horas.
❗ Recomendación: No enviar las ventas del ecommerce. Esas se obtienen desde la API del ecommerce a través del conector correspondiente.
❗ Los campos Total, Gross, Discount y Tax deben ser globales de toda la factura. Para un mismo invoice_number deben repetirse línea a línea.
❗ Enviar al menos un identificador de cliente (document y/o email).
Campos / Cabeceras de la entidad Ventas
Campo | Tipo | Descripción | Ejemplo | Obligatorio |
document |
| Documento o cédula del cliente. | 36872489 | Si |
| Email del cliente. | Si | ||
invoice_number |
| Número de factura. Debe ser ÚNICO por venta. Ver recomendación de armado abajo. | FAC0230321 | Si |
createtime |
| Fecha y hora de la venta. Ver sección 6.3.1 sobre zona horaria. | 2020-01-23 16:32:05 | Si |
channel |
| Canal de venta. Valores: web, in-store. | in-store | Si |
branch_name |
| Código de la tienda donde se realizó la venta. Debe coincidir con el campo 'name' del archivo de Tiendas. | A101 | Si |
points |
| Puntos otorgados por la venta. Aplica solo si el cliente tiene contratado Loyalty. | 100 | No |
shipping |
| Costo de envío. NO debe sumarse al total de la factura. | 500 | No |
gross |
| Subtotal de la factura (sin impuestos, sin envíos y sin descuentos). Se repite línea a línea. | 9000 | Si |
tax |
| Impuestos de la factura. Se repite línea a línea. | 1400 | No |
discount |
| Descuento total de la factura (incluye descuentos a nivel producto y a nivel factura). Se repite línea a línea. | 2000 | No |
total |
| Total de la factura. Se repite línea a línea. No debe incluir shipping. | 9400 | Si |
payment_type |
| Medio de pago. Valores: credit, debit, mercadopago, todopago, cash, other. Ver nota sobre entidad Pagos. | debit | Si |
payment_brand |
| Marca de la tarjeta. | Visa | No |
payment_bank |
| Banco emisor de la tarjeta. | Banco Galicia | No |
payment_installments |
| Cantidad de cuotas. | 6 | No |
payment_total |
| Total por medio de pago. | 9400 | No |
seller_name |
| Nombre del vendedor. | Gil Gunderson | No |
seller_email |
| Email del vendedor. | No | |
seller_external_id |
| Id externo del vendedor. | 10 | No |
SKU |
| Código del producto. Ver sección 6.3.3 sobre criterio de SKU por vertical. | AB123324 | Si |
product_name |
| Nombre del producto. | Celular Moto Z | Si |
brand |
| Marca del producto. | Motorola | No |
quantity |
| Cantidad de unidades del producto en esta línea. En notas de crédito debe ser negativo. | 2 | Si |
unit_price |
| Precio unitario del producto (sin impuestos y sin descuentos). En notas de crédito debe ser negativo. | 1000 | Si |
variations |
| Características por las que se agrupan variantes del producto. Formato clave-valor separado 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.
Document y email: debe enviarse al menos uno.
Payment_type es obligatorio únicamente si NO se envía el archivo de la entidad Pagos. Si se envía el archivo de Pagos, este campo no debe enviarse en Ventas (ver sección pagos).
Zona horaria y campo createtime
La fecha y hora de la venta deben enviarse de forma consistente. Se debe indicar explícitamente al equipo de WoowUp si el campo createtime viene en UTC o en horario local de la tienda.
Cuando el origen no dispone de horario (solo fecha), enviar la venta con la hora hardcodeada al último minuto del día (23:59:59). Esto es necesario para que WoowUp pueda asociar correctamente la venta a cualquier campaña o automatización que se haya ejecutado ese día: si se envía la venta con hora 00:00:00, quedaría antes de la ejecución de la campaña y no se atribuiría.
Número de factura único
El invoice_number debe ser único a nivel cuenta. Cuando la numeración del comprobante se repite entre sucursales o tipos de comprobante, se recomienda armarlo concatenando:
{punto_de_venta}{letra_comprobante}{numero_comprobante}
Por ejemplo: 0001A00000123. La combinación invoice_number + branch_name siempre debe ser única.
SKU
El SKU del archivo de ventas debe coincidir con el SKU usado en el ecommerce, para poder cruzar correctamente la información de producto entre ambos orígenes.
Moda: utilizar el código de referencia del producto (no el SKU de variante por talle/color).
Farma y Electro: utilizar el SKU completo de variante.
Notas de crédito y devoluciones
Las notas de crédito y devoluciones se envían en el mismo archivo de ventas, con valores numéricos negativos en los siguientes campos:
gross
discount
tax
total
unit_price
quantity
payment_total (si aplica)
points (si aplica)
El invoice_number de la nota de crédito debe ser distinto al de la venta original, siguiendo la misma regla de unicidad.
Uso de discount
El campo discount debe reflejar el descuento total aplicado a la factura, incluyendo tanto descuentos a nivel factura (ej: cupón general) como descuentos a nivel producto (ej: 2x1, promo por SKU). Esto es clave para que el Perfil 360 del cliente y las métricas de Analytics reflejen correctamente la rentabilidad real.
Buenas prácticas
No enviar ventas sin al menos un identificador de cliente.
Los SKUs del archivo de Ventas deben coincidir con los del ecommerce.
La combinación invoice_number + branch_name debe ser única. Concatenar si es necesario (punto de venta, letra de comprobante, número).
No enviar las ventas del ecommerce; se obtienen por el conector propio de WoowUp.
Las devoluciones y notas de crédito se envían con valores negativos en gross, discount, tax, total, unit_price, quantity, payment_total y points.
Los campos gross, discount, tax y total deben repetirse línea a línea para un mismo invoice_number.
El costo de envío (shipping) NO debe sumarse al total.
Archivo de Ejemplo
Se envían las ventas creadas en las últimas 24 horas.
Pagos (Opcional)
Pagos (Opcional)
La entidad Pagos es opcional y resulta útil cuando una misma venta puede tener más de un medio de pago asociado (pagos combinados). Permite vincular a un invoice_number múltiples registros de pago.
Importante: cuando se envía el archivo de Pagos, NO se debe enviar el campo payment_type ni los demás campos de pago dentro del archivo de Ventas. Los medios de pago se toman exclusivamente desde el archivo Pagos
Los archivos deben nombrarse pagos_{YYYYMMDD}.csv. Se envían los pagos de las ventas creadas en las últimas 24 horas.
Archivo de Ejemplo
Se envían los pagos de las ventas creadas en las últimas 24 horas.
Campos / Cabeceras de la entidad Pagos
Campo | Tipo | Descripción | Ejemplo | Obligatorio |
invoice_number |
| Número de factura tal cual aparece en el archivo de Ventas. | FAC0123213 | Si |
branch_name |
| Tienda donde se realizó la venta. | A101 | Si |
type |
| Tipo de pago. Valores: credit, debit, cash, mercadopago, other. | Credit | Si |
brand |
| Marca de la tarjeta. | VISA | No |
bank |
| Banco emisor de la tarjeta. | Banco Galicia | No |
total |
| Total pagado por este medio de pago. | 1299 | Si |
installments |
| Cantidad de cuotas. | 2 | No
|
card_first_digits |
| Primeros 6 dígitos de la tarjeta (BIN). Ver nota abajo. | 12321 | No |
Nota sobre card_first_digits (BIN)
El BIN (Bank Identification Number) corresponde a los primeros 6 dígitos del número de tarjeta. Permite identificar automáticamente la marca, el banco emisor y el tipo de tarjeta (crédito/débito) sin necesidad de enviar esos campos por separado.
Debe enviarse siempre como string (no como número), para preservar ceros a la izquierda.
Nunca enviar más de 6 dígitos: enviar más información de la tarjeta puede implicar un incumplimiento de PCI-DSS.
Si el POS no provee el BIN, dejar el campo vacío y enviar brand y bank como strings separados.
Buenas prácticas
Si se envía el archivo Pagos, NO enviar payment_type ni campos de pago en Ventas.
La suma de total por invoice_number en Pagos debe coincidir con el total de la factura en Ventas.
Enviar el BIN (card_first_digits) cuando esté disponible; nunca más de 6 dígitos por cumplimiento PCI-DSS.
Productos (Opcional)
Productos (Opcional)
La entidad Productos aplica únicamente cuando la información de catálogo proviene del ERP. Si el catálogo se obtiene desde la integración de ecommerce (VTEX, Shopify, etc.), este archivo NO debe enviarse: WoowUp toma los productos desde el conector correspondiente.
Reglas generales
Enviar únicamente las columnas definidas en esta documentación.
category_id debe contener siempre el ID de la categoría hija (último nivel de la jerarquía). NO se deben enviar nombres de categorías, solo IDs.
Ejemplo: si la estructura es BD01 > BE01 > BE50, el valor correcto de category_id es BE50.
Campos / Cabeceras — Productos
Campo | Tipo | Descripción | Ejemplo | Obligatorio |
sku | String | Código único del producto. Debe coincidir con el SKU del ecommerce. | AB123324 | Sí |
name | String | Nombre del producto. | Celular Moto Z | Sí |
category_id | String | ID de la categoría hija (último nivel). Debe existir en el archivo de Categorías. | BE50 | Sí |
Archivo de Ejemplo
Categorías (Opcional)
Categorías (Opcional)
El archivo de Categorías es fundamental para que WoowUp pueda reconstruir la jerarquía del árbol de categorías. Aplica únicamente si el archivo de Productos también se envía.
Reglas obligatorias
La jerarquía se define únicamente mediante el campo parent_id.
No se utiliza ningún otro campo para indicar niveles o relaciones.
Cada categoría debe tener id único, name y parent_id (vacío o null solo para categorías raíz).
Campos / Cabeceras — Categorías
Campo | Tipo | Descripción | Ejemplo | Obligatorio |
id | String | Identificador único de la categoría. | BE50 | Sí |
name | String | Nombre visible de la categoría. | Billeteras Mujer | Sí |
parent_id | String | ID de la categoría padre. Vacío o null para categorías raíz. | BE01 | Sí* |
* parent_id es obligatorio como columna, pero puede enviarse vacío cuando la categoría es raíz.
Ejemplo de archivo de Categorías
id | name | parent_id |
BD01 | Accesorios |
|
BE01 | Accesorios Mujer | BD01 |
BE50 | Billeteras Mujer | BE01 |
Cómo WoowUp construye el árbol de categorías
WoowUp no recibe la jerarquía armada: la construye internamente siguiendo los IDs y sus relaciones. El proceso es:
Lee el category_id del producto (ej: BE50).
Busca ese ID en el archivo de Categorías.
Identifica su parent_id (BE01) y lo vuelve a buscar. Encuentra que BE01 tiene como parent_id a BD01.
Busca BD01, encuentra parent_id vacío, finaliza la jerarquía.
De esta manera, el producto queda asociado a la estructura completa: Accesorios > Accesorios Mujer > Billeteras Mujer.
Errores frecuentes a evitar
Enviar en category_id un ID que no existe en el archivo de Categorías.
No enviar las categorías raíz.
Asignar productos a categorías padre en lugar de categorías hijas.
Enviar productos con categorías que no existen en el archivo de Categorías.
Generar ciclos en la jerarquía (una categoría que sea ancestro de sí misma).
Checklist de validación antes de enviar
Todos los category_id del archivo de Productos existen en el archivo de Categorías.
Los productos tienen el ID de la categoría hija (último nivel).
Cada categoría hija tiene su correspondiente categoría padre en el archivo.
Las categorías raíz tienen parent_id vacío.
Todos los id de categorías son únicos.
No hay ciclos en la jerarquía.
Buenas prácticas
Si el catálogo se integra por ecommerce, NO enviar Productos ni Categorías.
category_id en Productos siempre refiere a la categoría hija (último nivel).
Todas las categorías referenciadas desde Productos deben existir en Categorías.
Archivo de Ejemplo
Procesos de datos
Análisis de datos (etapa previa)
Antes de construir y enviar los archivos CSV, se realiza una reunión de análisis de datos entre el equipo técnico del cliente y el equipo de Integraciones de WoowUp. En esta reunión:
Se releva la arquitectura de datos del cliente (ERP/POS/SQL/exports).
Se mapean los campos disponibles contra los campos obligatorios de cada entidad.
Se identifican reglas de negocio específicas (multipago, notas de crédito, clientes genéricos, múltiples tiendas).
Se acuerda el alcance del primer entregable y el plan de pruebas.
Se define el horario del ciclo de procesamiento diario.
Proceso de carga diaria
Una vez acordado el esquema y generados los archivos de prueba, el cliente comienza a depositar diariamente los archivos en la carpeta pending del SFTP.
Cada archivo debe contener los datos de las últimas 24 horas.
WoowUp procesa los archivos en un horario diario pactado con el cliente.
Los archivos se mueven automáticamente de pending → processing → processed o failed.
Los archivos procesados exitosamente quedan disponibles para consulta histórica en la carpeta processed.
Los archivos que fallan quedan en failed y deben revisarse/corregirse antes de reenviarse a pending.
Proceso de datos históricos (history)
Durante el onboarding se realiza una carga inicial de hasta 2 años de datos históricos, para poblar la base de WoowUp con el comportamiento histórico de los clientes. Los archivos se depositan en la carpeta history del SFTP y deben incluir "history" en el nombre para diferenciarlos de los archivos regulares.
Archivos requeridos
Master de Tiendas: todas las tiendas activas e inactivas de los últimos 2 años.
Master de Clientes: todos los clientes creados en los últimos 2 años.
Ventas: separadas mes a mes, comenzando desde 2 años atrás.
Pagos (si aplica): siguiendo el mismo criterio mensual que ventas.
Productos y Categorías (si aplica): un master único de cada entidad.
Ejemplo de nombres de archivo histórico
tiendas_history.csv
clientes_history.csv
ventas_enero2023_history.csv
ventas_febrero2023_history.csv
ventas_marzo2023_history.csv
pagos_enero2023_history.csv
productos_history.csv
categorias_history.csv
Importante: la carpeta history NO tiene un proceso automático corriendo sobre ella. Una vez depositados los archivos, es necesario notificar al equipo de WoowUp para que los procese manualmente durante el sprint de onboarding.
Validación de Datos
Una vez procesados los archivos, es responsabilidad del cliente validar los resultados en WoowUp.
Cantidad de clientes
En WoowUp, ir a Segmentos y, sin aplicar filtros, hacer clic en el símbolo #. Puede haber más clientes en WoowUp que en la base de datos original, porque WoowUp crea automáticamente un cliente cuando detecta una venta con un document/email no registrado previamente en la entidad Clientes.
Cantidad y totales de ventas
Ir a Analytics > Listado de Facturas. Filtrar por fechas y tiendas, asegurándose de excluir la tienda de ecommerce para comparar contra los datos del ERP/POS.
Tiendas procesadas
Acceder a Configuración > Tiendas (menú lateral) para ver las tiendas procesadas y editarlas si fuese necesario.
Consistencia entre archivos
Todos los branch_name usados en Ventas existen en Tiendas.
Todos los document/email usados en Ventas existen (o serán creados automáticamente) en Clientes.
Los invoice_number son únicos por cuenta.
Si se envía Pagos: la suma de total por invoice_number en Pagos coincide con el total de la factura en Ventas.
Contingencias
Procedimiento en caso de fallos
En caso de no procesarse los datos, se envía una notificación por email al contacto técnico del cliente. Se recomienda validar los siguientes puntos:
Proceso de subida de archivos: confirmar que el proceso automático del cliente esté operativo y esté subiendo archivos.
Credenciales y habilitación de IP: verificar que las credenciales de SFTP sean correctas y que la IP fija siga whitelisteada por WoowUp.
Envío de todas las entidades obligatorias: confirmar que estén presentes los archivos de Tiendas, Clientes y Ventas.
Archivos no vacíos: verificar que los archivos no estén vacíos (solo cabecera).
Ventas recientes: confirmar que efectivamente haya habido ventas en las últimas 24 horas y que estén en el archivo.
Reporte de sincronizaciones
WoowUp mantiene un reporte detallado de cada ciclo de sincronización, accesible desde Configuración > Sincronizaciones. El reporte incluye:
Archivo procesado (nombre y timestamp).
Entidad a la que corresponde.
Cantidad de registros procesados con éxito.
Cantidad y detalle de registros con error (motivo por fila).
Estado final del archivo (processed/failed).
¿Cómo enterarme si está fallando algún proceso?
Para poder enterarte si algún procesamiento está fallando, debes activar las notificaciones dentro de Woowup
Configuración > Notificaciones
Recomendamos configurar:Clientes y ventas: Igual o menos de 0 creados en los últimos 3 días
Productos: Igual o menos de 0 creados en los últimos 7 días
Carritos abandonados y navegaciones web: Igual o menos de 0 creados en los últimos 2 días
