API de Integración

Introducción

La API externa de Dockely expone los datos de tu instancia bajo el prefijo /api/ext/. Es independiente del API interna (que usa JWT para la app móvil) y se autentica exclusivamente con API keys generadas desde el panel de control.

✓

Las claves se gestionan desde hub.dockely.com → tu proyecto → API de integración. Máximo 3 claves activas. Cada clave se muestra solo una vez al crearla.

⚠

La API respeta los límites de usuarios de tu plan. No es posible crear más usuarios de los permitidos aunque se use la API.

Autenticación

Incluye tu API key en cada petición usando el header X-API-Key o como Bearer token en Authorization.

Header recomendado

X-API-Key: dky_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Alternativa Bearer

Authorization: Bearer dky_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Ejemplo completo con curl

# Sustituye <slug> y <tu-clave> por los valores reales
curl -s \
  -H "X-API-Key: dky_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://<slug>.dockely.com/api/ext/users"

ℹ

Si la clave es inválida o ha sido revocada recibirás un 401. Si el proyecto no tiene API activa recibirás un 500 (error de configuración).

URL base

Cada instancia tiene su propia URL base. Si tienes dominio propio configurado, úsalo en lugar del subdominio de Dockely.

Subdominio https://<slug>.dockely.com

Dominio propio https://<tu-dominio.com>

Todos los endpoints se añaden a esta URL base. Por ejemplo: https://mygym.dockely.com/api/ext/users

Errores

La API devuelve errores en JSON con el campo msg.

Código	Significado
200	OK — operación correcta
201	Creado — recurso creado correctamente
400	Datos incorrectos o campos obligatorios faltantes
401	API key no proporcionada o inválida
403	Límite de plan alcanzado (ej. máximo de usuarios)
404	Recurso no encontrado
409	Conflicto — por ejemplo email ya registrado
500	Error interno o de configuración del servidor

Ejemplo de error

{
  "msg": "Límite de usuarios alcanzado (50). Actualiza tu plan."
}

Paginación

Todos los endpoints de listado aceptan los parámetros page y limit.

Parámetro	Tipo	Default	Máximo	Descripción
page	integer	1	—	Número de página (empieza en 1)
limit	integer	100	500	Resultados por página

GET /api/ext/users?page=2&limit=50

Usuarios

Gestión completa del directorio de usuarios de la app. El campo is_admin=false corresponde a clientes/socios. Las altas respetan el límite de usuarios del plan contratado.

Listar usuarios

GET /api/ext/users Lista todos los usuarios con paginación y búsqueda opcional

Query params

Param		Tipo	Descripción
q	opt	string	Busca por nombre, apellidos o email
page	opt	integer	Página (default 1)
limit	opt	integer	Resultados por página (max 500, default 100)

Ejemplo

curl -H "X-API-Key: dky_..." \
  "https://<slug>.dockely.com/api/ext/users?q=juan&limit=20"

Respuesta

[
  {
    "id":         1,
    "email":      "juan@ejemplo.com",
    "name":       "Juan",
    "apellidos":  "García",
    "phone":      "+34 600 000 000",
    "is_admin":   false,
    "is_active":  true,
    "created_at": "2024-03-01T10:00:00"
  }
]

Obtener usuario

GET /api/ext/users/{id} Devuelve los datos de un usuario por su ID

curl -H "X-API-Key: dky_..." \
  "https://<slug>.dockely.com/api/ext/users/42"

Crear usuario

POST /api/ext/users Crea un nuevo usuario. Respeta el límite de usuarios del plan

Body (JSON)

Campo		Tipo	Descripción
email	req	string	Email único del usuario
name	req	string	Nombre
apellidos	opt	string	Apellidos
phone	opt	string	Teléfono
password	opt	string	Si no se envía, se genera una aleatoria y se devuelve en `_generated_password`
is_admin	opt	boolean	Si es administrador de la app (default `false`)

Ejemplo

curl -X POST \
  -H "X-API-Key: dky_..." \
  -H "Content-Type: application/json" \
  -d '{"email":"maria@ejemplo.com","name":"María","apellidos":"López"}' \
  "https://<slug>.dockely.com/api/ext/users"

Respuesta 201

{
  "id":                   55,
  "email":               "maria@ejemplo.com",
  "name":                "María",
  "apellidos":           "López",
  "is_admin":            false,
  "_generated_password": "Xk9mP2qr..."  // solo si no se envió password
}

Actualizar usuario

PATCH /api/ext/users/{id} Actualiza uno o más campos del usuario

Body (JSON) — todos opcionales

