Integración de datos por API | WoowUp Help Center

Introducción

Bienvenido a la documentación de la API de WoowUp. Esta API permite integrar de manera eficiente los datos de tus clientes, tiendas, ventas y productos con nuestro CRM especializado en marketing relacional.

¿Qué podés hacer con la API?

Tiendas — Integración de sucursales físicas o puntos de venta.
Clientes — Registro, actualización y atributos personalizados.
Ventas — Envío de transacciones de tienda física o ecommerce.
Productos y Categorías — Mantenimiento del catálogo (opcional).

¿Cómo funciona la API?

La API de WoowUp sigue un enfoque RESTful y utiliza el protocolo HTTP. Esto significa que puedes realizar las siguientes operaciones:

GET: Recuperar información.
POST: Enviar nuevos registros.
PUT: Actualizar datos existentes.
DELETE: Eliminar registros (donde aplique).

Los datos se envían y reciben en formato JSON, y se recomienda utilizar HTTPS para asegurar todas las transacciones de datos.

⚠️La API tiene un límite de 140 requests por minuto. Si lo superás recibirás un HTTP 429. Ver la sección de Rate Limiting mas abajo para más detalles.

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

A continuación, se detallan los pasos para llevar a cabo la integración:

2. Primeros pasos, buenas prácticas y autenticación

2.1 Primeros pasos

Pedí un entorno de prueba en WoowUp:
- Las pruebas no deben afectar integraciones activas. Un entorno de prueba permite verificar el flujo sin impactar producción.

Solicitá acceso a WoowUp
- Necesitás acceso a la plataforma para consultar la API Key y monitorear los datos. Si no tenés acceso, contactá al equipo de soporte.

Obtené tu API Key
- Disponible en Configuración › Mi Cuenta › ApiKey. Debe incluirse en todas las solicitudes.
Importar colección
- Aca podes importar la colección con todos los endpoints preconfigurados para empezar a probar. Incluye ejemplos listos para usar de cada entidad: Tiendas, Clientes, Ventas y Productos. Solo tenés que reemplazar <tu_api_key> en el header de autenticación.

Antes de usar la colección, te recomendamos leer la documentación completa.

Colección de Postman

2.2 Autenticación

Todas las solicitudes requieren autenticación mediante un encabezado HTTP con la API Key:

Authorization: Basic <tu_api_key>

2.3 Buenas prácticas generales

Seguridad de la API Key — No la compartas públicamente. Almacenala en un lugar seguro.
Siempre HTTPS — Todas las solicitudes deben ir por HTTPS para garantizar el cifrado.
Rate Limiting — Límite de 140 requests por minuto. Ver sección siguiente.
Manejo de errores — La API usa códigos HTTP estándar (4xx / 5xx). Implementá manejo de excepciones.
Log de carga — Mantené un registro detallado: registros enviados, errores y advertencias.

2.4 Códigos de respuesta HTTP

La API utiliza códigos HTTP estándar. A continuación se detallan los más frecuentes y la acción recomendada ante cada uno:

Código	Significado	Acción recomendada
`200`	OK — Consulta exitosa	Continuar normalmente
`201`	Created — Registro creado	Continuar normalmente
`400`	Bad Request — Datos inválidos o faltantes	Revisar el body enviado y los campos obligatorios
`401`	Unauthorized — API Key incorrecta o ausente	Verificar el header de autenticación
`404`	Not Found — Recurso no encontrado	Verificar el ID o parámetro enviado
`409`	Conflict — Registro duplicado	Verificar si el recurso ya existe antes de crearlo
`429`	Too Many Requests — Rate limit superado	Esperar los segundos indicados en `Retry-After` y reintentar
`500`	Internal Server Error — Error en WoowUp	Reintentar con backoff exponencial. Si persiste, contactar soporte

💡 Ante un 500, implementar al menos 3 reintentos con backoff antes de escalar al equipo de soporte. WoowUp no tiene visibilidad sobre los datos que se intentan enviar, por lo que el log del lado del cliente es clave para el diagnóstico.

2.5 Orden de implementación

Antes de arrancar, es importante entender el orden en que deben desarrollarse e integrarse las entidades. Algunas dependen de que otras ya existan en WoowUp para funcionar correctamente.

Tiendas → Clientes → Ventas → Productos y Categorías (opcional) → Stats

⚠️ No es posible registrar una venta si la tienda referenciada en branch_name no existe previamente en WoowUp. El mismo criterio aplica para el cliente asociado a la venta.

2.6 Rate Limiting

La API limita la cantidad de requests por cuenta para garantizar la estabilidad del servicio. El límite por defecto es de 140 requests por minuto.

El sistema divide el tiempo en segmentos de 30 segundos y evalúa siempre dos segmentos: el actual y el anterior. Los requests del segmento actual cuentan al 100%, mientras que los del segmento anterior se ponderan según el tiempo transcurrido — cuanto más tiempo pasó, menos pesan.

💡Este mecanismo genera una transición suave entre ventanas, evitando el problema clásico de los contadores fijos donde un cliente puede duplicar el límite en el borde del reset.

Algoritmo de cálculo

Fórmula
peso       = 1 - (segundos_transcurridos / duración_segmento)
estimación = (requests_anteriores × peso) + requests_actuales
if estimación ≥ límite → HTTP 429

Ejemplo: Segmento anterior con 60 requests, actual con 25, a los 15 segundos:

Ejemplo de cálculo
peso       = 1 - (15 / 30) = 0.5
estimación = (60 × 0.5) + 25 = 55  →  Permitido (< 70)

Headers de respuesta

Todas las respuestas incluyen estos headers para monitorear el consumo en tiempo real:

Header	Descripción	Ejemplo
x-rate-limit-limit	Máximo de requests por ventana	70
x-rate-limit-remaining	Requests restantes en la ventana actual	45
x-rate-limit-reset	Unix de cuándo se renueva la ventana	1742121660

Cuando se supera el límite, la API responde con HTTP 429 Too Many Requests e incluye:

Header	Descripción	Ejemplo
Retry-After	Segundos que debés esperar antes de reintentar	18

Ejemplos de respuesta HTTP

HTTP 200 — Normal

HTTP/1.1 200 OK
x-rate-limit-limit: 70
x-rate-limit-remaining: 45
x-rate-limit-reset: 1742121660

HTTP 429 — Límite superado

