API de integración
Referencia de la API
34 operaciones sobre /api/integration/v1, agrupadas por recurso. Cada una incluye sus parámetros, el esquema de la respuesta, ejemplos listos para copiar y un botón para enviarla con tu clave. Los conceptos comunes (autenticación, paginación, sincronización, errores) están en la guía de la API.
Versión 1.0.0 · openapi.yaml (OpenAPI 3.1, importable en Postman, Insomnia o cualquier generador de clientes).
Probar con tu clave de API
Pega una clave de tu cadena y cada operación tendrá un botón Enviar que llama a /api/integration/v1. La clave no sale de tu navegador salvo hacia esa URL.
Organización
Gym (cadena) y clubs (sedes).
Datos de la cadena dueña de la clave
Respuestas
200Gym
Gym de la clave.
- idstring
- namestring
- timezonestring
Zona horaria IANA. Todas las fechas sin hora se interpretan en ella.
p. ej. "Europe/Madrid"
- clubCountinteger
401Error
Falta la clave, no es válida o está revocada.
- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
curl -X GET '/api/integration/v1/gym' \
-H 'Authorization: Bearer opt_live_…'{
"id": "cm3id00000001",
"name": "Lucía Martín",
"timezone": "Europe/Madrid",
"clubCount": 3
}Lista los clubs del gym
Permiso:clubs:read
Si la clave está restringida a ciertos clubs, solo devuelve esos.
Parámetros de consulta
- limitinteger
por defecto 100 · 1–500
- cursorstring
Valor
nextCursorde la página anterior. Opaco. - updatedSincestring · date-time
Solo registros creados o modificados en ese instante o después. Con este filtro el orden es
(updatedAt, id)ascendente, para que la sincronización incremental no se salte filas. - activeboolean
Respuestas
200
Página de clubs.
- array<Club>
- nextCursorstring | nullobligatorio
nullcuando no hay más páginas.
401Error
Falta la clave, no es válida o está revocada.
- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
403Error
La clave no tiene el permiso o el club necesarios.
- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
curl -X GET '/api/integration/v1/clubs' \
-H 'Authorization: Bearer opt_live_…'{
"data": [
{
"id": "cm3id00000001",
"slug": "centro",
"name": "Lucía Martín",
"active": true,
"address": "Calle Mayor, 1",
"city": "Pamplona",
"phone": "+34 600 000 000",
"email": "lucia.martin@ejemplo.com",
"nightShiftStart": "07:00",
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z"
}
],
"nextCursor": null
}Detalle de un club
Permiso:clubs:read
Parámetros de ruta
- clubIdstringobligatorio
Respuestas
200Club
Club.
- idstring
- slugstring
- namestring
- activeboolean
- addressstring | null
- citystring | null
- phonestring | null
- emailstring | null
- nightShiftStartstring
Hora de pared en la zona del gym, 24 h.
patrón ^([01][0-9]|2[0-3]):[0-5][0-9]$ · p. ej. "07:00", "21:30"
- createdAtstring · date-time
- updatedAtstring · date-time
404Error
No existe o no pertenece a la cadena de la clave.
- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
curl -X GET '/api/integration/v1/clubs/{clubId}' \
-H 'Authorization: Bearer opt_live_…'{
"id": "cm3id00000001",
"slug": "centro",
"name": "Lucía Martín",
"active": true,
"address": "Calle Mayor, 1",
"city": "Pamplona",
"phone": "+34 600 000 000",
"email": "lucia.martin@ejemplo.com",
"nightShiftStart": "07:00",
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z"
}Catálogo
Salas y tipos de clase de cada club.
Salas del club
Permiso:catalog:read
Parámetros de ruta
- clubIdstringobligatorio
Parámetros de consulta
- limitinteger
por defecto 100 · 1–500
- cursorstring
Valor
nextCursorde la página anterior. Opaco. - updatedSincestring · date-time
Solo registros creados o modificados en ese instante o después. Con este filtro el orden es
(updatedAt, id)ascendente, para que la sincronización incremental no se salte filas.
Respuestas
200
Página de salas.
- array<Room>
- nextCursorstring | nullobligatorio
nullcuando no hay más páginas.
curl -X GET '/api/integration/v1/clubs/{clubId}/rooms' \
-H 'Authorization: Bearer opt_live_…'{
"data": [
{
"id": "cm3id00000001",
"clubId": "cm3club000001",
"name": "Lucía Martín",
"color": "#6366f1",
"isActive": true,
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z"
}
],
"nextCursor": null
}Crea una sala
Permiso:catalog:write
Parámetros de ruta
- clubIdstringobligatorio
Cabeceras
- Idempotency-Keystring
Identificador único de la operación (por ejemplo, un UUID). Reenviar la misma petición con la misma clave en las 24 h siguientes devuelve la respuesta original (cabecera
Idempotent-Replayed: true) sin repetir la escritura. Reutilizarla con otro cuerpo responde422.máx. 255 caracteres
Cuerpo de la petición application/jsonRoomInput
- namestringobligatorio
máx. 100 caracteres
- colorstring
patrón ^#[0-9a-fA-F]{6}$
Respuestas
201Room
Sala creada.
- idstring
- clubIdstring
- namestring
- colorstring
p. ej. "#6366f1"
- isActiveboolean
- createdAtstring · date-time
- updatedAtstring · date-time
409Error
Choca con el estado actual (duplicado, solape, versión congelada…).
- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
422Error
Datos no válidos.
detailsindica el campo.- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
curl -X POST '/api/integration/v1/clubs/{clubId}/rooms' \
-H 'Authorization: Bearer opt_live_…' \
-H 'Content-Type: application/json' \
-d '{
"name": "Lucía Martín"
}'{
"id": "cm3id00000001",
"clubId": "cm3club000001",
"name": "Lucía Martín",
"color": "#6366f1",
"isActive": true,
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z"
}Modifica una sala
Permiso:catalog:write
Para dar de baja una sala se envía isActive=false. La API no borra salas.
Parámetros de ruta
- clubIdstringobligatorio
- roomIdstringobligatorio
Cuerpo de la petición application/jsonRoomPatch
- namestring
máx. 100 caracteres
- colorstring
patrón ^#[0-9a-fA-F]{6}$
- isActiveboolean
Respuestas
200Room
Sala modificada.
- idstring
- clubIdstring
- namestring
- colorstring
p. ej. "#6366f1"
- isActiveboolean
- createdAtstring · date-time
- updatedAtstring · date-time
404Error
No existe o no pertenece a la cadena de la clave.
- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
422Error
Datos no válidos.
detailsindica el campo.- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
curl -X PATCH '/api/integration/v1/clubs/{clubId}/rooms/{roomId}' \
-H 'Authorization: Bearer opt_live_…' \
-H 'Content-Type: application/json' \
-d '{}'{
"id": "cm3id00000001",
"clubId": "cm3club000001",
"name": "Lucía Martín",
"color": "#6366f1",
"isActive": true,
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z"
}Tipos de clase del club
Permiso:catalog:read
Parámetros de ruta
- clubIdstringobligatorio
Parámetros de consulta
- limitinteger
por defecto 100 · 1–500
- cursorstring
Valor
nextCursorde la página anterior. Opaco. - updatedSincestring · date-time
Solo registros creados o modificados en ese instante o después. Con este filtro el orden es
(updatedAt, id)ascendente, para que la sincronización incremental no se salte filas.
Respuestas
200
Página de tipos de clase.
- array<ClassType>
- nextCursorstring | nullobligatorio
nullcuando no hay más páginas.
curl -X GET '/api/integration/v1/clubs/{clubId}/class-types' \
-H 'Authorization: Bearer opt_live_…'{
"data": [
{
"id": "cm3id00000001",
"clubId": "cm3club000001",
"name": "Spinning",
"durationMinutes": 45,
"defaultRoomId": "cm3defaul0001",
"color": "#6366f1",
"description": "Texto libre",
"isActive": true,
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z"
}
],
"nextCursor": null
}Crea un tipo de clase
Permiso:catalog:write
Parámetros de ruta
- clubIdstringobligatorio
Cabeceras
- Idempotency-Keystring
Identificador único de la operación (por ejemplo, un UUID). Reenviar la misma petición con la misma clave en las 24 h siguientes devuelve la respuesta original (cabecera
Idempotent-Replayed: true) sin repetir la escritura. Reutilizarla con otro cuerpo responde422.máx. 255 caracteres
Cuerpo de la petición application/jsonClassTypeInput
- namestringobligatorio
máx. 100 caracteres
- durationMinutesintegerobligatorio
5–480
- defaultRoomIdstring | null
- colorstring
patrón ^#[0-9a-fA-F]{6}$
- descriptionstring | null
máx. 500 caracteres
Respuestas
201ClassType
Tipo de clase creado.
- idstring
- clubIdstring
- namestring
p. ej. "Spinning"
- durationMinutesinteger
p. ej. 45
- defaultRoomIdstring | null
- colorstring
- descriptionstring | null
- isActiveboolean
- createdAtstring · date-time
- updatedAtstring · date-time
409Error
Choca con el estado actual (duplicado, solape, versión congelada…).
- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
422Error
Datos no válidos.
detailsindica el campo.- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
curl -X POST '/api/integration/v1/clubs/{clubId}/class-types' \
-H 'Authorization: Bearer opt_live_…' \
-H 'Content-Type: application/json' \
-d '{
"name": "Lucía Martín",
"durationMinutes": 45
}'{
"id": "cm3id00000001",
"clubId": "cm3club000001",
"name": "Spinning",
"durationMinutes": 45,
"defaultRoomId": "cm3defaul0001",
"color": "#6366f1",
"description": "Texto libre",
"isActive": true,
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z"
}Modifica un tipo de clase
Permiso:catalog:write
Para dar de baja un tipo de clase se envía isActive=false. La API no los borra.
Parámetros de ruta
- clubIdstringobligatorio
- classTypeIdstringobligatorio
Cuerpo de la petición application/jsonClassTypePatch
- namestring
máx. 100 caracteres
- durationMinutesinteger
5–480
- defaultRoomIdstring | null
- colorstring
patrón ^#[0-9a-fA-F]{6}$
- descriptionstring | null
máx. 500 caracteres
- isActiveboolean
Respuestas
200ClassType
Tipo de clase modificado.
- idstring
- clubIdstring
- namestring
p. ej. "Spinning"
- durationMinutesinteger
p. ej. 45
- defaultRoomIdstring | null
- colorstring
- descriptionstring | null
- isActiveboolean
- createdAtstring · date-time
- updatedAtstring · date-time
404Error
No existe o no pertenece a la cadena de la clave.
- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
422Error
Datos no válidos.
detailsindica el campo.- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
curl -X PATCH '/api/integration/v1/clubs/{clubId}/class-types/{classTypeId}' \
-H 'Authorization: Bearer opt_live_…' \
-H 'Content-Type: application/json' \
-d '{}'{
"id": "cm3id00000001",
"clubId": "cm3club000001",
"name": "Spinning",
"durationMinutes": 45,
"defaultRoomId": "cm3defaul0001",
"color": "#6366f1",
"description": "Texto libre",
"isActive": true,
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z"
}Monitores
Fichas de empleado, especialidades, disponibilidad y contratos versionados.
Lista los monitores
Permiso:instructors:read
Una ficha de monitor pertenece a un solo club. Un empleado que trabaja en dos clubs
tiene dos fichas; ambas pueden llevar el mismo externalId.
Parámetros de consulta
- limitinteger
por defecto 100 · 1–500
- cursorstring
Valor
nextCursorde la página anterior. Opaco. - updatedSincestring · date-time
Solo registros creados o modificados en ese instante o después. Con este filtro el orden es
(updatedAt, id)ascendente, para que la sincronización incremental no se salte filas. - clubIdstring
Filtra por club. Sin él, todos los clubs a los que llega la clave.
- activeboolean
- externalIdstring
Busca por el identificador del empleado en el sistema externo.
- emailstring · email
Respuestas
200
Página de monitores.
- array<Instructor>
- nextCursorstring | nullobligatorio
nullcuando no hay más páginas.
curl -X GET '/api/integration/v1/instructors' \
-H 'Authorization: Bearer opt_live_…'{
"data": [
{
"id": "cm3id00000001",
"clubId": "cm3club000001",
"externalId": "cm3extern0001",
"name": "Lucía Martín",
"email": "lucia.martin@ejemplo.com",
"phone": "+34 600 000 000",
"isActive": true,
"canDoReception": true,
"vacationDays": 23,
"appAccess": "none",
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z"
}
],
"nextCursor": null
}Da de alta un monitor
Permiso:instructors:write
Caso típico: el sistema de personal da de alta a un empleado y lo crea en Optime. Si ya existe una ficha
con el mismo externalId en el club, responde 409 DUPLICATE_EXTERNAL_ID con el id de
la ficha existente. El contrato inicial es opcional; si se envía, entra en vigor en
contract.effectiveFrom.
Cabeceras
- Idempotency-Keystring
Identificador único de la operación (por ejemplo, un UUID). Reenviar la misma petición con la misma clave en las 24 h siguientes devuelve la respuesta original (cabecera
Idempotent-Replayed: true) sin repetir la escritura. Reutilizarla con otro cuerpo responde422.máx. 255 caracteres
Cuerpo de la petición application/jsonInstructorInput
- clubIdstringobligatorio
- externalIdstring
máx. 100 caracteres
- namestringobligatorio
máx. 200 caracteres
- emailstring · emailobligatorio
- phonestring
- canDoReceptionboolean
por defecto false
- vacationDaysinteger
por defecto 23 · ≥ 0
- specialtyClassTypeIdsarray<string>
- array<AvailabilitySlot>
- object (ContractInput)
- sendAppInviteboolean
Envía por email la invitación a la app de monitores.
por defecto false
Respuestas
201
Monitor creado. Con
sendAppInvite=trueincluyeappInvite: si el email no se pudo enviar, la ficha existe igualmente yappInvite.sentesfalse(el manager puede reenviar la invitación desde la web).- idstring
- clubIdstring
- externalIdstring | null
Identificador del empleado en el sistema externo. Lo escribe ese sistema; Optime no lo interpreta.
- namestring
- emailstring · email
- phonestring | null
- isActiveboolean
- canDoReceptionboolean
- vacationDaysinteger
Días de vacaciones anuales.
- appAccessenum
Si el monitor tiene la app vinculada a su ficha.
noneinvitedlinked - createdAtstring · date-time
- updatedAtstring · date-time
- object
409Error
Choca con el estado actual (duplicado, solape, versión congelada…).
- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
422Error
Datos no válidos.
detailsindica el campo.- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
curl -X POST '/api/integration/v1/instructors' \
-H 'Authorization: Bearer opt_live_…' \
-H 'Content-Type: application/json' \
-d '{
"clubId": "cm3club000001",
"name": "Lucía Martín",
"email": "lucia.martin@ejemplo.com"
}'{
"id": "cm3id00000001",
"clubId": "cm3club000001",
"externalId": "cm3extern0001",
"name": "Lucía Martín",
"email": "lucia.martin@ejemplo.com",
"phone": "+34 600 000 000",
"isActive": true,
"canDoReception": true,
"vacationDays": 23,
"appAccess": "none",
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z",
"appInvite": {
"sent": true,
"error": "texto"
}
}Detalle de un monitor
Permiso:instructors:read
Incluye especialidades, disponibilidad semanal y contrato vigente.
Parámetros de ruta
- instructorIdstringobligatorio
Respuestas
200InstructorDetail
Monitor.
- idstring
- clubIdstring
- externalIdstring | null
Identificador del empleado en el sistema externo. Lo escribe ese sistema; Optime no lo interpreta.
- namestring
- emailstring · email
- phonestring | null
- isActiveboolean
- canDoReceptionboolean
- vacationDaysinteger
Días de vacaciones anuales.
- appAccessenum
Si el monitor tiene la app vinculada a su ficha.
noneinvitedlinked - createdAtstring · date-time
- updatedAtstring · date-time
- array<object>
Tipos de clase que puede impartir.
- array<AvailabilitySlot>
Vacía = disponible siempre.
- object (Contract) | null
- object (Contract) | null
404Error
No existe o no pertenece a la cadena de la clave.
- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
curl -X GET '/api/integration/v1/instructors/{instructorId}' \
-H 'Authorization: Bearer opt_live_…'{
"id": "cm3id00000001",
"clubId": "cm3club000001",
"externalId": "cm3extern0001",
"name": "Lucía Martín",
"email": "lucia.martin@ejemplo.com",
"phone": "+34 600 000 000",
"isActive": true,
"canDoReception": true,
"vacationDays": 23,
"appAccess": "none",
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z",
"specialties": [
{
"classTypeId": "cm3classt0001",
"name": "Lucía Martín"
}
],
"availability": [
{
"dayOfWeek": 0,
"startTime": "07:00",
"endTime": "07:00"
}
],
"currentContract": {
"id": "cm3id00000001",
"instructorId": "cm3instru0001",
"effectiveFrom": "2026-10-22",
"effectiveTo": null,
"days": [
{
"dayOfWeek": 0,
"reception": 4,
"class1h": 4,
"class30min": 4,
"manager": 4,
"reinforcement": 4
}
],
"weeklyTotals": {
"reception": 4,
"class1h": 4,
"class30min": 4,
"manager": 4,
"reinforcement": 4,
"total": 4
},
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z"
},
"futureContract": null
}Modifica los datos del monitor
Permiso:instructors:write
Para la baja del empleado se envía isActive=false: deja de aparecer en el horario
futuro y conserva su histórico (fichajes, nóminas). Si tenía acceso a la app como monitor,
lo pierde en ese momento (para volver, se le reinvita). Sus turnos ya planificados no se
borran: hay que reasignarlos. La API no borra fichas: los fichajes se conservan 4 años por
ley. Cambiar el email anula la invitación a la app pendiente.
Parámetros de ruta
- instructorIdstringobligatorio
Cuerpo de la petición application/jsonInstructorPatch
- externalIdstring | null
máx. 100 caracteres
- namestring
máx. 200 caracteres
- emailstring · email
- phonestring | null
- canDoReceptionboolean
- vacationDaysinteger
≥ 0
- isActiveboolean
false= baja del empleado.
Respuestas
200Instructor
Monitor modificado.
- idstring
- clubIdstring
- externalIdstring | null
Identificador del empleado en el sistema externo. Lo escribe ese sistema; Optime no lo interpreta.
- namestring
- emailstring · email
- phonestring | null
- isActiveboolean
- canDoReceptionboolean
- vacationDaysinteger
Días de vacaciones anuales.
- appAccessenum
Si el monitor tiene la app vinculada a su ficha.
noneinvitedlinked - createdAtstring · date-time
- updatedAtstring · date-time
404Error
No existe o no pertenece a la cadena de la clave.
- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
422Error
Datos no válidos.
detailsindica el campo.- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
curl -X PATCH '/api/integration/v1/instructors/{instructorId}' \
-H 'Authorization: Bearer opt_live_…' \
-H 'Content-Type: application/json' \
-d '{}'{
"id": "cm3id00000001",
"clubId": "cm3club000001",
"externalId": "cm3extern0001",
"name": "Lucía Martín",
"email": "lucia.martin@ejemplo.com",
"phone": "+34 600 000 000",
"isActive": true,
"canDoReception": true,
"vacationDays": 23,
"appAccess": "none",
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z"
}Sustituye las especialidades del monitor
Permiso:instructors:write
Lista completa de tipos de clase que puede impartir (reemplazo total).
Parámetros de ruta
- instructorIdstringobligatorio
Cuerpo de la petición application/json
- classTypeIdsarray<string>obligatorio
Respuestas
200InstructorDetail
Especialidades guardadas.
- idstring
- clubIdstring
- externalIdstring | null
Identificador del empleado en el sistema externo. Lo escribe ese sistema; Optime no lo interpreta.
- namestring
- emailstring · email
- phonestring | null
- isActiveboolean
- canDoReceptionboolean
- vacationDaysinteger
Días de vacaciones anuales.
- appAccessenum
Si el monitor tiene la app vinculada a su ficha.
noneinvitedlinked - createdAtstring · date-time
- updatedAtstring · date-time
- array<object>
Tipos de clase que puede impartir.
- array<AvailabilitySlot>
Vacía = disponible siempre.
- object (Contract) | null
- object (Contract) | null
422Error
Datos no válidos.
detailsindica el campo.- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
curl -X PUT '/api/integration/v1/instructors/{instructorId}/specialties' \
-H 'Authorization: Bearer opt_live_…' \
-H 'Content-Type: application/json' \
-d '{
"classTypeIds": [
"cm3classt0001"
]
}'{
"id": "cm3id00000001",
"clubId": "cm3club000001",
"externalId": "cm3extern0001",
"name": "Lucía Martín",
"email": "lucia.martin@ejemplo.com",
"phone": "+34 600 000 000",
"isActive": true,
"canDoReception": true,
"vacationDays": 23,
"appAccess": "none",
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z",
"specialties": [
{
"classTypeId": "cm3classt0001",
"name": "Lucía Martín"
}
],
"availability": [
{
"dayOfWeek": 0,
"startTime": "07:00",
"endTime": "07:00"
}
],
"currentContract": {
"id": "cm3id00000001",
"instructorId": "cm3instru0001",
"effectiveFrom": "2026-10-22",
"effectiveTo": null,
"days": [
{
"dayOfWeek": 0,
"reception": 4,
"class1h": 4,
"class30min": 4,
"manager": 4,
"reinforcement": 4
}
],
"weeklyTotals": {
"reception": 4,
"class1h": 4,
"class30min": 4,
"manager": 4,
"reinforcement": 4,
"total": 4
},
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z"
},
"futureContract": null
}Sustituye la disponibilidad semanal
Permiso:instructors:write
Lista vacía = disponible siempre (valor por defecto). Con franjas, el monitor solo está disponible dentro de ellas y los días sin franja cuentan como "no disponible".
Parámetros de ruta
- instructorIdstringobligatorio
Cuerpo de la petición application/json
- array<AvailabilitySlot>obligatorio
Respuestas
200InstructorDetail
Disponibilidad guardada.
- idstring
- clubIdstring
- externalIdstring | null
Identificador del empleado en el sistema externo. Lo escribe ese sistema; Optime no lo interpreta.
- namestring
- emailstring · email
- phonestring | null
- isActiveboolean
- canDoReceptionboolean
- vacationDaysinteger
Días de vacaciones anuales.
- appAccessenum
Si el monitor tiene la app vinculada a su ficha.
noneinvitedlinked - createdAtstring · date-time
- updatedAtstring · date-time
- array<object>
Tipos de clase que puede impartir.
- array<AvailabilitySlot>
Vacía = disponible siempre.
- object (Contract) | null
- object (Contract) | null
422Error
Datos no válidos.
detailsindica el campo.- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
curl -X PUT '/api/integration/v1/instructors/{instructorId}/availability' \
-H 'Authorization: Bearer opt_live_…' \
-H 'Content-Type: application/json' \
-d '{
"slots": [
{
"dayOfWeek": 0,
"startTime": "07:00",
"endTime": "07:00"
}
]
}'{
"id": "cm3id00000001",
"clubId": "cm3club000001",
"externalId": "cm3extern0001",
"name": "Lucía Martín",
"email": "lucia.martin@ejemplo.com",
"phone": "+34 600 000 000",
"isActive": true,
"canDoReception": true,
"vacationDays": 23,
"appAccess": "none",
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z",
"specialties": [
{
"classTypeId": "cm3classt0001",
"name": "Lucía Martín"
}
],
"availability": [
{
"dayOfWeek": 0,
"startTime": "07:00",
"endTime": "07:00"
}
],
"currentContract": {
"id": "cm3id00000001",
"instructorId": "cm3instru0001",
"effectiveFrom": "2026-10-22",
"effectiveTo": null,
"days": [
{
"dayOfWeek": 0,
"reception": 4,
"class1h": 4,
"class30min": 4,
"manager": 4,
"reinforcement": 4
}
],
"weeklyTotals": {
"reception": 4,
"class1h": 4,
"class30min": 4,
"manager": 4,
"reinforcement": 4,
"total": 4
},
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z"
},
"futureContract": null
}Historial de contratos (versiones)
Permiso:instructors:read
Los contratos están versionados por fecha de entrada en vigor. La versión vigente en
una fecha es la de mayor effectiveFrom que no sea posterior a esa fecha. Puede haber
como mucho una versión futura.
Parámetros de ruta
- instructorIdstringobligatorio
Respuestas
200
Versiones, de la más reciente a la más antigua.
- array<Contract>
curl -X GET '/api/integration/v1/instructors/{instructorId}/contracts' \
-H 'Authorization: Bearer opt_live_…'{
"data": [
{
"id": "cm3id00000001",
"instructorId": "cm3instru0001",
"effectiveFrom": "2026-10-22",
"effectiveTo": null,
"days": [
{
"dayOfWeek": 0,
"reception": 4,
"class1h": 4,
"class30min": 4,
"manager": 4,
"reinforcement": 4
}
],
"weeklyTotals": {
"reception": 4,
"class1h": 4,
"class30min": 4,
"manager": 4,
"reinforcement": 4,
"total": 4
},
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z"
}
]
}Registra un cambio de contrato
Permiso:contracts:write
Crea una versión nueva que entra en vigor en effectiveFrom (hoy o una fecha futura).
Las horas anteriores se siguen calculando con la versión que estaba vigente. Si ya existe
una versión con esa misma fecha, se sustituyen sus horas. No se admiten fechas pasadas:
para corregir un error en la versión vigente, usar PUT …/contracts/{contractId}.
Parámetros de ruta
- instructorIdstringobligatorio
Cabeceras
- Idempotency-Keystring
Identificador único de la operación (por ejemplo, un UUID). Reenviar la misma petición con la misma clave en las 24 h siguientes devuelve la respuesta original (cabecera
Idempotent-Replayed: true) sin repetir la escritura. Reutilizarla con otro cuerpo responde422.máx. 255 caracteres
Cuerpo de la petición application/jsonContractInput
- effectiveFromstring · dateobligatorio
Hoy o una fecha futura.
- array<ContractDayHours>obligatorio
Un elemento por día de la semana; los días que falten cuentan como 0 h.
máx. 7 elementos
Respuestas
201Contract
Versión creada.
- idstring
- instructorIdstring
- effectiveFromstring · date
- effectiveTostring · date | null
Día anterior a la siguiente versión;
nullsi es la última. - array<ContractDayHours>
Un elemento por día de la semana; los días que falten cuentan como 0 h.
máx. 7 elementos
- object
- createdAtstring · date-time
- updatedAtstring · date-time
422Error
Datos no válidos.
detailsindica el campo.- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
curl -X POST '/api/integration/v1/instructors/{instructorId}/contracts' \
-H 'Authorization: Bearer opt_live_…' \
-H 'Content-Type: application/json' \
-d '{
"effectiveFrom": "2026-10-22",
"days": [
{}
]
}'{
"id": "cm3id00000001",
"instructorId": "cm3instru0001",
"effectiveFrom": "2026-10-22",
"effectiveTo": null,
"days": [
{
"dayOfWeek": 0,
"reception": 4,
"class1h": 4,
"class30min": 4,
"manager": 4,
"reinforcement": 4
}
],
"weeklyTotals": {
"reception": 4,
"class1h": 4,
"class30min": 4,
"manager": 4,
"reinforcement": 4,
"total": 4
},
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z"
}Corrige las horas de una versión vigente o futura
Permiso:contracts:write
Reescribe las horas por día de la versión sin cambiar su fecha. Afecta a todo el
periodo en que esa versión estuvo vigente, incluidos meses ya pasados que no tengan
nómina aprobada. Las nóminas aprobadas no cambian (están congeladas). Requiere reason;
queda en la auditoría con el antes y el después.
Parámetros de ruta
- instructorIdstringobligatorio
- contractIdstringobligatorio
Cuerpo de la petición application/json
- array<ContractDayHours>obligatorio
Un elemento por día de la semana; los días que falten cuentan como 0 h.
máx. 7 elementos
- reasonstringobligatorio
máx. 500 caracteres
Respuestas
200Contract
Versión corregida.
- idstring
- instructorIdstring
- effectiveFromstring · date
- effectiveTostring · date | null
Día anterior a la siguiente versión;
nullsi es la última. - array<ContractDayHours>
Un elemento por día de la semana; los días que falten cuentan como 0 h.
máx. 7 elementos
- object
- createdAtstring · date-time
- updatedAtstring · date-time
409Error
Choca con el estado actual (duplicado, solape, versión congelada…).
- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
422Error
Datos no válidos.
detailsindica el campo.- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
curl -X PUT '/api/integration/v1/instructors/{instructorId}/contracts/{contractId}' \
-H 'Authorization: Bearer opt_live_…' \
-H 'Content-Type: application/json' \
-d '{
"days": [
{}
],
"reason": "Corrección por error de registro"
}'{
"id": "cm3id00000001",
"instructorId": "cm3instru0001",
"effectiveFrom": "2026-10-22",
"effectiveTo": null,
"days": [
{
"dayOfWeek": 0,
"reception": 4,
"class1h": 4,
"class30min": 4,
"manager": 4,
"reinforcement": 4
}
],
"weeklyTotals": {
"reception": 4,
"class1h": 4,
"class30min": 4,
"manager": 4,
"reinforcement": 4,
"total": 4
},
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z"
}Horario
Horario resuelto por día (plantilla semanal + modificaciones puntuales) y festivos.
Horario resuelto por días
Permiso:schedule:read
Devuelve, para cada fecha del rango, el horario efectivo: la modificación puntual del día si existe y, si no, la plantilla vigente para esa fecha. Es lo que se ha trabajado (o se va a trabajar) según Optime, con las ausencias aprobadas ya aplicadas. Rango máximo: 62 días.
Parámetros de ruta
- clubIdstringobligatorio
Parámetros de consulta
- fromstring · dateobligatorio
- tostring · dateobligatorio
Inclusive.
- instructorIdstring
Devuelve solo las asignaciones de ese monitor (las clases se mantienen).
Respuestas
200
Días del rango, en orden.
- array<ScheduleDay>
422Error
Datos no válidos.
detailsindica el campo.- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
curl -X GET '/api/integration/v1/clubs/{clubId}/schedule' \
-H 'Authorization: Bearer opt_live_…'{
"data": [
{
"date": "2026-10-22",
"dayOfWeek": 0,
"source": "template",
"templateName": "Horario anual",
"isClosed": false,
"holiday": null,
"openTime": "09:00",
"closeTime": "21:00",
"notes": "Texto libre",
"etag": "W/\"8f3c2a\"",
"classes": [
{
"id": "cm3id00000001",
"classTypeId": "cm3classt0001",
"classTypeName": "Spinning",
"roomId": "cm3room000001",
"roomName": "Sala 1",
"startTime": "07:00",
"endTime": "07:00"
}
],
"assignments": [
{
"id": "cm3id00000001",
"instructorId": "cm3instru0001",
"instructorName": "Lucía Martín",
"role": "CLASS",
"startTime": "07:00",
"endTime": "07:00",
"classId": null,
"minutes": 60
}
],
"absentInstructorIds": [
"cm3absent0001"
]
}
]
}Sustituye el horario de un día concreto
Permiso:schedule:write
Guarda una modificación puntual del día (reemplazo completo: apertura, clases y asignaciones). Pasa por las mismas validaciones que la web y devuelve los avisos que genera el día (recepción sin cubrir, monitor ausente, solapes, horas de contrato…). Los monitores afectados reciben una notificación en la app. No se admiten fechas pasadas.
Con dryRun=true no guarda nada: solo valida y devuelve los avisos (y day tal como
está hoy, sin aplicar el cambio).
Parámetros de ruta
- clubIdstringobligatorio
- datestring · dateobligatorio
Parámetros de consulta
- dryRunboolean
por defecto false
Cabeceras
- If-Matchstring
etagdel día tal como se leyó. Si el día ha cambiado desde entonces (por ejemplo, lo ha tocado un manager), responde412en lugar de pisar el cambio.
Cuerpo de la petición application/jsonScheduleDayInput
- openTimestring
Hora de pared en la zona del gym, 24 h.
patrón ^([01][0-9]|2[0-3]):[0-5][0-9]$ · p. ej. "07:00", "21:30"
- closeTimestring
Hora de pared en la zona del gym, 24 h.
patrón ^([01][0-9]|2[0-3]):[0-5][0-9]$ · p. ej. "07:00", "21:30"
- notesstring
máx. 500 caracteres
- array<object>obligatorio
- array<object>obligatorio
Respuestas
200
Día guardado (o validado, con
dryRun).- object (ScheduleDay)
- array<ScheduleWarning>
- savedboolean
412Error
El recurso ha cambiado desde que se leyó (
If-Matchno coincide).- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
422Error
Datos no válidos.
detailsindica el campo.- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
curl -X PUT '/api/integration/v1/clubs/{clubId}/schedule/{date}' \
-H 'Authorization: Bearer opt_live_…' \
-H 'Content-Type: application/json' \
-d '{
"classes": [
{
"classTypeId": "cm3classt0001",
"roomId": "cm3room000001",
"startTime": "07:00",
"endTime": "07:00"
}
],
"assignments": [
{
"instructorId": "cm3instru0001",
"role": "CLASS",
"startTime": "07:00",
"endTime": "07:00"
}
]
}'{
"day": {
"date": "2026-10-22",
"dayOfWeek": 0,
"source": "template",
"templateName": "Horario anual",
"isClosed": false,
"holiday": null,
"openTime": "09:00",
"closeTime": "21:00",
"notes": "Texto libre",
"etag": "W/\"8f3c2a\"",
"classes": [
{
"id": "cm3id00000001",
"classTypeId": "cm3classt0001",
"classTypeName": "Spinning",
"roomId": "cm3room000001",
"roomName": "Sala 1",
"startTime": "07:00",
"endTime": "07:00"
}
],
"assignments": [
{
"id": "cm3id00000001",
"instructorId": "cm3instru0001",
"instructorName": "Lucía Martín",
"role": "CLASS",
"startTime": "07:00",
"endTime": "07:00",
"classId": null,
"minutes": 60
}
],
"absentInstructorIds": [
"cm3absent0001"
]
},
"warnings": [
{
"type": "reception_uncovered",
"severity": "error",
"message": "Mensaje legible",
"details": "texto"
}
],
"saved": true
}Devuelve el día a la plantilla
Permiso:schedule:write
Borra la modificación puntual; el día vuelve a resolverse desde la plantilla.
Parámetros de ruta
- clubIdstringobligatorio
- datestring · dateobligatorio
Respuestas
200
Día restablecido.
- object (ScheduleDay)
curl -X DELETE '/api/integration/v1/clubs/{clubId}/schedule/{date}' \
-H 'Authorization: Bearer opt_live_…'{
"day": {
"date": "2026-10-22",
"dayOfWeek": 0,
"source": "template",
"templateName": "Horario anual",
"isClosed": false,
"holiday": null,
"openTime": "09:00",
"closeTime": "21:00",
"notes": "Texto libre",
"etag": "W/\"8f3c2a\"",
"classes": [
{
"id": "cm3id00000001",
"classTypeId": "cm3classt0001",
"classTypeName": "Spinning",
"roomId": "cm3room000001",
"roomName": "Sala 1",
"startTime": "07:00",
"endTime": "07:00"
}
],
"assignments": [
{
"id": "cm3id00000001",
"instructorId": "cm3instru0001",
"instructorName": "Lucía Martín",
"role": "CLASS",
"startTime": "07:00",
"endTime": "07:00",
"classId": null,
"minutes": 60
}
],
"absentInstructorIds": [
"cm3absent0001"
]
}
}Festivos y cierres del club
Permiso:schedule:read
Parámetros de ruta
- clubIdstringobligatorio
Parámetros de consulta
- yearinteger
- updatedSincestring · date-time
Solo registros creados o modificados en ese instante o después. Con este filtro el orden es
(updatedAt, id)ascendente, para que la sincronización incremental no se salte filas.
Respuestas
200
Festivos.
- array<Holiday>
curl -X GET '/api/integration/v1/clubs/{clubId}/holidays' \
-H 'Authorization: Bearer opt_live_…'{
"data": [
{
"id": "cm3id00000001",
"name": "Lucía Martín",
"date": "2026-10-22",
"endDate": "2026-10-22",
"recurring": true,
"isReducedHours": true,
"openTime": "09:00",
"closeTime": "21:00",
"updatedAt": "2026-10-22T07:02:11Z"
}
]
}Ausencias
Vacaciones, bajas y permisos.
Lista ausencias
Permiso:absences:read
Por defecto devuelve todas las ausencias que se solapan con el rango, en cualquier
estado. Solo las APPROVED cuentan como ausencia real en horario y nómina.
Parámetros de consulta
- limitinteger
por defecto 100 · 1–500
- cursorstring
Valor
nextCursorde la página anterior. Opaco. - updatedSincestring · date-time
Solo registros creados o modificados en ese instante o después. Con este filtro el orden es
(updatedAt, id)ascendente, para que la sincronización incremental no se salte filas. - clubIdstring
Filtra por club. Sin él, todos los clubs a los que llega la clave.
- instructorIdstring
- fromstring · date
- tostring · date
- statusenum
PENDINGAPPROVEDREJECTED - typeenum
VACATIONSICK_LEAVEPERSONALOTHER
Respuestas
200
Página de ausencias.
- array<Absence>
- nextCursorstring | nullobligatorio
nullcuando no hay más páginas.
curl -X GET '/api/integration/v1/absences' \
-H 'Authorization: Bearer opt_live_…'{
"data": [
{
"id": "cm3id00000001",
"instructorId": "cm3instru0001",
"clubId": "cm3club000001",
"type": "VACATION",
"status": "PENDING",
"startDate": "2026-10-22",
"endDate": "2026-10-22",
"days": 1,
"notes": "Texto libre",
"origin": "app",
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z"
}
],
"nextCursor": null
}Registra una ausencia
Permiso:absences:write
Desde un sistema externo, una ausencia nace APPROVED (por ejemplo, una baja médica
registrada en personal). Se rechaza si se solapa con otra PENDING o APPROVED del mismo monitor. Si
el monitor tenía asignaciones en esos días, aparecen como aviso en el horario para que
el manager las cubra.
Cabeceras
- Idempotency-Keystring
Identificador único de la operación (por ejemplo, un UUID). Reenviar la misma petición con la misma clave en las 24 h siguientes devuelve la respuesta original (cabecera
Idempotent-Replayed: true) sin repetir la escritura. Reutilizarla con otro cuerpo responde422.máx. 255 caracteres
Cuerpo de la petición application/jsonAbsenceInput
- instructorIdstringobligatorio
- typeenumobligatorio
VACATIONSICK_LEAVEPERSONALOTHER - startDatestring · dateobligatorio
- endDatestring · dateobligatorio
- statusenum
APPROVEDPENDINGpor defecto "APPROVED"
- notesstring
máx. 300 caracteres
Respuestas
201Absence
Ausencia creada.
- idstring
- instructorIdstring
- clubIdstring
- typeenum
VACATIONSICK_LEAVEPERSONALOTHER - statusenum
PENDINGAPPROVEDREJECTED - startDatestring · date
- endDatestring · date
Inclusive.
- daysinteger
Días naturales del rango.
- notesstring | null
- originenum
appwebapi - createdAtstring · date-time
- updatedAtstring · date-time
409Error
Choca con el estado actual (duplicado, solape, versión congelada…).
- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
422Error
Datos no válidos.
detailsindica el campo.- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
curl -X POST '/api/integration/v1/absences' \
-H 'Authorization: Bearer opt_live_…' \
-H 'Content-Type: application/json' \
-d '{
"instructorId": "cm3instru0001",
"type": "VACATION",
"startDate": "2026-10-22",
"endDate": "2026-10-22"
}'{
"id": "cm3id00000001",
"instructorId": "cm3instru0001",
"clubId": "cm3club000001",
"type": "VACATION",
"status": "PENDING",
"startDate": "2026-10-22",
"endDate": "2026-10-22",
"days": 1,
"notes": "Texto libre",
"origin": "app",
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z"
}Modifica, aprueba o rechaza una ausencia
Permiso:absences:write
Cambiar status de PENDING a APPROVED/REJECTED resuelve una solicitud hecha desde
la app y notifica al monitor, igual que si lo hiciera el manager.
Parámetros de ruta
- absenceIdstringobligatorio
Cuerpo de la petición application/jsonAbsencePatch
- typeenum
VACATIONSICK_LEAVEPERSONALOTHER - startDatestring · date
- endDatestring · date
- statusenum
PENDINGAPPROVEDREJECTED - notesstring | null
máx. 300 caracteres
Respuestas
200Absence
Ausencia modificada.
- idstring
- instructorIdstring
- clubIdstring
- typeenum
VACATIONSICK_LEAVEPERSONALOTHER - statusenum
PENDINGAPPROVEDREJECTED - startDatestring · date
- endDatestring · date
Inclusive.
- daysinteger
Días naturales del rango.
- notesstring | null
- originenum
appwebapi - createdAtstring · date-time
- updatedAtstring · date-time
404Error
No existe o no pertenece a la cadena de la clave.
- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
409Error
Choca con el estado actual (duplicado, solape, versión congelada…).
- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
curl -X PATCH '/api/integration/v1/absences/{absenceId}' \
-H 'Authorization: Bearer opt_live_…' \
-H 'Content-Type: application/json' \
-d '{}'{
"id": "cm3id00000001",
"instructorId": "cm3instru0001",
"clubId": "cm3club000001",
"type": "VACATION",
"status": "PENDING",
"startDate": "2026-10-22",
"endDate": "2026-10-22",
"days": 1,
"notes": "Texto libre",
"origin": "app",
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z"
}Anula una ausencia
Permiso:absences:write
Parámetros de ruta
- absenceIdstringobligatorio
Respuestas
204
Ausencia anulada.
404Error
No existe o no pertenece a la cadena de la clave.
- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
curl -X DELETE '/api/integration/v1/absences/{absenceId}' \
-H 'Authorization: Bearer opt_live_…'Fichajes
Registro de jornada (art. 34.9 ET). Lectura y correcciones con motivo.
Lista fichajes
Permiso:time-entries:read
Fichajes de entrada y salida. La hora la pone siempre el servidor de Optime. workDate
es el día de la entrada en la zona horaria del gym (un turno de noche que cruza la
medianoche pertenece al día en que empezó).
Parámetros de consulta
- limitinteger
por defecto 100 · 1–500
- cursorstring
Valor
nextCursorde la página anterior. Opaco. - updatedSincestring · date-time
Solo registros creados o modificados en ese instante o después. Con este filtro el orden es
(updatedAt, id)ascendente, para que la sincronización incremental no se salte filas. - clubIdstring
Filtra por club. Sin él, todos los clubs a los que llega la clave.
- instructorIdstring
- fromstring · date
Por
workDate, inclusive. - tostring · date
Por
workDate, inclusive. - statusenum
OPENCLOSEDINCOMPLETE
Respuestas
200
Página de fichajes.
- array<TimeEntry>
- nextCursorstring | nullobligatorio
nullcuando no hay más páginas.
curl -X GET '/api/integration/v1/time-entries' \
-H 'Authorization: Bearer opt_live_…'{
"data": [
{
"id": "cm3id00000001",
"clubId": "cm3club000001",
"instructorId": "cm3instru0001",
"workDate": "2026-10-22",
"clockIn": "2026-10-22T07:02:11Z",
"clockOut": "2026-10-22T07:02:11Z",
"minutes": 60,
"status": "OPEN",
"source": "APP",
"correction": {
"reason": "Corrección por error de registro",
"editedAt": "2026-10-22T07:02:11Z",
"editedBy": "texto"
},
"incident": {
"note": "texto",
"status": "PENDING",
"proposedClockIn": "2026-10-22T07:02:11Z",
"proposedClockOut": "2026-10-22T07:02:11Z",
"response": "texto",
"resolvedAt": "2026-10-22T07:02:11Z"
},
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z"
}
],
"nextCursor": null
}Horas reales frente a planificadas, por monitor y día
Permiso:time-entries:read
Mismo cálculo que la vista de Fichajes de la web: turnos planificados en el horario resuelto frente a fichajes reales. Rango máximo: 62 días.
Parámetros de consulta
- clubIdstringobligatorio
- fromstring · dateobligatorio
- tostring · dateobligatorio
- instructorIdstring
Respuestas
200
Una fila por monitor y día con turno o fichaje.
- array<TimeEntryDaySummary>
curl -X GET '/api/integration/v1/time-entries/daily-summary' \
-H 'Authorization: Bearer opt_live_…'{
"data": [
{
"date": "2026-10-22",
"instructorId": "cm3instru0001",
"plannedMinutes": 1,
"workedMinutes": 1,
"state": "working",
"entryIds": [
"cm3entry00001"
]
}
]
}Corrige un fichaje (motivo obligatorio)
Permiso:time-entries:write
Mismas reglas que la corrección manual del manager: motivo obligatorio, sin horas
futuras, como mucho 16 h de duración y sin solapes con otros fichajes del monitor. El
fichaje queda marcado como corregido (editedAt, note) y la auditoría guarda el antes
y el después. La API no permite borrar fichajes.
Parámetros de ruta
- timeEntryIdstringobligatorio
Cuerpo de la petición application/json
- clockInstring · date-time
- clockOutstring · date-time | null
- reasonstringobligatorio
máx. 500 caracteres
Respuestas
200TimeEntry
Fichaje corregido.
- idstring
- clubIdstring
- instructorIdstring
- workDatestring · date
- clockInstring · date-time
- clockOutstring · date-time | null
- minutesinteger | null
Duración;
nullsi no hay salida. - statusenum
OPENen jornada ·CLOSEDcerrado ·INCOMPLETEse olvidó fichar la salida (clockOutsigue anullhasta que lo corrige el manager).OPENCLOSEDINCOMPLETE - sourceenum
APPfichado desde la app ·MANUALañadido por un manager o por la API.APPMANUAL - object | null
Última corrección manual, si la hay.
- object | null
Incidencia comunicada por el monitor al fichar.
- createdAtstring · date-time
- updatedAtstring · date-time
409Error
Choca con el estado actual (duplicado, solape, versión congelada…).
- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
422Error
Datos no válidos.
detailsindica el campo.- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
curl -X POST '/api/integration/v1/time-entries/{timeEntryId}/corrections' \
-H 'Authorization: Bearer opt_live_…' \
-H 'Content-Type: application/json' \
-d '{
"reason": "Corrección por error de registro"
}'{
"id": "cm3id00000001",
"clubId": "cm3club000001",
"instructorId": "cm3instru0001",
"workDate": "2026-10-22",
"clockIn": "2026-10-22T07:02:11Z",
"clockOut": "2026-10-22T07:02:11Z",
"minutes": 60,
"status": "OPEN",
"source": "APP",
"correction": {
"reason": "Corrección por error de registro",
"editedAt": "2026-10-22T07:02:11Z",
"editedBy": "texto"
},
"incident": {
"note": "texto",
"status": "PENDING",
"proposedClockIn": "2026-10-22T07:02:11Z",
"proposedClockOut": "2026-10-22T07:02:11Z",
"response": "texto",
"resolvedAt": "2026-10-22T07:02:11Z"
},
"createdAt": "2026-10-22T07:02:11Z",
"updatedAt": "2026-10-22T07:02:11Z"
}Nómina
Cierre mensual de horas por monitor, listo para nómina. Solo lectura.
Cierres mensuales del club
Permiso:payroll:read
Parámetros de ruta
- clubIdstringobligatorio
Parámetros de consulta
- yearinteger
- statusenum
DRAFTAPPROVEDARCHIVED - updatedSincestring · date-time
Solo registros creados o modificados en ese instante o después. Con este filtro el orden es
(updatedAt, id)ascendente, para que la sincronización incremental no se salte filas.
Respuestas
200
Periodos (sin el detalle por monitor).
- array<PayrollPeriodSummary>
curl -X GET '/api/integration/v1/clubs/{clubId}/payroll' \
-H 'Authorization: Bearer opt_live_…'{
"data": [
{
"clubId": "cm3club000001",
"year": 2026,
"month": 10,
"status": "DRAFT",
"approvedAt": "2026-10-22T07:02:11Z",
"approvedBy": "texto",
"updatedAt": "2026-10-22T07:02:11Z"
}
]
}Cierre de horas de un mes, por monitor
Permiso:payroll:read
Un mes APPROVED o ARCHIVED está congelado: sus cifras no cambian aunque luego se
modifique el horario o un contrato. Un mes sin aprobar se calcula en el momento a partir
del horario y viene con provisional: true; para nómina conviene importar solo meses
aprobados. Solo lectura: aprobar, reabrir y archivar se hace desde la web.
Parámetros de ruta
- clubIdstringobligatorio
- yearintegerobligatorio
- monthintegerobligatorio
1–12
Respuestas
200PayrollPeriod
Cierre del mes.
- clubIdstring
- yearinteger
- monthinteger
- statusenum
DRAFTAPPROVEDARCHIVED - approvedAtstring · date-time | null
- approvedBystring | null
- updatedAtstring · date-time
- provisionalboolean
truesi el mes no está aprobado y las cifras se han calculado ahora. - notesstring | null
- array<PayrollRecord>
404Error
No existe o no pertenece a la cadena de la clave.
- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
curl -X GET '/api/integration/v1/clubs/{clubId}/payroll/{year}/{month}' \
-H 'Authorization: Bearer opt_live_…'{
"clubId": "cm3club000001",
"year": 2026,
"month": 10,
"status": "DRAFT",
"approvedAt": "2026-10-22T07:02:11Z",
"approvedBy": "texto",
"updatedAt": "2026-10-22T07:02:11Z",
"provisional": false,
"notes": "Texto libre",
"records": [
{
"instructorId": "cm3instru0001",
"externalId": "cm3extern0001",
"instructorName": "Lucía Martín",
"actual": {
"reception": 4,
"class1h": 4,
"class30min": 4,
"manager": 4,
"reinforcement": 4,
"total": 4
},
"target": {
"reception": 4,
"class1h": 4,
"class30min": 4,
"manager": 4,
"reinforcement": 4,
"total": 4
},
"holidayHours": 4,
"nightHours": 4,
"atcHours": 4,
"extraActivities": {
"class1hInside": 4,
"class1hOutside": 4,
"class30minInside": 4,
"class30minOutside": 4
},
"manualAdjustment": 4,
"adjustmentNotes": "texto"
}
]
}Socios
Control mensual de altas y bajas de socios frente a presupuesto. Solo lectura.
Control de socios mes a mes
Permiso:membership:read
Solo los meses del año con datos; el cierre acumulado cuenta los meses sin datos como cero.
Parámetros de ruta
- clubIdstringobligatorio
- yearintegerobligatorio
Respuestas
200
Resumen de cada mes del año.
- yearinteger
- openingMembersinteger | null
Socios a 1 de enero.
- array<MembershipMonth>
curl -X GET '/api/integration/v1/clubs/{clubId}/membership/{year}' \
-H 'Authorization: Bearer opt_live_…'{
"year": 2026,
"openingMembers": 1,
"months": [
{
"clubId": "cm3club000001",
"year": 2026,
"month": 10,
"joiners": {
"real": 1,
"estimate": 1,
"budget": 1
},
"leavers": {
"real": 1,
"estimate": 1,
"budget": 1
},
"net": 1,
"closingMembers": 1,
"frozen": 1,
"blocked": 1,
"transfers": 1,
"recoveryPct": 4,
"updatedAt": "2026-10-22T07:02:11Z"
}
]
}Control de socios de un mes, con registro diario
Permiso:membership:read
Parámetros de ruta
- clubIdstringobligatorio
- yearintegerobligatorio
- monthintegerobligatorio
1–12
Respuestas
200
Mes con su registro diario.
- clubIdstring
- yearinteger
- monthinteger
- object
- object
- netinteger
- closingMembersinteger | null
Socios al cierre del mes.
- frozeninteger
- blockedinteger
- transfersinteger
- recoveryPctnumber
- updatedAtstring · date-time
- array<MembershipDay>
404Error
No existe o no pertenece a la cadena de la clave.
- objectobligatorio
- requestIdstring
Identificador para pedir soporte sobre una llamada concreta.
curl -X GET '/api/integration/v1/clubs/{clubId}/membership/{year}/{month}' \
-H 'Authorization: Bearer opt_live_…'{
"clubId": "cm3club000001",
"year": 2026,
"month": 10,
"joiners": {
"real": 1,
"estimate": 1,
"budget": 1
},
"leavers": {
"real": 1,
"estimate": 1,
"budget": 1
},
"net": 1,
"closingMembers": 1,
"frozen": 1,
"blocked": 1,
"transfers": 1,
"recoveryPct": 4,
"updatedAt": "2026-10-22T07:02:11Z",
"days": [
{
"day": 1,
"joinersReal": 1,
"joinersEstimate": 1,
"leaversReal": 1,
"leaversEstimate": 1,
"promotion": "texto"
}
]
}Sincronización
Registros borrados, para mantener al día una copia sincronizada.
Registros borrados desde una fecha
Permiso:clubs:read
Complementa updatedSince: un registro borrado ya no aparece en los listados, así que
una copia sincronizada necesita saber qué eliminar. Se conservan 90 días.
Parámetros de consulta
- sincestring · date-timeobligatorio
- entityenum
clubroomclassTypeinstructorcontractabsenceholidayscheduleDay - limitinteger
por defecto 100 · 1–500
- cursorstring
Valor
nextCursorde la página anterior. Opaco.
Respuestas
200
Página de borrados.
- array<object>
- nextCursorstring | nullobligatorio
nullcuando no hay más páginas.
curl -X GET '/api/integration/v1/deletions' \
-H 'Authorization: Bearer opt_live_…'{
"data": [
{
"entity": "absence",
"id": "cm3id00000001",
"clubId": "cm3club000001",
"deletedAt": "2026-10-22T07:02:11Z"
}
],
"nextCursor": null
}