API de Control de Acceso

Conecta torniquetes, cerraduras y lectores QR con Gym&i.

Tiempo real

Valida QR y abre paso en milisegundos

Funciona offline

Sincroniza miembros localmente, sube eventos después

API key segura

Autenticación por Bearer token con rate limiting

Autenticación

Todas las peticiones usan Bearer token en el header Authorization:

Authorization: Bearer <API_KEY>

La API key se genera en Configuración → Negocio → Control de Acceso del panel de administración.

Base URL: https://{subdomain}.gymni.mx/api/tenant/hardware

Endpoints

POST/checkin— Check-in en tiempo real

Valida el token de acceso del miembro y registra la asistencia. Compatible con cualquier método de identificación (QR, huella, RFID, facial). Requiere conexión a internet.

Request

{
  "access_token": "550e8400e29b41d4a716446655440000",
  "device_id": "entrada-principal"
}

Campo	Tipo	Requerido	Descripción
`access_token`	string	Sí	Token de acceso del miembro (32 chars hex)
`device_id`	string	No	Identificador del dispositivo (máx. 100 chars)

Respuestas

Acceso concedido:

{ "access": "granted", "member_name": "Carlos López", "warning": null }

Con advertencia:

{ "access": "granted", "member_name": "Carlos López", "warning": "Membresía con adeudo" }

No encontrado:

{ "access": "denied", "message": "Miembro no encontrado" }

Duplicado (mismo día):

{ "access": "granted", "member_name": "Carlos López", "message": "Ya registró asistencia hoy", "duplicate": true }

Importante: La respuesta depende de la política de acceso configurada por el gimnasio (ver sección más abajo). En modo Libre siempre concede acceso. En modo Flexible o Estricto, puede denegar según el estado de la membresía.

GET/members— Sincronización de miembros

Retorna todos los miembros con código QR para almacenamiento local. Llamar cada 1-5 minutos para mantener la base de datos local actualizada.

Respuesta

{
  "synced_at": "2026-03-26T12:00:00.000Z",
  "members": [
    {
      "access_token": "550e8400e29b41d4a716446655440000",
      "name": "Carlos López",
      "gender": "MALE",
      "status": "active",
      "warning": null
    }
  ]
}

Campo	Descripción
`access_token`	Token de acceso único del miembro (32 chars hex)
`name`	Nombre del miembro
`gender`	`"MALE"`, `"FEMALE"`, o `null`
`status`	`"active"` o `"warning"`
`warning`	Texto de la advertencia o `null`

POST/checkin/sync— Subir check-ins offline

Cuando el dispositivo estuvo sin internet, envía los check-ins acumulados en un solo request.

Request

{
  "events": [
    {
      "access_token": "550e8400e29b41d4a716446655440000",
      "device_id": "entrada-principal",
      "checked_in_at": "2026-03-26T09:30:00.000Z"
    }
  ]
}

Campo	Tipo	Requerido	Descripción
`events`	array	Sí	Lista de eventos (mín. 1, máx. 500)
`access_token`	string	Sí	Token de acceso del miembro
`device_id`	string	No	Identificador del dispositivo
`checked_in_at`	string	Sí	Fecha/hora ISO 8601 del check-in real

Validaciones

Timestamp no mayor a 5 minutos en el futuro (tolerancia de reloj)
Timestamp no mayor a 7 días de antigüedad
Duplicados por miembro por día se omiten automáticamente

Respuesta

{
  "processed": 45,
  "duplicates": 3,
  "errors": [
    { "index": 12, "access_token": "abc123...", "reason": "Miembro no encontrado" }
  ]
}

Códigos de error

Status	Significado
200	OK (check-in usa 200 incluso para `"access": "denied"`)
400	Datos inválidos en el body
401	API key inválida o no proporcionada
403	El plan del gimnasio no incluye esta función (requiere Pro+)
429	Rate limit excedido (ver header `Retry-After`)

Rate limits

Endpoint	Límite por minuto
`POST /checkin`	120
`GET /members`	30
`POST /checkin/sync`	10

Los límites son por gimnasio. Si se exceden, la respuesta incluye un header Retry-After.

Formato del token de acceso