HTTP/1.1 429 Too Many Requests
Retry-After: 18

Buenas prácticas de Rate Limiting

Monitoreá los headers — Revisá x-rate-limit-remaining en cada respuesta antes de alcanzar el límite.
Reintentá con backoff — Cuando recibas un 429, esperá los segundos indicados en Retry-After.
Distribuí los requests — Repartí las llamadas de forma uniforme en lugar de enviar ráfagas.
Usá paginación eficiente — Usá valores altos de limit (ej: ?limit=100) para reducir la cantidad de requests necesarios.

3. Entidad Tiendas

La entidad Tiendas en WoowUp te permite gestionar las ubicaciones físicas de tu negocio, ya sean sucursales, puntos de venta o incluso tiendas de ecommerce. Esta entidad es clave para integrar datos de ventas realizadas en diferentes ubicaciones y asociarlas correctamente a los clientes.

📌El campo name es el identificador único de la tienda y es el que se referencia en las ventas con el campo branch_name.

Campos permitidos

Campo

Tipo

Descripción

Ejemplo

Obligatorio

name	`String`	Identificador único de la tienda	A101	Sí
display_name	`String`	Nombre de la tienda	Sucursal Palermo	Sí
branch_zone_code	`String`	Código de la zona	13	No
branch_zone_name	`String`	Nombre de la zona	Buenos Aires	No

3.1 Endpoints principales

La API de WoowUp proporciona varios endpoints para interactuar con la entidad Tiendas. A continuación, se detallan los más relevantes:

POST

https://api.woowup.com/apiv3/branches

PUT

https://api.woowup.com/apiv3/branches/{id}

GET

https://api.woowup.com/apiv3/branches?page=0&limit=20

DELETE

https://api.woowup.com/apiv3/branches

Crear tienda (POST):

Este endpoint te permite agregar una nueva tienda en WoowUp.

Ejemplo:

curl --request POST \ 
--url https://api.woowup.com/apiv3/branches \ 
--header 'Authorization: Basic <tu_api_key>' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data:{ 
"name": "A101", 
"display_name": "Sucursal Palermo",
"branch_zone": {
	"id": "005106",
	"name": "Centro"}
}

Respuesta

{
    "payload": {
        "id": 94848,
        "name": "A101",
        "display_name": "Sucursal Palermo",
        "description": null,
        "status": "active",
        "holder": null,
        "email": null,
        "telephone": null,
        "address": "Calle Falsa 123",
        "working_hours": null,
        "notes": null,
        "branch_zone": null,
        "country": null,
        "state": "Estado Y",
        "city": "Ciudad X",
        "location_type": null,
        "business_type": null,
        "shopping_center": null,
        "format": null,
        "group": null,
        "m2": null,
        "m2_cost": null,
        "employees_quantity": null,
        "is_web": false,
        "createtime": "2024-10-04T05:05:16+00:00",
        "updatetime": "2024-10-04T05:05:16+00:00"
    },
    "message": "ok",
    "code": "ok",
    "time": "22ms"
}

Actualizar tienda (PUT):

Modifica los datos de una tienda existente.

Como parámetro se debe enviar el id de la tienda, el cual se obtiene haciendo antes un GET o, dentro de WoowUp, en Configuración > Tiendas.

Ejemplo:

curl --request PUT \ 
--url https://api.woowup.com/apiv3/branches/{id} \ 
--header 'Authorization: Basic <tu_api_key>' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data:{ 
"name": "A101", 
"display_name": "Sucursal Palermo Nueva"
}

Respuesta

{
    "payload": {
        "id": 94848,
        "name": "A101",
        "display_name": "Sucursal Palermo Nueva",
        "description": null,
        "status": "active",
        "holder": null,
        "email": null,
        "telephone": null,
        "address": "Calle Falsa 123",
        "working_hours": null,
        "notes": null,
        "branch_zone": null,
        "country": null,
        "state": "Estado Y",
        "city": "Ciudad X",
        "location_type": null,
        "business_type": null,
        "shopping_center": null,
        "format": null,
        "group": null,
        "m2": null,
        "m2_cost": null,
        "employees_quantity": null,
        "is_web": false,
        "createtime": "2024-10-04T05:05:16+00:00",
        "updatetime": "2024-10-08T05:05:16+00:00"
    },
    "message": "ok",
    "code": "ok",
    "time": "22ms"
}

Obtener tiendas (GET):

Este endpoint permite recuperar la lista de todas las tiendas activas en la plataforma. Se puede realizar una páginación con los parámetros page y limit.

Ejemplo de solicitud:

curl --request GET \ 
--url https://api.woowup.com/apiv3/branches?page=0&limit=1 \ 
--header 'Authorization: Basic <tu_api_key>' \
--header 'accept: application/json' \

Respuesta

{
    "payload": [
        {
            "id": 1,
            "name": "A101",
            "display_name": "Sucursal Palermo",
            "description": "",
            "status": "active",
            "created": "2018-04-13 15:12:50",
            "modified": null,
            "holder": null,
            "email": null,
            "telephone": null,
            "address": null,
            "working_hours": null,
            "notes": null,
            "branch_zone_name": null
        }
    ],
    "message": "ok",
    "code": "ok",
    "time": "25ms"
}

Eliminar tienda (DELETE):

Permite eliminar una tienda existente de la plataforma.

En este caso, el id debe enviarse en el body de la consulta junto a un email para notificar cuando el proceso de borrado haya finalizado.

Ejemplo:

curl --request DELETE \ 
--url https://api.woowup.com/apiv3/branches \ 
--header 'Authorization: Basic <tu_api_key>' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data:{ 
"id": 00000, 
"notify_to": "[email protected]"
}

Respuesta

{
    "payload": {
        "request_id": "XXXX"
    },
    "message": "ok",
    "code": "ok",
    "time": "62ms"
}

3.2 Consideraciones importantes

Identificación de tiendas: Cada tienda tiene un id único que WoowUp asigna automáticamente al momento de su creación. Utiliza este id para realizar modificaciones o eliminar tiendas.

Datos requeridos: Para crear o actualizar una tienda, es necesario proporcionar al menos los campos obligatorios como name, y display_name,. Asegúrate de revisar la documentación completa para ver qué campos son opcionales.

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

4. Entidad Clientes

Gestión de la información y atributos personalizados de los clientes