Campo	Tipo	Descripción
name	string	Nombre
apellidos	string	Apellidos
phone	string	Teléfono
email	string	Nuevo email
password	string	Nueva contraseña (se hashea)
is_admin	boolean	Rol de administrador

curl -X PATCH \
  -H "X-API-Key: dky_..." \
  -H "Content-Type: application/json" \
  -d '{"phone":"+34 611 000 000"}' \
  "https://<slug>.dockely.com/api/ext/users/55"

Eliminar usuario

DELETE /api/ext/users/{id} Elimina permanentemente un usuario

curl -X DELETE \
  -H "X-API-Key: dky_..." \
  "https://<slug>.dockely.com/api/ext/users/55"

Respuesta

{ "ok": true }

Reservas / Citas

Acceso completo a la agenda de reservas. Disponible en los verticales que tengan el módulo de reservas activado (gym, salud, educación, etc.).

ℹ

Las fechas deben estar en formato ISO 8601: 2024-06-15T10:30:00. Los campos start_datetime y end_datetime son obligatorios al crear.

Listar reservas

GET /api/ext/bookings Lista reservas con filtros opcionales

Query params

Param		Tipo	Descripción
user_id	opt	integer	Filtra por usuario
status	opt	string	`confirmed`, `cancelled`, `pending`
page	opt	integer	Página
limit	opt	integer	Resultados por página (max 500)

curl -H "X-API-Key: dky_..." \
  "https://<slug>.dockely.com/api/ext/bookings?status=confirmed&user_id=42"

Obtener reserva

GET /api/ext/bookings/{id} Devuelve detalle completo incluyendo usuario, tipo y calendario

curl -H "X-API-Key: dky_..." \
  "https://<slug>.dockely.com/api/ext/bookings/101"

Respuesta

{
  "id":                   101,
  "user_id":              42,
  "appointment_type_id":  3,
  "calendar_id":          1,
  "start_datetime":       "2024-06-15T10:00:00",
  "end_datetime":         "2024-06-15T11:00:00",
  "status":               "confirmed",
  "admin_notes":          ""
}

Crear reserva

POST /api/ext/bookings Crea una nueva reserva en la agenda

Body (JSON)

Campo		Tipo	Descripción
user_id	req	integer	ID del usuario
appointment_type_id	req	integer	ID del tipo de cita/servicio
start_datetime	req	string	ISO 8601 — inicio
end_datetime	req	string	ISO 8601 — fin
calendar_id	opt	integer	ID del calendario/profesional
status	opt	string	Default `confirmed`
admin_notes	opt	string	Notas internas

curl -X POST \
  -H "X-API-Key: dky_..." \
  -H "Content-Type: application/json" \
  -d '{"user_id":42,"appointment_type_id":3,"start_datetime":"2024-06-15T10:00:00","end_datetime":"2024-06-15T11:00:00"}' \
  "https://<slug>.dockely.com/api/ext/bookings"

Actualizar reserva

PATCH /api/ext/bookings/{id} Modifica estado, horario o notas de una reserva

curl -X PATCH \
  -H "X-API-Key: dky_..." \
  -H "Content-Type: application/json" \
  -d '{"status":"cancelled"}' \
  "https://<slug>.dockely.com/api/ext/bookings/101"

Eliminar reserva

DELETE /api/ext/bookings/{id} Elimina una reserva permanentemente

curl -X DELETE \
  -H "X-API-Key: dky_..." \
  "https://<slug>.dockely.com/api/ext/bookings/101"

Pagos y membresías

Consulta del historial de pagos, suscripciones activas y catálogo de planes. Todos los endpoints son de solo lectura.

Listar pagos

GET /api/ext/pagos Historial de pagos/transacciones

Query params

Param		Tipo	Descripción
user_id	opt	integer	Filtra por usuario
page / limit	opt	integer	Paginación

curl -H "X-API-Key: dky_..." \
  "https://<slug>.dockely.com/api/ext/pagos?user_id=42"

Listar suscripciones

GET /api/ext/suscripciones Suscripciones activas de membresía

curl -H "X-API-Key: dky_..." \
  "https://<slug>.dockely.com/api/ext/suscripciones"

Listar planes

GET /api/ext/planes Catálogo de planes de membresía activos

curl -H "X-API-Key: dky_..." \
  "https://<slug>.dockely.com/api/ext/planes"

Calendario

Eventos del calendario interno de la app.

Listar eventos

GET /api/ext/calendar Lista eventos del calendario con paginación

curl -H "X-API-Key: dky_..." \
  "https://<slug>.dockely.com/api/ext/calendar?limit=50"