API pública — Clientes (customerClients)

Miguel Gómez Pérez · Equipo Bukyapp· 4 min de lectura·Actualizado 21 may 2026

Consulta las fichas de cliente de tu cuenta mediante la API pública de Buky para acceder a contacto, etiquetas y preferencias de quienes han reservado contigo

Esta página explica cómo consultar las fichas de cliente de tu cuenta mediante la API pública de Buky. Aquí están los datos de contacto, documentación, etiquetas y preferencias de las personas que han reservado contigo.

Antes de empezar

• Necesitas un API Token activo. Si aún no lo has creado, sigue la guía Conectar Buky con herramientas externas (API Tokens).
• El token es de solo lectura: puedes listar y consultar clientes, pero no crearlos ni modificarlos.
• La función está en fase beta. Si no ves la pestaña "API Tokens" en tu configuración, contacta con soporte.

Autenticación

El token se envía en cada petición de una de estas dos formas:

Opción 1 — Cabecera `auth` (recomendado):

curl "https://app.bukyapp.com/api/customerClients" \
  -H "auth: bk_TU_TOKEN"

Opción 2 — Parámetro `token` en la URL:

curl "https://app.bukyapp.com/api/customerClients?token=bk_TU_TOKEN"

Usa la cabecera siempre que puedas — las URLs suelen quedarse en logs y expuestas.

Listar clientes

curl "https://app.bukyapp.com/api/customerClients" \
  -H "auth: bk_TU_TOKEN"

La respuesta es un array JSON de fichas de cliente, ordenado por fecha de creación descendente por defecto (el más reciente primero):

[
  {
    "_id": "65f1a2b3c4d5e6f7a8b9c0d1",
    "name": "Laura",
    "surname": "García",
    "email": "laura@example.com",
    "phone": "+34 600 123 456",
    "dni": "12345678A",
    "birthday": "1992-03-15T00:00:00.000Z",
    "country": "ES",
    "city": "San Sebastián",
    "tags": ["vip", "surf"],
    "check_marketing": true,
    "origin": "booker",
    "createdAt": "2025-11-20T10:15:00.000Z",
    "customer": "5f0e1d2c3b4a5968778695a4"
  },
  ...
]

Paginación

En las cabeceras de la respuesta recibes el total de resultados y el número de páginas:

• X-Count: total de clientes que coinciden con el filtro.
• X-Page-Count: número de páginas.

Por defecto el endpoint devuelve como máximo 100 clientes por página. Para paginar:

curl "https://app.bukyapp.com/api/customerClients?page=1&limit=50" \
  -H "auth: bk_TU_TOKEN"

• limit: clientes por página (máximo 100).
• page: número de página, empezando en 1.

Filtrar clientes

El parámetro filter acepta un objeto JSON con sintaxis MongoDB. Envíalo codificado en la URL.

Por email

curl -G "https://app.bukyapp.com/api/customerClients" \
  -H "auth: bk_TU_TOKEN" \
  --data-urlencode 'filter={"email":"laura@example.com"}'

Por nombre o apellido (búsqueda parcial)

# Clientes cuyo nombre empieza por "Lau"
--data-urlencode 'filter={"name":{"$regex":"^Lau","$options":"i"}}'

# Buscar por apellido
--data-urlencode 'filter={"surname":{"$regex":"García","$options":"i"}}'

Clientes nuevos del último mes

curl -G "https://app.bukyapp.com/api/customerClients" \
  -H "auth: bk_TU_TOKEN" \
  --data-urlencode 'filter={"createdAt":{"$gte":"2026-03-20T00:00:00Z"}}'

Por etiqueta (tag)

# Clientes con la etiqueta "vip"
--data-urlencode 'filter={"tags":"vip"}'

# Clientes con varias etiquetas a la vez
--data-urlencode 'filter={"tags":{"$all":["vip","surf"]}}'

Por país o ciudad

--data-urlencode 'filter={"country":"ES"}'
--data-urlencode 'filter={"city":{"$regex":"San Sebastián","$options":"i"}}'

Por origen de la ficha

# Solo clientes que vinieron por el booker (tienda online)
--data-urlencode 'filter={"origin":"booker"}'

# Creados manualmente desde el backoffice
--data-urlencode 'filter={"origin":"manual"}'