La entidad Clientes en WoowUp te permite gestionar la información de tus usuarios, incluyendo sus datos personales, comportamiento de compra y atributos personalizados. Este recurso es fundamental para crear campañas de marketing efectivas basadas en el perfil y la actividad de los clientes.

Diccionario de campos:

Campos / Cabeceras de la entidad Clientes

Campo

Tipo

Descripción

Ejemplo

Obligatorio

document	`String`	Documento o cédula del cliente.	30300300	Si
email	`String`	Email del cliente.	[email protected]	Si
first_name	`String`	Nombre del cliente.	Christian	No
last_name	`String`	Apellido del cliente.	Vitale	No
telephone	`String`	Teléfono con formato E.164 internacional.	+541173682446	No
birthdate	`Date`	Fecha de nacimiento (sin hora). Formato YYYY-MM-DD.	1992-03-31	No
gender	`Enum`	Género. Valores permitidos: M, F, vacío.	M	No
street	`String`	Calle y número de la dirección.	ohm 2220	No
city	`String`	Ciudad.	CABA	No
state	`String`	Provincia/Estado.	CABA	No
department	`String`	Barrio o departamento.	Villa Urquiza	No
postcode	`String`	Código postal.	1431	No
points	`Integer`	Puntos	100	No
mailing_enabled	`Enum`	Habilitación para envíos por email. Valores: enabled, disabled.	enabled	No
sms_enabled	`Enum`	Habilitación para envíos por SMS. Valores: enabled, disabled.	disabled	No
whatsapp_enabled	`Enum`	Habilitación para envíos por WhatsApp. Valores: enabled, disabled.	disabled	No

Buenas Practicas:

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.
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. Este campo se utiliza únicamente para hacer envíos de Whatsapp.
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.
Points: 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 aplica cargos adicionales.

4.1 Identificación de clientes mediante múltiples identificadores

WoowUp permite identificar a un cliente utilizando varios identificadores clave, lo que garantiza que puedas trabajar con los datos del cliente de manera flexible:

document: Número de documento de identidad.
email: Correo electrónico principal del cliente.
telephone: Número de teléfono móvil.

Para interactuar con la API de WoowUp, cualquiera de estos identificadores puede utilizarse para obtener, actualizar o crear un cliente. Al menos uno debe estar presente.

La jerarquía y prioridad de los identificadores es la que se muestra en el listado, sin embargo es completamente personalizable dentro de WoowUp.

Endpoints

GET

https://api.woowup.com/apiv3/multiusers/exist?document=X&email=Y

GET

https://api.woowup.com/apiv3/multiusers/find?document=X&email=Y

POST

https://api.woowup.com/apiv3/users

PUT

https://api.woowup.com/apiv3/multiusers

DELETE

https://api.woowup.com/apiv3/multiusers

DELETE

https://api.woowup.com/apiv3/multiusers/bulk

(borrado masivo por segmento)

4.2 Lógica para crear o actualizar un cliente

Antes de crear o actualizar un cliente, verifica si ya existe en la base de datos de WoowUp utilizando el endpoint GET /users/exist. Dependiendo de la respuesta, se tomará una acción:

Verificar si el cliente existe (GET user exist):
Este endpoint permite verificar si un cliente con esos identificadores específicos ya está registrado en la base de datos de WoowUp. En este ejemplo, se incluyen el documento y el email del cliente, pero es posible incluir hasta los 4 identificadores como parámetros.

Ejemplo:

curl --request GET \ 
--url https://api.woowup.com/apiv3/multiusers/exist?document=12345678&[email protected]\
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \ 
--header 'Authorization: Basic <tu_api_key>'

Respuesta:

{
    "payload": {
        "exist": true,
        "userapp_id": "31173442"
    },
    "message": "",
    "code": "ok",
    "time": "57ms"
}

A partir de la respuesta "exist": true/false, debemos optar por actualizar o crear el cliente dentro de WoowUp.

2. Actualizar un cliente existente (PUT user): Si el cliente existe, es posible actualizar su información mediante este endpoint. Es necesario enviar en el body al menos un identificador (documento, email, teléfono o service_uid).

Ejemplo:

curl --request PUT \ 
--url https://api.woowup.com/apiv3/multiusers \ 
--header 'Authorization: Basic <tu_api_key>' \ 
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \ 
--data '{
"document": "12345678",
"email": "[email protected]",
"first_name": "Juan",
"last_name": "Pérez",
"state": "CABA",
"city": "Buenos Aires",
"custom_attributes": {
      "loyalty_level": "Gold",
      "favorite_store": "Store N°01"
        }
}'

Respuesta:

Como respuesta obtendrás todos los campos con los datos actualizados del cliente

{
    "payload": {
        "userapp_id": XXXXXXXX,
        "user_id": YYYYYYYY,
        "app_id": ZZZ,
        "service_uid": null,
        "email": "[email protected]",
        "first_name": "Juan",
        "last_name": "Pérez",
        "telephone": null,
        "birthday": null,
        "gender": null,
        "document": "12345678",
        "document_type": null,
        "state": "CABA",
        "city": "Buenos Aires",
        "department": null,
        "address": null,
        "postal_code": null,
        "marital_status": null,
        "tags": null,
        "points": 0,
        "customform": [],
        "club_inscription_date": null,
        "blocked": false,
        "notes": null,
        "mailing_enabled": true,
        "mailing_enabled_reason": null,
        "whatsapp_enabled": false,
        "whatsapp_enabled_reason": "invalid_telephone",
        "sms_enabled": false,
        "sms_enabled_reason": "invalid_telephone",
        "custom_attributes": {      
               "loyalty_level": "Gold",
               "favorite_store": "Store N°01" },
        "family": [],
        "createtime": "2024-02-01T21:26:18+00:00",
        "updatetime": "2024-07-05T21:34:35+00:00"
    },
    "message": "ok",
    "code": "ok",
    "time": "50ms"
}

3. Crear un nuevo cliente (POST user):
Si el cliente no existe, procede a crearlo.

Ejemplo:

curl --request POST \ 
--url https://api.woowup.com/apiv3/users \ 
--header 'Authorization: Basic <tu_api_key>' \ 
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \ 
--data '{
"document": "12345678",
"document_type": "DNI",
"email": "[email protected]",
"first_name": "Juan",
"last_name": "Pérez",
"state": "CABA",
"city": "Buenos Aires",
"telephone": "+54911558877744",
"birthdate": "1990-01-21",
"gender": "M",
"marital_status": "single",
"tags": "tag1,tag2",
"points": 150,
"mailing_enabled": "enabled",
"custom_attributes": {
      "loyalty_level": "Gold",
      "favorite_store": "Store N°01"
        }
}'

