Disponible. La API de integración está en producción en
/api/integration/v1: lectura de todos los recursos y escritura de datos maestros, ausencias, horario de un día y correcciones de fichaje. La especificación completa está enopenapi.yaml(OpenAPI 3.1) y en la referencia interactiva, donde cada operación se puede probar con tu propia clave. Los webhooks están previstos como siguiente paso.La API de la app móvil (
/api/v1) es otra distinta: cada llamada va con la sesión de una persona y devuelve sus propios datos. Está documentada endocs/API.mdy no sirve para integraciones de sistema a sistema.
Para qué sirve
Optime organiza la operativa de cada club: clases, salas, monitores, el horario de cada día, los fichajes y las horas de cada contrato. La API de integración permite que cualquier otro sistema de la cadena lea esos datos y, cuando tiene sentido, los escriba. Algunos usos habituales:
| Necesidad | Qué ofrece la API |
|---|---|
| Gestión de personal (ERP, RR. HH.) | Alta, modificación y baja de monitores, especialidades, disponibilidad, contratos versionados y ausencias. |
| Análisis y reporting (BI, almacén de datos, hojas de cálculo) | Carga incremental de todo lo que cambia: horario efectivo, fichajes, ausencias, horas y socios, con registro de borrados. |
| Nómina y gestoría | Cierre mensual de horas aprobado por monitor y categoría, con festivos y nocturnidad. |
| Automatizaciones propias | Scripts y herramientas internas que consultan el horario, registran ausencias o corrigen fichajes con motivo. |
Quién manda en cada dato
Para que dos sistemas no pisen el mismo dato, el reparto recomendado es:
- El sistema de personal manda en el empleado: alta, baja, datos personales, identificador externo (
externalId) y contrato. Los escribe en Optime por la API. - Optime manda en la operativa: horario de cada día, asignaciones, fichajes y cierre de horas. El resto de sistemas los leen.
- Las ausencias son compartidas: un sistema externo puede registrarlas ya aprobadas y los monitores pueden pedirlas desde la app para que el manager las apruebe. Las dos vías acaban en el mismo sitio.
Nada de esto es obligatorio: cada cadena decide qué sistema escribe qué, concediendo a cada clave solo los permisos que necesita.
Alcance
| Área | Lectura | Escritura |
|---|---|---|
| Organización | Gym y clubs | — |
| Catálogo | Salas y tipos de clase | Crear y modificar |
| Monitores | Fichas, especialidades, disponibilidad y contratos | Alta, modificación y baja; especialidades; disponibilidad; nuevas versiones y correcciones de contrato |
| Horario | Horario resuelto por día y festivos | Sustituir o restablecer un día concreto (con avisos, dryRun e If-Match) |
| Ausencias | Listado con filtros | Crear, modificar y eliminar |
| Fichajes | Fichajes y resumen diario | Correcciones con motivo |
| Nómina | Cierre mensual de horas | — (se aprueba desde la web) |
| Socios | Control mensual de altas y bajas | — |
| Sincronización | Registros borrados (GET /deletions) | — |
En la especificación, cada operación lleva x-scopes con el permiso que necesita.
Autenticación
Cada cadena crea sus claves desde Integraciones (solo el owner). Una clave:
- se muestra una sola vez al crearla y Optime solo guarda su huella cifrada;
- lleva un nombre descriptivo y unos permisos concretos;
- puede limitarse a ciertos clubs;
- se revoca al momento, y queda registrado cada uso (qué clave, qué llamada, cuándo).
Se envía en la cabecera Authorization:
GET /api/integration/v1/clubs HTTP/1.1
Host: optimeclub.com
Authorization: Bearer opt_live_9f3c…Las claves opt_test_… pertenecen al entorno de pruebas, con datos de ejemplo. Los permisos de escritura dejan modificar datos del club como si lo hiciera un manager: conviene concederlos solo a la clave del sistema que los necesite.
Permisos
| Permiso | Permite |
|---|---|
clubs:read | Gym, clubs y registro de borrados |
catalog:read / catalog:write | Salas y tipos de clase |
instructors:read / instructors:write | Fichas de monitor, especialidades y disponibilidad (lectura incluye contratos) |
contracts:write | Crear y corregir versiones de contrato |
schedule:read / schedule:write | Horario resuelto y festivos / modificar un día |
absences:read / absences:write | Ausencias |
time-entries:read / time-entries:write | Fichajes / corregirlos con motivo |
payroll:read | Cierre mensual de horas (no hay permiso de escritura) |
membership:read | Control de socios |
Recomendamos una clave por sistema y solo con lo que necesita: por ejemplo, un sistema que solo importa el cierre de horas se queda con payroll:read e instructors:read.
Convenciones
- Identificadores: texto opaco (
"cm3x9…"). El identificador del empleado en el sistema externo va enexternalIddel monitor. - Un monitor, un club: una ficha de monitor pertenece a un único club. Si un empleado trabaja en dos clubs tiene dos fichas, y las dos pueden llevar el mismo
externalId. - Fechas sin hora:
YYYY-MM-DD, en la zona horaria del gym (GET /gym→timezone, normalmenteEurope/Madrid). - Instantes (fichajes,
updatedAt): ISO 8601 en UTC,2026-10-04T07:02:11Z. - Horas del día:
"HH:MM"en 24 h, hora local del club. - Día de la semana:
0 = lunes … 6 = domingo. - Horas de contrato y de nómina: número decimal (
7.5= 7 h 30 min). - Idioma: los mensajes de error vienen en español.
Paginación
Los listados devuelven páginas con cursor:
{
"data": [ { "id": "…" } ],
"nextCursor": "eyJ1IjoiMjAyNi0xMC0yMlQxMDow…"
}Se pide la siguiente con ?cursor=<nextCursor>. limit va de 1 a 500 (100 por defecto). Cuando nextCursor es null no hay más.
Sincronización incremental
Los listados admiten updatedSince: devuelven solo lo creado o modificado desde ese instante, ordenado por (updatedAt, id). Una carga periódica típica:
- Guardar la hora de inicio de la carga (
T1). - Para cada recurso, pedir
?updatedSince=<T0>(la de la carga anterior) y recorrer todas las páginas, haciendo upsert porid. - Pedir
GET /deletions?since=<T0>y borrar esos registros. - Guardar
T1como el nuevoT0.
Conviene solapar unos minutos (T0 menos 5 min); el upsert hace que repetir filas no tenga efecto.
El horario es un caso aparte. El horario efectivo de un día se calcula a partir de la plantilla semanal y de las modificaciones puntuales, así que un cambio en la plantilla altera muchos días a la vez. Para el horario recomendamos volver a leer una ventana móvil (por ejemplo, de 30 días atrás a 30 días adelante) con GET /clubs/{clubId}/schedule?from=…&to=…, en lugar de usar updatedSince.
Escrituras
- Idempotencia: los
POSTaceptan la cabeceraIdempotency-Key. Repetir la misma petición con la misma clave durante 24 h devuelve la respuesta original (con la cabeceraIdempotent-Replayed: true) sin crear nada nuevo, así que se puede reintentar sin miedo tras un corte de red. Reutilizar la clave con otro cuerpo responde422. - Mismas reglas que la web: todo lo que entra por la API pasa por las mismas validaciones que si lo hiciera un manager, queda en la auditoría con el antes y el después (firmado como
API (<nombre de la clave>)) y notifica a los monitores en la app cuando les afecta. - Bajas, no borrados: los monitores, salas y tipos de clase se dan de baja con
isActive=false. Los fichajes se conservan 4 años por ley (art. 34.9 ET) y no se pueden borrar por la API. - Contratos versionados: un cambio de contrato se registra como versión nueva desde una fecha (hoy o futura, en la zona horaria del gym), y las horas pasadas se siguen calculando con la versión anterior. Solo puede haber una versión futura: si ya hay una programada con otra fecha,
POSTresponde409(corrígela conPUTo cámbiala desde la web). Corregir la versión vigente o la futura exige motivo; una versión ya sustituida es histórico y no se toca. Las nóminas aprobadas no cambian nunca. - Horario de un día:
PUT /clubs/{clubId}/schedule/{fecha}sustituye el día completo y devuelve los avisos que genera (recepción sin cubrir, monitor de vacaciones, solapes, especialidad, horas de contrato…), con la severidad configurada por el club. Los avisos no bloquean el guardado: son los mismos que vería el manager en la web. Con?dryRun=truesolo valida. ConIf-Match: <etag>no pisa un cambio que haya hecho un manager mientras tanto.DELETEdevuelve el día a la plantilla. No se admiten fechas pasadas. - Fichajes: solo se pueden corregir, con motivo obligatorio, sin horas futuras, con un máximo de 16 h y sin solapes. Las horas van como instantes ISO 8601 (UTC); la corrección queda firmada como
API (<nombre de la clave>). - Ausencias: las que registra la API nacen
APPROVED(oPENDINGsi se indica) conorigin: api. UnPATCHque pasa una solicitudPENDINGaAPPROVED/REJECTEDavisa al monitor en la app, igual que si lo hiciera el manager. Las rechazadas no bloquean fechas. - Monitores: el email es único por club (
409 CONFLICTsi se repite) y elexternalIdtambién (409 DUPLICATE_EXTERNAL_ID, con el id de la ficha existente endetails). Cambiar el email anula la invitación a la app pendiente. Las especialidades deben ser tipos de clase del mismo club. - Nómina: solo lectura. Aprobar, reabrir o archivar un mes se hace desde la web.
Errores
Todas las respuestas de error tienen la misma forma:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "La fecha de fin no puede ser anterior a la de inicio",
"details": [ { "field": "endDate", "message": "Debe ser igual o posterior a startDate" } ]
},
"requestId": "req_01J…"
}| HTTP | code | Cuándo |
|---|---|---|
| 400 | BAD_REQUEST | JSON mal formado o parámetro con formato incorrecto |
| 401 | UNAUTHENTICATED | Falta la clave, no existe o está revocada |
| 403 | FORBIDDEN | La clave no tiene ese permiso o ese club |
| 404 | NOT_FOUND | No existe o no pertenece a la cadena |
| 409 | CONFLICT, DUPLICATE_EXTERNAL_ID, ABSENCE_OVERLAP, TIME_ENTRY_OVERLAP, PAYROLL_FROZEN | Choca con el estado actual |
| 412 | PRECONDITION_FAILED | El día cambió desde que se leyó (If-Match) |
| 422 | VALIDATION_ERROR | Datos no válidos (details dice el campo) |
| 429 | RATE_LIMITED | Demasiadas peticiones (ver Retry-After) |
| 5xx | INTERNAL_ERROR | Error nuestro; se puede reintentar. Indica el requestId al soporte |
Límites
- 600 peticiones por minuto por clave. Al superarlo se responde
429con la cabeceraRetry-After(segundos). - Toda respuesta lleva la cabecera
X-Request-Id(el mismorequestIddel cuerpo de error). - Rangos de fechas de horario y resumen de fichajes: 62 días como máximo por llamada.
Versionado
La versión va en la ruta (/v1). Dentro de una versión solo se hacen cambios compatibles: campos nuevos en las respuestas, parámetros opcionales nuevos, endpoints nuevos. Hay que ignorar los campos desconocidos. Un cambio incompatible saldría como /v2 y la v1 se mantendría al menos 12 meses, con aviso previo.
Webhooks (próximamente)
Está previsto que Optime envíe un POST firmado (HMAC-SHA256 en la cabecera Optime-Signature) a la URL que configure la cadena, con reintentos durante 24 h, para no tener que consultar. Eventos previstos:
| Evento | Cuándo |
|---|---|
schedule.day.changed | Se modifica o se restablece el horario de un día |
absence.created / absence.updated | Nueva ausencia o cambio de estado (por ejemplo, una solicitud de la app aprobada) |
time_entry.created / time_entry.corrected | Fichaje de entrada o salida, o corrección manual |
payroll.approved / payroll.reopened | Se aprueba o se reabre el cierre de un mes |
instructor.created / instructor.updated | Cambios en una ficha hechos desde la web |
El cuerpo llevará el tipo de evento, el identificador y el club; para el detalle se consulta la API. Mientras tanto, la sincronización incremental descrita arriba cubre el mismo caso con una consulta periódica.
Recursos
| Recurso | Lectura | Escritura |
|---|---|---|
| Gym y clubs | GET /gym, GET /clubs, GET /clubs/{id} | — |
| Salas | GET /clubs/{id}/rooms | POST, PATCH |
| Tipos de clase | GET /clubs/{id}/class-types | POST, PATCH |
| Monitores | GET /instructors, GET /instructors/{id} | POST, PATCH, PUT …/specialties, PUT …/availability |
| Contratos | GET /instructors/{id}/contracts | POST (nueva versión), PUT …/{contractId} (corrección con motivo) |
| Horario | GET /clubs/{id}/schedule?from&to | PUT /clubs/{id}/schedule/{fecha}, DELETE (volver a la plantilla) |
| Festivos | GET /clubs/{id}/holidays | — |
| Ausencias | GET /absences | POST, PATCH, DELETE |
| Fichajes | GET /time-entries, GET /time-entries/daily-summary | POST /time-entries/{id}/corrections |
| Cierre de horas | GET /clubs/{id}/payroll, GET /clubs/{id}/payroll/{año}/{mes} | — |
| Socios | GET /clubs/{id}/membership/{año} (solo los meses con datos), GET …/{año}/{mes} | — |
| Borrados | GET /deletions?since | — |
Cada operación, con sus parámetros y esquemas, está en la referencia interactiva.
Ejemplos
Alta de un empleado desde el sistema de personal
POST /api/integration/v1/instructors
Authorization: Bearer opt_live_…
Idempotency-Key: 7b1e0c2a-4f7d-4c39-9a51-2f0c6f0a1d11
Content-Type: application/json
{
"clubId": "cm3club…",
"externalId": "EMP-00427",
"name": "Lucía Martín",
"email": "lucia.martin@ejemplo.com",
"canDoReception": true,
"specialtyClassTypeIds": ["cm3spinning…", "cm3pilates…"],
"contract": {
"effectiveFrom": "2026-11-01",
"days": [
{ "dayOfWeek": 0, "reception": 4, "class1h": 2 },
{ "dayOfWeek": 2, "reception": 4, "class1h": 2 },
{ "dayOfWeek": 4, "class1h": 3 }
]
},
"sendAppInvite": true
}Baja
PATCH /api/integration/v1/instructors/cm3lucia…
{ "isActive": false }Baja médica registrada en otro sistema
POST /api/integration/v1/absences
{ "instructorId": "cm3lucia…", "type": "SICK_LEAVE", "startDate": "2026-11-12", "endDate": "2026-11-15" }Si Lucía tenía clases esos días, el horario del club las marca como aviso para que el manager las recoloque (o lo haga el asistente IA).
Cierre de horas de octubre
GET /api/integration/v1/clubs/cm3club…/payroll/2026/10{
"clubId": "cm3club…",
"year": 2026,
"month": 10,
"status": "APPROVED",
"approvedAt": "2026-11-02T09:14:00Z",
"provisional": false,
"records": [
{
"instructorId": "cm3lucia…",
"externalId": "EMP-00427",
"instructorName": "Lucía Martín",
"actual": { "reception": 34, "class1h": 26, "class30min": 0, "manager": 0, "reinforcement": 0, "total": 60 },
"target": { "reception": 34, "class1h": 30, "class30min": 0, "manager": 0, "reinforcement": 0, "total": 64 },
"holidayHours": 4,
"nightHours": 2.5,
"atcHours": 0,
"extraActivities": { "class1hInside": 26, "class1hOutside": 0, "class30minInside": 0, "class30minOutside": 0 },
"manualAdjustment": 0,
"adjustmentNotes": null
}
]
}