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

Campo

Tipo

Descripción

document	`string`	Documento o cédula
email	`string`	Email
telephone	`string`	Teléfono
service_uid	`string`	Identificador externo
first_name	`string`	Nombre
last_name	`string`	Apellido
birthdate	`string`	Fecha de nacimiento Formato: yyyy-mm-dd
gender	`enum`	Valores: "F", "M"
street	`string`	Dirección
postcode	`string`	Código postal
city	`string`	Ciudad
department	`string`	Departamento / Provincia
state	`string`	Estado
country	`string`	País
document_type	`string`	Tipo de documento
marital_status	`enum`	Valores: "single", "commited", "married", "divorced", "widowed".
tags	`string`	Etiquetas separadas por coma. Ejemplo: "tag1,tag2,tag3"
points	`integer`	Puntos totales del cliente
mailing_enabled	`enum`	Habilitado para envío de emails. Valores: "enabled", "disabled".
mailing_disabled_reason	`enum`	Razón por la que no está habilitado. Valores: "bounce", "unsubscribe", "spamreport", "dropped", "other".
whatsapp_enabled	`string`	Habilitado para envío de Whatsapp. Valores: "enabled", "disabled".
whatsapp_disabled_reason	`string`	Razón por la que no está habilitado. Valores: "bounce", "unsubscribe", "spamreport", "dropped", "other".
sms_enabled	`string`	Habilitado para envío de SMS. Valores: "enabled", "disabled".
sms_disabled_reason	`string`	Razón por la que no está habilitado. Valores: "bounce", "unsubscribe", "spamreport", "dropped", "other".
club_inscription_date	`string`
custom_attributes	`array`	Par clave-valor con información adicional del usuario. La definición de estos atributos debe ser creada previamente

3.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.
service_uid: Identificador único asignado al cliente por un servicio externo (opcional).

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.

3.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/multiusers \ 
--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"
}

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

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

3.4 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"
}

3.5 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" 
  }