Respuesta:

Como respuesta obtendrás todos los campos con los datos creados del cliente

{
    "payload": {
        "userapp_id": XXXXXXXX,
        "user_id": YYYYYYYY,
        "app_id": ZZZ,
        "service_uid": null,
        "email": "[email protected]",
        "first_name": "Juan",
        "last_name": "Pérez",
        "telephone": "+54911558877744",
        "birthday": "1990-01-21",
        "gender": "M",
        "document": "12345678",
        "document_type": null,
        "state": "CABA",
        "city": "Buenos Aires",
        "department": null,
        "address": null,
        "postal_code": null,
        "marital_status": null,
        "tags": "tag1,tag2",
        "points": 150,
        "customform": [],
        "club_inscription_date": null,
        "blocked": false,
        "notes": null,
        "mailing_enabled": true,
        "mailing_enabled_reason": null,
        "whatsapp_enabled": true,
        "whatsapp_enabled_reason": null,
        "sms_enabled": true,
        "sms_enabled_reason": null,
        "custom_attributes": {      
               "loyalty_level": "Gold",
               "favorite_store": "Store N°01" },
        "family": [],
        "createtime": "2024-02-01T21:26:18+00:00",
        "updatetime": "2024-07-05T21:34:35+00:00"
    },
    "message": "ok",
    "code": "ok",
    "time": "50ms"
}

4.3 Consulta de clientes mediante múltiples identificadores

Obtener un cliente (GET user):
Para obtener los datos de un cliente individual ya registrado en WoowUp, puedes usar el siguiente endpoint. Se puede buscar al cliente utilizando cualquiera de los identificadores disponibles: email, document, telephone, o service_uid.

Ejemplo:

curl --request GET \ 
--url https://api.woowup.com/apiv3/multiusers/find?document=20983522&[email protected] \ 
--header 'Authorization: Basic <tu_api_key>' \ 
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \

La respuesta incluirá todos los detalles del cliente, como su nombre, apellidos, correo electrónico, teléfono, y cualquier atributo personalizado que hayas definido.

Respuesta:

{
    "payload": {
        "userapp_id": XXXXXXXX,
        "user_id": YYYYYYYY,
        "app_id": ZZZ,
        "service_uid": null,
        "email": "[email protected]",
        "first_name": "Juan",
        "last_name": "Pérez",
        "telephone": "+54911558877744",
        "birthday": "1990-01-21",
        "gender": "M",
        "document": "12345678",
        "document_type": null,
        "state": "CABA",
        "city": "Buenos Aires",
        "department": null,
        "address": null,
        "postal_code": null,
        "marital_status": null,
        "tags": "tag1,tag2",
        "points": 150,
        "customform": [],
        "club_inscription_date": null,
        "blocked": false,
        "notes": null,
        "mailing_enabled": true,
        "mailing_enabled_reason": null,
        "whatsapp_enabled": true,
        "whatsapp_enabled_reason": null,
        "sms_enabled": true,
        "sms_enabled_reason": null,
        "custom_attributes": {      
               "loyalty_level": "Gold",
               "favorite_store": "Store N°01" },
        "family": [],
        "createtime": "2024-02-01T21:26:18+00:00",
        "updatetime": "2024-07-05T21:34:35+00:00"
    },
    "message": "ok",
    "code": "ok",
    "time": "50ms"
}

4.4 Eliminar un cliente (DELETE user):

Si es necesario eliminar un cliente de WoowUp, usa el siguiente endpoint. Asegúrate de identificar correctamente al cliente antes de realizar esta operación usando sus identificadores en el body.

Ejemplo:

curl --request DELETE \ 
--url https://api.woowup.com/apiv3/multiusers \ 
--header 'Authorization: Basic <tu_api_key>' \ 
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \ 
--data '{
"document": "12345678",
"email": "[email protected]"
}'

Respuesta:

{
    "payload": [],
    "message": "ok",
    "code": "ok",
    "time": "98ms"
}

4.5 Eliminar un segmento de clientes (DELETE users bulk):

Si deseas eliminar una gran cantidad de clientes de WoowUp, puedes crear primero un segmento en WoowUp, guardarlo y luego eliminar todos los clientes pertenecientes a ese segmento mediante este endpoint.

En el body se debe enviar el parámetro segment_id, siendo el id el número que se obtiene en la URL de WoowUp al seleccionar el segmento de la lista desplegable.

Ejemplo:

curl --request DELETE \ 
--url https://api.woowup.com/apiv3/multiusers/bulk \ 
--header 'Authorization: Basic <tu_api_key>' \ 
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \ 
--data '{
"segment_id": 4321,
"notify_to": "[email protected]"
}'

Respuesta:

{
    "payload": { "request_id": "XXX" },
    "message": "ok",
    "code": "ok",
    "time": "111ms"
}

4.6 Atributos extendidos

WoowUp te permite agregar atributos personalizados a cada cliente, lo que facilita la segmentación y análisis de tu base de datos de manera flexible. Estos atributos pueden incluir información adicional relevante para tu negocio, como nivel de fidelidad, preferencias de compra u otros datos específicos.

Antes de enviarlos en una consulta, es necesario crearlos dentro de WoowUp.

Puedes consultar esta documentación para obtener más información:

Atributos Extendidos ¿Cómo agregar más datos a tu base?

Ejemplo de atributos extendidos:

"custom_attributes": { 
   "loyalty_level": "Platinum",
   "favorite_category": "Electrónica" 
  }

¿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

5. Entidad Ventas

Registro y gestión de transacciones

La entidad Ventas en WoowUp permite registrar y gestionar todas las transacciones realizadas por los clientes, vinculando esta información a sus perfiles. Esto es crucial para el análisis del comportamiento de compra y para personalizar campañas de marketing.

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