El token de acceso de cada miembro es una cadena hexadecimal de 32 caracteres. Ejemplo: 550e8400e29b41d4a716446655440000

El token es único y persistente por miembro. No cambia a menos que un administrador lo regenere manualmente.

Flujo de integración recomendado

Modo online

Lector QR lee código del miembro
POST /checkin con el código
"granted" → abrir paso, "denied" → denegar
Mostrar nombre y advertencia si la hay

Modo offline-capable

Cada 1-5 minutos (con internet):

GET /members → guardar en base de datos local (SQLite, JSON, etc.)

Cuando un miembro escanea su QR:

Buscar token en la base de datos local
Si existe → abrir paso + guardar evento en cola
Si no existe → denegar (no sincronizado)

Cuando regresa el internet:

POST /checkin/sync con los eventos acumulados → limpiar cola

Política de acceso

El gimnasio configura qué miembros pueden entrar según el estado de su membresía. El campo access en la respuesta será "granted" o "denied" según la política activa.

Política	Membresía activa	Con adeudo	Cancelada	Sin membresía
Libre	granted	granted	granted	granted
Flexible	granted	granted + warning	denied	denied
Estricto	granted	denied	denied	denied

El staff del gimnasio (owners, admins, staff) siempre recibe "granted" sin importar la política.

Los warnings posibles son: "Sin membresía activa", "Membresía con adeudo", "Membresía cancelada", "Membresía vencida".

Métodos de identificación

La API es agnóstica al método de identificación. El dispositivo identifica al miembro con su método preferido y envía el access_token a Gym&i.

Método	Cómo envía el access_token
Código QR	El lector escanea el QR del celular del miembro. El QR contiene el access_token directamente.
Huella dactilar	El lector identifica la huella localmente contra su base de datos y envía el access_token asociado.
Reconocimiento facial	La cámara identifica el rostro y envía el access_token del miembro reconocido.
Tarjeta RFID / NFC	La tarjeta o pulsera contiene el access_token grabado. El lector lo lee por proximidad.

En todos los casos, el dispositivo envía POST /checkin con el campo access_token. Gym&i no necesita saber qué método se usó — solo valida el token y registra el acceso.

Enrolamiento biométrico recomendado

Los métodos biométricos (huella, cara) requieren un registro presencial inicial para asociar la biometría del miembro con su access_token. Recomendamos el siguiente flujo para garantizar que la identidad del miembro sea verificada correctamente:

El miembro abre su app y muestra su código QR — este QR contiene su access_token único. Es la prueba de identidad: solo el dueño de la cuenta puede generarlo desde su sesión activa.
El dispositivo escanea el QR — obtiene el access_token y lo busca en la lista sincronizada de miembros (vía GET /members). Muestra: "Hola Carlos. Pon tu dedo para registrar tu huella."
El miembro registra su biometría — el dispositivo captura la huella o el rostro y guarda el template asociado al access_token en su base de datos local.
Listo — a partir de ahí, el miembro se identifica con su biometría. El dispositivo encuentra el access_token asociado y llama a POST /checkin normalmente.

¿Por qué usar el QR para enrolar? Si el enrolamiento se hace por nombre o email, cualquier persona podría registrar su huella a nombre de otro miembro. El QR garantiza que solo el dueño de la cuenta (con sesión activa en su celular) puede iniciar el proceso. Es el único método seguro de verificación de identidad.

Este proceso puede ser completamente self-service si el dispositivo cuenta con lector QR y lector biométrico. El miembro lo hace solo, sin staff. Para dispositivos sin lector QR, un miembro del staff puede buscar al miembro manualmente durante el enrolamiento inicial.

Dispositivos compatibles

Cualquier dispositivo que pueda identificar al miembro, hacer peticiones HTTPS e interpretar respuestas JSON:

Lectores QR industriales (Honeywell, Zebra, Netum)
Lectores de huella dactilar (DigitalPersona, ZKTeco)
Terminales faciales (ZKTeco SpeedFace, Hikvision, Suprema)
Lectores RFID/NFC de proximidad
Raspberry Pi o mini PC como controlador
Tablet Android con app custom
Torniquetes con controladora programable

¿No eres técnico? Lee nuestra guía de control de acceso para gimnasios o el artículo completo sobre opciones de hardware.