Los valores posibles de origin son: manual, checkin, import, booker, migration.

Por consentimiento de marketing

# Clientes que aceptaron recibir comunicaciones comerciales
--data-urlencode 'filter={"check_marketing":true}'

Combinando filtros

Cualquier combinación funciona — se aplica como AND:

--data-urlencode 'filter={"country":"ES","tags":"vip","createdAt":{"$gte":"2026-01-01"}}'

Ordenar los resultados

Con sort, también en formato JSON:

# Más antiguos primero
--data-urlencode 'sort={"createdAt":1}'

# Alfabético por nombre
--data-urlencode 'sort={"name":1}'

# Por apellido descendente
--data-urlencode 'sort={"surname":-1}'

1 = ascendente, -1 = descendente.

Traer solo los campos que necesites

Con fields reduces el tamaño de la respuesta pidiendo solo las columnas que usas:

--data-urlencode 'fields={"name":1,"surname":1,"email":1,"phone":1,"tags":1,"createdAt":1}'

Útil cuando exportas miles de fichas y solo necesitas un resumen de contacto.

Expandir relaciones (populate)

Las referencias a otros recursos vienen como IDs. Para obtener el objeto completo en la misma respuesta:

curl -G "https://app.bukyapp.com/api/customerClients" \
  -H "auth: bk_TU_TOKEN" \
  --data-urlencode 'populate=customer'

Úsalo con moderación: expandir relaciones en consultas grandes puede hacer la respuesta muy pesada.

Consultar un cliente concreto

curl "https://app.bukyapp.com/api/customerClients/65f1a2b3c4d5e6f7a8b9c0d1" \
  -H "auth: bk_TU_TOKEN"

Devuelve la ficha completa del cliente.

Buscar por un campo alternativo

Si no tienes el _id pero sí el email, puedes usar getBy:

curl -G "https://app.bukyapp.com/api/customerClients/laura@example.com" \
  -H "auth: bk_TU_TOKEN" \
  --data-urlencode 'getBy=email'

Listar etiquetas disponibles

Este endpoint devuelve todas las etiquetas (tags) que existen en las fichas de tus clientes:

curl "https://app.bukyapp.com/api/customerClients/tags" \
  -H "auth: bk_TU_TOKEN"

Respuesta:

["vip", "surf", "regular", "student"]

Útil para construir filtros dinámicos en tu integración.

Campos útiles del objeto CustomerClient

Un CustomerClient tiene algunos campos más (formularios de checkin, códigos de acceso…). Usa fields para traer solo los que necesites.

Consejos

• Filtra siempre. Sin filter obtienes todas las fichas paginadas, pero si tienes miles de clientes, añade al menos un rango de createdAt o un filtro por tags para reducir resultados.
• Usa `fields` en exportaciones masivas. Si solo necesitas nombre y email para una newsletter, no pidas la ficha completa. Ahorras ancho de banda y tiempo de respuesta.
• Cuidado con los datos personales. Email, teléfono, DNI y dirección son datos protegidos por el RGPD. No los almacenes más tiempo del necesario y limita el acceso en tus sistemas.
• Sincronización incremental. Guarda el último createdAt procesado y pide solo fichas posteriores. Evitas reprocesar todo cada vez.
• Las etiquetas son libres. No hay un catálogo cerrado — cada cuenta define las suyas. Usa el endpoint /tags para descubrir las que existen.

Preguntas frecuentes

¿Puedo crear o modificar clientes por la API?

No. Los API Tokens son de solo lectura. Sirven para consultar datos, no para modificarlos.

¿Qué pasa con los clientes eliminados?

Por defecto no aparecen en los listados. Si necesitas incluirlos, añade includeDeleted=true como parámetro. Las fichas eliminadas tienen el campo isDeleted con la fecha de borrado.

¿Puedo buscar un cliente por email sin saber su ID?

Sí, de dos formas: con filter={"email":"laura@example.com"} (devuelve un array) o con getBy=email en la URL del cliente concreto (devuelve un objeto).

¿Qué son los `customFields`?

Son campos adicionales que cada cuenta puede definir libremente. Su estructura varía según la configuración de tu cuenta, así que no tienen un esquema fijo. Si los usas en tu integración, consulta primero qué campos has configurado en Buky.