⚠️ Las ventas deben enviarse con createtime y updatetime en horario UTC, luego WoowUp hace el cambio según la zona horaria configurada.

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.	[email protected]	Si
invoice_number	`String`	Número de factura. Debe ser ÚNICO por venta. Ver recomendación de armado abajo.	FAC0230321	Si
createtime	`String`	Fecha y hora de la venta. Ver sección 6.3.1 sobre zona horaria.	2020-01-23 16:32:05	Si
channel	`Enum`	Canal de venta. Valores: web, in-store.	in-store	Si
branch_name	`String`	Código de la tienda donde se realizó la venta. Debe coincidir con el campo 'name' del archivo de Tiendas.	A101	Si
points	`Integer`	Puntos otorgados por la venta. Aplica solo si el cliente tiene contratado Loyalty.	100	No
shipping	`Float`	Costo de envío. NO debe sumarse al total de la factura.	500	No
gross	`Float`	Subtotal de la factura (sin impuestos, sin envíos y sin descuentos). Se repite línea a línea.	9000	Si
tax	`Float`	Impuestos de la factura. Se repite línea a línea.	1400	No
discount	`Float`	Descuento total de la factura (incluye descuentos a nivel producto y a nivel factura). Se repite línea a línea.	2000	No
total	`Float`	Total de la factura. Se repite línea a línea. No debe incluir shipping.	9400	Si
payment_type	`Enum`	Medio de pago. Valores: credit, debit, mercadopago, todopago, cash, other. Ver nota sobre entidad Pagos.	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.	[email protected]	No
seller_external_id	`String`	Id externo del vendedor.	10	No
SKU	`String`	Código del producto. Ver sección 6.3.3 sobre criterio de SKU por vertical.	AB123324	Si
product_name	`String`	Nombre del producto.	Celular Moto Z	Si
brand	`String`	Marca del producto.	Motorola	No
quantity	`Integer`	Cantidad de unidades del producto en esta línea. En notas de crédito debe ser negativo.	2	Si
unit_price	`Float`	Precio unitario del producto (sin impuestos y sin descuentos). En notas de crédito debe ser negativo.	1000	Si
variations	`String`	Características por las que se agrupan variantes del producto. Formato clave-valor separado por pipes (\|).	Color: Blanco \| Talle: XXXL	No

Endpoints

POST

https://api.woowup.com/apiv3/purchases

GET

https://api.woowup.com/apiv3/purchases?invoice_number={invoice_number}

PUT

https://api.woowup.com/apiv3/purchases

DELETE

https://api.woowup.com/apiv3/purchases

5.1 Flujo de envío de ventas

En caso de que el proceso de ventas esté desincronizado con el proceso de clientes, es necesario cumplir nuevamente con la lógica de creación o actualización de un cliente dependiendo de si ya existe en WoowUp. Sigue el siguiente flujo:

Verificar si el cliente existe (GET user exist):
Antes de registrar una venta, es importante verificar si el cliente que realizó la compra ya está registrado en WoowUp. Usa el GET user exist para verificar esto.
Actualizar o crear el cliente según su existencia:
- Si el cliente existe (response: true), actualiza su información si es necesario con el endpoint PUT user.
- Si el cliente no existe (response: false), crea un nuevo cliente con el endpoint POST user.
Registrar la venta (POST purchase):
Una vez actualizado o creado del cliente, procede a registrar la venta en WoowUp. Se debe enviar al menos un identificador del cliente como el document o email del cliente, la lista de productos comprados, y los montos asociados.

5.2 Creación de una venta (POST purchase)

Para crear una venta, asegúrate de enviar la información correcta y completa en la solicitud a WoowUp. El proceso de creación de una venta sigue estos pasos clave, con estos campos incluídos en el cuerpo de la consulta:

Identificador del cliente:
Debes proporcionar uno de los identificadores principales del cliente, como su email, document, telephone, o service_uid, para asociar correctamente la venta con su perfil.
Productos comprados:
La venta debe incluir una lista de productos con sus respectivos sku, product_name, unit_price y quantity.
Montos de la venta:
Debes enviar el monto total de la venta, así como los detalles de cualquier descuento aplicado, impuestos, o cargos adicionales.
Fecha de la venta:
Asegúrate de enviar la fecha y hora exacta de la transacción en el campo createtime, en formato YYYY-MM-DD hh:mm:ss, expresadas en UTC. WoowUp convertirá automáticamente esta fecha a la zona horaria configurada en la cuenta para su visualización.

⚠️ Las ventas deben enviarse con createtime y updatetime en horario UTC. WoowUp tiene configurada la zona horaria del país y realiza la conversión horaria automáticamente dentro de la plataforma.

Ejemplo:

curl --request POST \ 
--url https://api.woowup.com/apiv3/purchases \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \ 
--header 'cache-control: no-cache' \
--header 'Authorization: Basic <tu_api_key>' \
--data {
"document": "123456789",
"invoice_number": "FAC-0000856789",
"channel": "in-store",
"purchase_detail": [
    {
      "sku": "2907362",
      "product_name": "Pantalón Negro",
      "quantity": 1,
      "unit_price": 1999.00,
      "variations": [
        {
          "name": "Talla",
          "value": "XS"
        }
      ]
    },
    {
      "sku": "4874645",
      "product_name": "Remera Manga Corta Blanca",
      "quantity": 1,
      "unit_price": 1200.00,
      "variations": [
        {
          "name": "Talla",
          "value": "S"
        }
      ]
    }
  ],
  "prices": {
    "cost": 2043.00,
    "shipping": 120.00,
    "gross": 3199.00,
    "tax": 199.00,
    "discount": 100.00,
    "total": 3219.00
  },
  "payment":{
    "type":"credit",
    "brand":"Visa",
    "bank": "Example Bank",
    "total": 3219.00,
    "installments": 12,
    "card_first_digits": "123456"
  },
  "branch_name": "A101",
  "seller":{
    "name": "Seller Relles",
    "email": "[email protected]",
    "external_id": "0001"
  },
  "createtime": "2024-07-23 14:35:22",
  "approvedtime": "2024-07-23 15:01:48",
  "custom_attributes": { 
    "fecha_max_cambio": "2024-08-23"
  }
}'

Respuesta:

{
    "payload": [],
    "message": "purchase successfully saved",
    "code": "ok",
    "time": "170ms"
}

5.3 Consulta de una venta (GET purchase)

Es posible consultar la información detallada de una venta registrada en WoowUp utilizando el endpoint GET purchase. Este proceso te permite acceder a los datos de una transacción en función de su número de factura (invoice_number), lo que resulta útil para verificar detalles específicos de una compra.

Paso a paso para consultar una venta:

Identificador de la venta:
Para realizar la consulta, es necesario proporcionar como parámetro el identificador único de la venta, que puede ser el invoice_number (número de la factura). Este valor debe estar asociado a una venta previamente registrada.

Solicitud GET:
La solicitud se realiza utilizando el endpoint GET /purchases/?invoice_number={invoice_number}, donde se sustituye {invoice_number} por el número de la factura de la venta que deseas consultar.

Ejemplo:

curl --request GET \ 
--url https://api.woowup.com/v3/purchases/?invoice_number=FAC-0000856789 \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \ 
--header 'Authorization: Basic <tu_api_key>'

Respuesta:
Si la venta existe, recibirás una respuesta en formato JSON que contiene todos los detalles de la transacción, incluyendo el cliente asociado, productos comprados, totales, y métodos de pago.

Ejemplo de respuesta:

{
    "payload": [
        {
            "service_uid": "123456789",
            "document": "123456789",
            "email": "[email protected]",
            "telephone": "11223344",
            "invoice_number": "FAC-0000856789",
            "channel": "in-store",
            "purchase_detail": {
                "items": [
                    {
                        "product_id": "2907362",
                        "product_name": "pantalón negro",
                        "quantity": 1,
                        "price": 1999,
                        "manufacturer_warranty_date": null,
                        "extension_warranty_date": null,
                        "custom_attributes": []
                    },
                    {
                        "product_id": "4874645",
                        "product_name": "remera manga corta blanca",
                        "quantity": 1,
                        "price": 1200,
                        "manufacturer_warranty_date": null,
                        "extension_warranty_date": null,
                        "custom_attributes": []
                    }
                ]
            },
            "prices": {
                "total": 3219,
                "gross": 3199,
                "discount": 100,
                "shipping": 120,
                "tax": 199,
                "cost": 2043
            },
            "points": 0,
            "downloadtime": "2024-07-23 14:35:22",
            "createtime": "2024-07-23 14:35:22",
            "metadata": null,
            "custom_attributes": {
                "fecha_max_cambio": "2024-08-23 00:00:00"
            },
            "cancel_transaction_id": null,
            "branch": {
                "id": 94848,
                "name": "A101"
            },
            "payment": {
                "type": "credit",
                "brand": "Visa",
                "name": "Example Bank"
            },
            "purchase_operator": {
                "name": "Seller Relles",
                "email": "[email protected]"
            },
            "pickup_store": null,
            "promotions": null
        }
    ],
    "message": "ok",
    "code": "ok",
    "time": "40ms"
}

5.4 Actualización de las ventas (PUT purchase)

La actualización de una venta en WoowUp se realiza utilizando el mismo proceso que la creación de una venta (POST), pero cambiando el método a PUT. Esto te permite modificar la información de una venta previamente registrada, como los productos comprados, montos, o datos del cliente.

5.5 Eliminación de una venta (DELETE purchase)

Si necesitas eliminar una venta registrada en WoowUp, puedes utilizar el método DELETE. Esto permite remover completamente la información de una transacción, lo cual puede ser necesario en caso de errores o registros duplicados.

Debes identificar la venta mediante el número de factura (invoice_number) en el body.

Ejemplo:

curl -X DELETE \
--url https://api.woowup.com/apiv3/purchases \
--header 'Accept: application/json' \
--header 'Authorization: Basic XXXXXXXXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--data '{
    "invoice_number": "FAC-0000856789"
}'

Respuesta:

{
    "payload": [],
    "message": "ok",
    "code": "ok",
    "time": "98ms"
}

5.6 Atributos extendidos en las ventas

Al igual que con los clientes, es posible enviar atributos personalizados en las ventas para agregar información adicional sobre la transacción. Estos atributos pueden utilizarse para análisis avanzados y segmentación.

Ejemplo con atributos personalizados:

 "custom_attributes": { 
    "fecha_max_cambio": "2024-08-23",
    "cupon_descuento": "15OFF",
    "pago_con_ahora12": "Si"
  }

5.7 Invoice_number ú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.

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

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

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

6. Entidad Productos (opcional)

Gestión de productos en WoowUp

La Entidad Productos en WoowUp permite registrar, actualizar y gestionar los productos que vendes en tu tienda.

La integración de esta entidad por API no es obligatoria. En muchos casos es preferible obtener estos datos de la integración nativa de su Ecommerce.

Integra esta entidad únicamente con la aprobación del equipo de WoowUp

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í

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.

Endpoints Productos

POST

https://api.woowup.com/apiv3/products

POST

https://api.woowup.com/apiv3/products/bulk

PUT

https://api.woowup.com/apiv3/products/{{encoded_base64_sku}}

GET

https://api.woowup.com/apiv3/products

GET

https://api.woowup.com/apiv3/products/{{encoded_base64_sku}}

Endpoints Categorias

GET

https://api.woowup.com/apiv3/categories

DELETE

https://api.woowup.com/apiv3/categories

6.1 Creación y actualización de productos

Registrar un nuevo producto (POST product):
Usa este endpoint para añadir un nuevo producto a tu catálogo en WoowUp. Es recomendable incluir todos los detalles disponibles del producto como SKU, nombre, categoría y precio.

Las categorías se envían como un array dentro del producto, ordenadas de la más general a la más específica. El primer elemento es la categoría raíz y el último es la categoría más específica a la que pertenece el producto. WoowUp interpreta el orden del array para construir la jerarquía.

Ejemplo:

curl --request POST \ 
--url https://api.woowup.com/apiv3/products \ 
--header 'Authorization: Basic <tu_api_key>' \ 
--header 'Content-Type: application/json' \ 
--data '{ 
"sku": "sku001", 
"name": "Producto A", 
"price": 100.0, 
"category": [
        {
            "id": "a",
            "name": "Todos los productos"          
        },
        {
            "id": "a-b",
            "name": "Hogar"
        },
        {
            "id": "a-b-c",
            "name": "Notebook"            
        }
    ]
 }'

Actualizar un producto existente (PUT product):
Si necesitas modificar la información de un producto ya existente, puedes hacerlo utilizando el SKU del producto.

Ejemplo:

curl --request PUT \ 
--url https://api.woowup.com/apiv3/products/{encoded_sku} \ 
--header 'Authorization: Bearer <tu_api_key>' \ 
--header 'Content-Type: application/json' \ 
--data '{ 
"name": "Producto A - Actualizado", 
"price": 120.0, 
 "category": [
        {
            "id": "a",
            "name": "Todos los productos"          
        },
        {
            "id": "a-b",
            "name": "Hogar"
        },
        {
            "id": "a-b-c",
            "name": "Notebook"            
        }
    ]
 }'

6.2 Obtención de productos

Puedes obtener la información de productos registrados en WoowUp mediante el endpoint GET products. Este recurso te permite acceder al catálogo completo de productos o filtrar por SKU específico.

Ejemplo para obtener todos los productos:

curl --request GET \ 
--url https://api.woowup.com/apiv3/products \ 
--header 'Authorization: Bearer <tu_api_key>'

Ejemplo para obtener un producto específico por SKU:

curl --request GET \ 
--url https://api.woowup.com/apiv3/products/{encoded_sku} \ 
--header 'Authorization: Bearer <tu_api_key>'

6.3 Eliminación de productos

No es posible eliminar un producto, sin embargo se puede quitar la recomendación del mismo para evitar que se presente en las campañas de forma automática. Para eso, debe hacerse una actualización para poner en stock = 0.

Ejemplo:

curl --request PUT\ 
--url https://api.woowup.com/apiv3/products/{encoded_sku} \ 
--header 'Authorization: Bearer <tu_api_key>'

6.4 Atributos extendidosen productos

Al igual que con los clientes y las ventas, es posible asignar atributos extendidos a los productos. Esto te permite añadir información extra que puede ser útil para análisis o segmentaciones avanzadas.

Ejemplo:

curl --request POST \
  --url https://api.woowup.com/apiv3/products \
  --header 'Authorization: Bearer <tu_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "sku": "sku001",
    "name": "Producto A",
    "price": 100.0,
    "custom_attributes": {
      "brand": "Marca X",
      "season": "Verano 2024"
    }
  }'

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.

7. Estadísticas de integración

Una vez en producción, podés registrar y consultar las estadísticas de cada ciclo de sincronización. Esto permite tener trazabilidad completa de lo que se procesó en cada carga: cuántos registros se crearon, actualizaron, fallaron, y el detalle línea a línea de los archivos enviados.

7.1 Crear estadísticas (POST)

POST

https://api.woowup.com/apiv3/integration-stats

Enviá las métricas de tu proceso de integración al finalizar cada ciclo de carga. Podés reportar resultados por entidad (clientes, productos, tiendas, ventas) y adjuntar el detalle de cada archivo procesado.

Ejemplo:

curl --request POST \
--url https://api.woowup.com/apiv3/integration-stats \
--header 'Authorization: Basic <tu_api_key>' \
--header 'Content-Type: application/json' \
--data '{
  "customers": {
    "created": 120,
    "updated": 45,
    "failed": [
      {
        "element": { "document": "99999", "email": "invalido" },
        "message": "Email inválido"
      }
    ]
  },
  "purchases": {
    "created": 300,
    "updated": 10,
    "duplicated": 5,
    "revenue": 158400.50,
    "units": 620,
    "failed": []
  },
  "files_stats": [
    {
      "filename": "ventas_2024-07-23.csv",
      "read_lines": 320,
      "valid_lines": 310,
      "unique_registers": 300,
      "revenue": 158400.50,
      "units": 620,
      "orders_customers": 280,
      "invalid_lines": [
        {
          "line": 45,
          "message": "invoice_number duplicado",
          "additional_details": { "invoice_number": "FAC-001" }
        }
      ]
    }
  ]
}'

Respuesta exitosa: 201 Created

Campos disponibles en el body:

Campo	Tipo	Descripción
customers	`object`	Stats de clientes: `created`, `updated`, `failed`
products	`object`	Stats de productos: `created`, `updated`, `failed`
branches	`object`	Stats de tiendas: `created`, `updated`, `failed`
purchases	`object`	Stats de ventas: `created`, `updated`, `duplicated`, `revenue`, `units`, `failed`
files_stats	`array`	Detalle por archivo procesado (ver abajo)

Campos de files_stats (un objeto por archivo):

Campo	Tipo	Descripción
filename	`String`	Nombre del archivo. Obligatorio.
read_lines	`Integer`	Total de líneas leídas
valid_lines	`Integer`	Líneas que pasaron validación
unique_registers	`Integer`	Registros únicos identificados
invalid_lines	`Array`	Detalle de líneas con error: `line`, `message`, `additional_details`
revenue	`Number`	Facturación total del archivo
units	`Integer`	Unidades totales
orders_customers	`Integer`	Cantidad de clientes únicos con pedidos

💡 El array failed de cada entidad acepta objetos con element (el registro que falló) y message (descripción del error). Esto facilita el diagnóstico sin tener que revisar los logs del sistema externo.

7.2 Consultar estadísticas (GET)

GET

https://api.woowup.com/apiv3/integration-stats

Recuperá el historial de estadísticas de sincronización, filtrando por rango de fechas y con paginación.

Parámetros de query:

Parámetro	Tipo	Descripción
from	`String`	Fecha de inicio. Formato `yyyy-mm-dd`
to	`String`	Fecha de fin. Formato `yyyy-mm-dd`
page	`String`	Página actual. Comienza en `0`
limit	`String`	Registros por página. Máximo `100`

Ejemplo:

curl --request GET \
--url 'https://api.woowup.com/apiv3/integration-stats?from=2024-07-01&to=2024-07-31&page=0&limit=20' \
--header 'Authorization: Basic <tu_api_key>' \
--header 'Accept: application/json'

7.3 Buenas prácticas

Registrá stats al finalizar cada ciclo — Enviá las estadísticas inmediatamente después de completar cada proceso de carga diario.
Incluí los failed con detalle — Cuanto más descriptivo sea el message y el element, más fácil es diagnosticar errores sin escalar al soporte.
Usá files_stats siempre que proceses archivos CSV — Permite tener trazabilidad completa de cada archivo en cada corrida.
Consultá el historial ante discrepancias — Antes de reportar un problema, revisá los stats del período afectado con el GET para identificar en qué ciclo ocurrió la desviación.

8. Envío del código implementado

Para garantizar que la integración esté correctamente desarrollada antes del pase a producción, el equipo de WoowUp realiza una auditoría del código implementado. A continuación se detallan los pasos y requisitos para compartirlo.

8.1 ¿Por qué es necesario?

El código es la fuente de verdad de la integración. Revisarlo permite detectar de forma temprana problemas que no siempre son visibles en los datos: lógica de reintentos incorrecta, manejo de errores ausente, campos que se construyen mal, o flujos que no respetan el orden requerido por la API.

8.2 Qué debe incluir el envío

Se requiere el código correspondiente a cada entidad integrada. Por cada una, compartir:

Entidad	Qué incluir
Tiendas	Lógica de extracción, transformación y envío (POST / PUT)
Clientes	Flujo completo: exist → POST o PUT, manejo de identificadores y atributos extendidos
Ventas	Flujo completo: exist → POST o PUT de cliente → POST de venta, construcción de `invoice_number`, manejo de devoluciones
Productos y Categorías	Lógica de creación y actualización (si aplica)
Stats	Código que registra y envía las estadísticas al finalizar cada ciclo

Además del código por entidad, incluir:

Manejo de errores y reintentos — Cómo se gestionan los HTTP 4xx / 5xx y el backoff ante un 429.
Scheduler o disparador — Cómo y cuándo se ejecuta el proceso diario (cron, job, trigger, etc.).
Logs — Dónde y cómo se registran los errores y advertencias de cada ciclo.

8.3 Formato de entrega

El código puede enviarse de cualquiera de estas formas:

Repositorio — Compartir acceso de lectura al repositorio (GitHub, GitLab, Bitbucket, etc.) con el equipo de WoowUp ([email protected]).
Archivos comprimidos — Enviar los archivos fuente en un .zip por el canal de comunicación acordado.

⚠️ No enviar credenciales ni API Keys dentro del código. Verificar que estén parametrizadas por variables de entorno antes de compartir.

8.4 Checklist previo al envío

Antes de compartir el código, verificar que cumpla con los siguientes puntos:

El flujo de clientes respeta el orden: exist → POST o PUT
El flujo de ventas respeta el orden: exist → POST/PUT cliente → POST venta
Las fechas se envían en UTC
Se implementa manejo de HTTP 429 con Retry-After
Se registran las estadísticas de integración al finalizar cada ciclo (ver sección 7)

8.5 Proceso de revisión

Una vez recibido el código, el equipo de WoowUp realiza la auditoría y devuelve:

Observaciones bloqueantes — Problemas que deben corregirse antes de continuar.
Observaciones recomendadas — Mejoras que no bloquean pero se sugiere aplicar.
Aprobación formal — Confirmación de que el código está alineado con los requisitos de la integración.

📌 La auditoría del código es un requisito previo al pase a producción. No se habilita producción sin la aprobación formal de esta etapa.

9. Envió de datos históricos

Para comenzar la integración, necesitamos que nos envíes los datos históricos de los últimos dos años de todas las entidades acordadas en la etapa de análisis (Tiendas, Clientes, Ventas, y Productos/Categorías si corresponde).

Formato de envío

Los datos históricos deben enviarse en archivos CSV (encode UTF-8 y separador punto y coma), usando exactamente el mismo esquema de campos que se usaría en el JSON de la API.

Podes consultar la documentación de CSV aquí:

https://help.woowup.com/es/articles/9441562-integracion-de-tiendas-fisicas-con-archivos-csv

Proceso

Una vez recibidos los archivos, el equipo de WoowUp realiza un análisis previo que incluye:

Cantidad de ventas, clientes, tiendas, productos y categorías a integrar.
Validación de campos obligatorios y calidad de los datos.
Detección de inconsistencias antes de la carga.

📌 No se inicia la integración hasta el cliente dé el OK sobre los datos relevados.

10. Subida de datos al entorno de testing

La subida al entorno de testing es progresiva y se realiza en dos etapas:

Etapa 1 — Validación de endpoints

Antes de cualquier carga masiva, validar que cada endpoint funcione correctamente enviando:

1 tienda
1 cliente
1 venta (con productos y categorías si corresponde)

Verificar que las respuestas sean exitosas ("code": "ok") y que los datos aparezcan correctamente en la plataforma.

Etapa 2 — Carga automatizada de prueba

Una vez confirmado que todos los endpoints funcionan, comenzar a enviar durante 1 semana la carga automatizada de cada entidad simulando el proceso diario real.

⚠️ Avisarnos cuando arrancan con esta etapa.

Validación final del testing

Al finalizar la semana de carga, ambas partes realizan una validación conjunta para confirmar que:

Todos los datos fueron procesados correctamente.
No hay registros faltantes ni duplicados.
Los totales de ventas, clientes y productos coinciden con los datos enviados.

11. Validación de datos históricos en WoowUp

Una vez procesado el histórico dentro de la plataforma, el equipo de WoowUp envía un análisis de validación que compara:

Los datos del análisis previo (punto 6) vs. los datos efectivamente procesados en WoowUp.
Cantidad de ventas, clientes, tiendas y productos integrados.
Detección de cualquier discrepancia entre lo enviado y lo procesado.

📌 El cliente revisa este análisis y debe dar el OK formal antes de pasar a producción.

12. Paso a producción

Una vez validados los datos del entorno de testing y recibido el OK de ambas partes, se procede a la subida a producción.

Pasos para el pase a producción

Cambiar la API Key — Reemplazar la API Key del entorno de testing por la de producción en todas las solicitudes.
Cerrar el gap de datos — Antes de comenzar el envío diario, enviar todos los datos generados entre el último día del histórico y la fecha de pase a producción. Esto garantiza que no quede ningún período sin datos en WoowUp.
Activar el proceso diario — Una vez enviado el gap, activar el envío automatizado diario de todas las entidades.

⚠️ El pase a producción solo puede realizarse una vez que el procesamiento del histórico haya finalizado completamente.

13. Consideraciones finales

Errores en la carga

Si encontrás errores o datos faltantes, revisá los logs de las solicitudes a la API para identificar problemas específicos. WoowUp no tiene visibilidad directa sobre los datos que se intentan subir, por lo que la validación y el diagnóstico inicial deben realizarse del lado del cliente antes de escalar al equipo de soporte.

Ajustes en la integración

Si es necesario corregir datos ya enviados, usá los endpoints de actualización (PUT) para modificar registros incorrectos.

Monitoreo constante

Es recomendable realizar revisiones periódicas de la data integrada, especialmente durante los primeros días de la integración en producción, para asegurar que los datos fluyan correctamente entre WoowUp y tus sistemas.