# API de integraciones de Fitnova (v1)

> Documentación completa de la API de integraciones de Fitnova en un único fichero: las guías, la referencia de cada operación (parámetros, cuerpos, ejemplos, respuestas y errores) y todos los esquemas. Sale de la misma especificación OpenAPI que el portal para desarrolladores.

## Servidores

- `https://developers.fitnova.eu` — ProducciÃ³n

Las rutas de la referencia son relativas al servidor (por ejemplo, `GET /integrations/v1/ping`).

## Autenticación

- Cabecera `X-API-Key` en todas las peticiones: Clave de integración del centro (`fnv_live_…` o `fnv_test_…`). La facilita Fitnova; se muestra una sola vez. Nunca la pongas en una app móvil ni en una web.

---

# Guías

## Introducción

La **API de integraciones de Fitnova** permite que tu programa de gestión (el que usa el centro para sus socios, cuotas y reservas) controle quién puede entrar por los tornos de un centro equipado con el control de accesos de Fitnova.

Tú mandas **el resultado** de tus reglas: qué socios existen, con qué tarjeta o QR se identifican y en qué momentos pueden pasar. Fitnova se encarga de hacérselo llegar al programa de tornos del centro y te devuelve cada entrada, cada salida y cada acceso denegado con su motivo.

```
Tu programa de gestión
        │  HTTPS + X-API-Key
        ▼
Fitnova (/integrations/v1)
        │
        ▼
Programa de tornos del centro
        │
        ▼
Tornos y lectores
```

De vuelta, Fitnova te envía cada entrada, salida y acceso denegado por **webhook firmado** y puedes consultarlos con `GET /access-events`.

### Cómo encaja

1. Fitnova da de alta el centro en **gestión externa**, configura sus tornos y crea los **perfiles de acceso** (por ejemplo, *Sala* o *Piscina*: cada uno abre unos tornos).
2. Tú creas los **socios** con tu propio identificador (`externalId`) y les asignas sus **tarjetas RFID** o les das un **QR** desde tu app.
3. Tú concedes **permisos de acceso**: «este socio puede entrar con el perfil *Sala* de tal fecha a tal fecha», o solo en unas franjas semanales, o un único día.
4. El programa de tornos recibe los cambios en segundos y valida cada paso en local, también si se queda sin conexión.
5. Cada entrada, salida o acceso denegado te llega por **webhook** y puedes consultarlo después con **`GET /access-events`**.

### Lo que la API no hace

- **No cobra, no lleva cuotas ni bonos.** El contador de sesiones, los pagos y las renovaciones son tuyos: cuando un socio no debe entrar, retiras su permiso.
- **No gestiona reservas ni clases.** Si un acceso depende de una reserva, mándalo como permiso de tipo `WINDOW` con la ventana que tú decidas.
- **No envía correos ni notificaciones** a los socios, ni les crea usuario en las apps de Fitnova.
- **No ve los socios que el centro tuviera antes** en Fitnova: solo los que creas por la API.
- Mientras el centro está en gestión externa, sus socios no pueden iniciar sesión ni registrarse en las apps de Fitnova: todos sus datos llegan desde tu programa.

### Glosario

| Término | Qué es |
|---|---|
| Centro | Un gimnasio. Tu clave pertenece a un único centro: no hace falta indicarlo en las llamadas. |
| Socio (`member`) | Persona que entra por los tornos. La identificas con tu `externalId`. |
| Perfil de acceso (`access-profile`) | Conjunto de tornos y zonas. Lo crea Fitnova; tú usas su `code`. |
| Permiso de acceso (`access-grant`) | «Este socio, con este perfil, puede entrar en estos momentos». Un socio puede tener varios. |
| Evento de acceso (`access-event`) | Lo que registra un torno: una entrada (`access.entry`), una salida (`access.exit`) o un paso denegado con su motivo (`access.denied`). |
| Visita (`visitId`) | Una entrada y su salida: comparten el mismo `visitId`. |

## Primeros pasos

### 1. Pide tus claves

Escribe a Fitnova indicando el centro, para qué vas a usar la API (qué scopes necesitas) y, si quieres, desde qué IPs llamarás. Recibirás:

- Una clave de **pruebas** (`fnv_test_…`) para el entorno de pruebas, con un centro de pruebas ya configurado (perfiles y tornos de ejemplo).
- Cuando tu integración esté lista, una clave de **producción** (`fnv_live_…`) para el centro real.

Cada clave se muestra **una sola vez**. Guárdala en un gestor de secretos de tu servidor; nunca en una app móvil, en una web ni en un repositorio.

### 2. Entornos

| Entorno | URL base | Claves |
|---|---|---|
| Producción | `https://developers.fitnova.eu/integrations/v1` | `fnv_live_…` |
| Pruebas | `https://dev-developers.fitnova.eu/integrations/v1` | `fnv_test_…` |

El entorno de pruebas es independiente: lo que hagas allí no afecta a ningún centro real. Su portal está en `https://dev-developers.fitnova.eu` y desde él puedes probar cada llamada con tu clave de pruebas.

### 3. Comprueba tu clave

```bash
curl https://dev-developers.fitnova.eu/integrations/v1/ping \
  -H "X-API-Key: fnv_test_Xq3vN8bT2kLw9RmZ5cYh7JpD4sGf6AeU1oQiWn0VzKx"
```

```json
{
  "apiVersion": "v1",
  "tenantId": "3b0f6c1e-7a2d-4e8b-9c5f-1d2e3f4a5b6c",
  "keyName": "Integración pruebas",
  "environment": "TEST",
  "scopes": ["events:read", "grants:read", "grants:write", "members:read", "members:write"],
  "serverTime": "2026-11-12T17:03:11.482Z"
}
```

Compara `serverTime` con la hora de tu sistema: los webhooks y el QR dependen de que tu reloj esté en hora.

### 4. Orden recomendado para conectar un centro

1. `GET /access-profiles`: los perfiles que puedes conceder.
2. `POST /bulk/members` (o `PUT /members/{externalId}` uno a uno): tus socios.
3. `PUT /members/{externalId}/credentials/rfid/{rfidNumber}`: sus tarjetas; o `POST …/credentials/qr-secret` si usan QR.
4. `POST /bulk/access-grants` (o `PUT /access-grants/{externalId}`): sus permisos vigentes.
5. `PUT /webhook` y `POST /webhook/test`: para recibir las entradas, salidas y accesos denegados.
6. A partir de ahí, mantén todo sincronizado: cada alta, baja, renovación o impago de tu programa se traduce en un `PUT` o un `DELETE` (ver *Casos de uso*).

En el entorno de pruebas no hay un torno delante: simula los pasos de tus socios con `POST /sandbox/access-events` (ver *Entorno de pruebas*) y recibirás los eventos como si fueran reales. Cuando tu integración esté lista, repasa *Puesta en producción* y pídenos la clave `fnv_live_`.

### 5. Probar desde este portal

Cada llamada de la referencia tiene un botón para probarla. Elige el servidor de pruebas, escribe tu clave `fnv_test_…` en la autenticación `X-API-Key` y envía. La clave solo se guarda en la memoria de esta pestaña. La especificación OpenAPI completa se puede descargar (botón *Descargar OpenAPI*) para generar clientes.

### 6. Si trabajas con un asistente de IA

El botón *Descargar documentación* de la cabecera descarga toda esta documentación (guías y referencia completa de cada llamada, con sus campos, ejemplos y errores) en un único fichero Markdown. Dáselo a tu asistente como contexto.

## Casos de uso

Cómo se traduce a la API lo que vende y gestiona un centro. La regla general: **tu programa decide, Fitnova ejecuta**. Cada vez que en tu programa cambia si un socio puede entrar, mandas el resultado con un `PUT` o un `DELETE`.

Usa como `externalId` de cada permiso el identificador de lo que lo origina en tu programa (la cuota, el periodo, la reserva…). Así un reintento o una corrección actualizan el mismo permiso en lugar de crear otro.

### Alta de un socio nuevo

1. `PUT /members/{externalId}` con sus datos (al menos `firstName`).
2. Su credencial: `PUT /members/{externalId}/credentials/rfid/{rfidNumber}` si usa tarjeta, o `POST /members/{externalId}/credentials/qr-secret` si usa el QR de tu app.
3. Su permiso: `PUT /access-grants/{externalId}` según lo que haya contratado (ver los casos siguientes).

El socio puede pasar en cuanto el torno recibe el permiso (segundos).

### Cuota mensual (o trimestral, anual…)

Un permiso `CONTINUOUS` por cada periodo pagado:

```json
PUT /access-grants/cuota-2026-11-socio-1042
{ "memberExternalId": "socio-1042", "accessProfile": "sala", "type": "CONTINUOUS",
  "start": "2026-11-01T00:00:00+01:00", "end": "2026-12-01T00:00:00+01:00" }
```

- **Renovación:** al cobrar el periodo siguiente, crea su permiso (`cuota-2026-12-socio-1042`). Si prefieres un único permiso por socio, envía otra vez el mismo `externalId` con el `end` ampliado: el `PUT` sustituye el permiso entero.
- **Margen de cortesía:** si dejas unos días de gracia tras el vencimiento, pon ese margen en `end`; tú decides la política.
- **Cuota con horario reducido** (solo mañanas, solo fines de semana): `SCHEDULED` con sus `weeklySlots`.
- **Una entrada al día como máximo:** añade `"dailyEntryLimit": 1`.

### Impago

Elige según tu política:

- **Bloquear sin perder nada:** `PUT /members/{externalId}` con `"enabled": false`. Deja de entrar al momento y sus permisos siguen guardados. Al cobrar, `"enabled": true` y vuelve a entrar con lo que tenía.
- **Cortar solo esa cuota:** `PUT` del permiso con `end` = ahora (o `DELETE /access-grants/{externalId}`). Si tiene otros permisos (un bono, una reserva), sigue entrando con ellos.

### Baja temporal o congelación

- **Pausa completa:** `"enabled": false` en el socio y, al volver, `"enabled": true`.
- **Pausa que alarga la cuota:** retira el permiso actual (`end` = inicio de la pausa) y, al volver, crea uno nuevo con los días que le quedaban.

### Baja definitiva

`DELETE /members/{externalId}`: se le quitan las tarjetas, se revocan sus permisos y deja de valer su QR. Si vuelve más adelante, `PUT` con `"enabled": true` y créale de nuevo sus permisos.

### Bono de sesiones

El contador es tuyo:

1. Al vender el bono, crea un permiso `CONTINUOUS` con la caducidad del bono (o `SCHEDULED` si tiene horario).
2. Con cada `access.entry` del socio (webhook), descuenta una sesión en tu programa. Usa el `id` del evento para no descontar dos veces el mismo.
3. Al gastar la última, retira el permiso (`DELETE` o `end` = ahora). Si está dentro, el torno le deja salir.

Si una entrada y una salida forman una única sesión, empareja ambas por `visitId`. Para no descontar dos veces a quien sale y vuelve a entrar enseguida, puedes contar como mucho una sesión por día, o usar `dailyEntryLimit`.

### Clase con reserva

Un permiso `WINDOW` por reserva, con el margen que quieras antes y después de la clase:

```json
PUT /access-grants/reserva-88123
{ "memberExternalId": "socio-1042", "accessProfile": "piscina", "type": "WINDOW",
  "start": "2026-11-20T17:45:00Z", "end": "2026-11-20T19:15:00Z" }
```

Si el socio cancela la reserva, `DELETE /access-grants/reserva-88123`.

### Pase de día o entrada suelta

`DAY_PASS` con la fecha (00:00 a 24:00 en hora de Madrid). Para que solo valga una vez, añade `"dailyEntryLimit": 1`.

### Varias zonas

Un permiso por perfil. Si su cuota incluye sala y piscina y el centro tiene perfiles separados, crea dos permisos con el mismo periodo. Si el centro tiene un perfil combinado (*Sala + Piscina*), uno basta. Los perfiles los configura Fitnova con el centro: pídelos si te falta alguno.

### Tarjeta perdida o cambiada

1. `DELETE /members/{externalId}/credentials/rfid/{rfidNumber}` con la vieja.
2. `PUT /members/{externalId}/credentials/rfid/{rfidNumber}` con la nueva.

Una tarjeta no puede ser de dos socios: para pasarla de uno a otro, quítasela antes al primero (si no, `409`).

### Móvil perdido (QR)

`POST /members/{externalId}/credentials/qr-secret/rotate` y entrega el secreto nuevo a la app. Los QR anteriores dejan de valer.

### Qué hacer con cada acceso denegado

Cada `access.denied` trae `reason`. Lo habitual:

| `reason` | Qué suele significar | Qué hacer |
|---|---|---|
| `card_not_registered` | La tarjeta no está asignada a nadie | Comprueba el número en tu programa y asígnala (`PUT …/credentials/rfid/…`). |
| `member_inactive` | El socio está deshabilitado o de baja | Si no debería, `PUT` con `"enabled": true`. |
| `no_access_grant` | No tiene ningún permiso | Créale el permiso de lo que tenga contratado. |
| `no_valid_access` | Sus permisos no valen ahora (caducados, fuera de franja o tope diario) | Revisa fechas, franjas y `dailyEntryLimit`. |
| `antipassback_wait`, `wrong_zone` | Acaba de pasar, o el torno cree que ya está dentro | Normalmente nada: es una regla del torno. Si se repite, avisa al centro. |
| `outside_opening_hours`, `capacity_full`, `reader_disabled`, `internal_error` | Situación del centro o del torno | Nada en tu programa; el centro lo gestiona. |
| `qr_invalid` | QR mal generado, reutilizado o con el reloj del móvil desfasado | Revisa el algoritmo y el reloj; si persiste, rota el secreto del socio. |

### Mantenerlo todo sincronizado

Aunque mandes cada cambio al momento, una llamada puede fallar sin que te enteres. Una vez al día, recorre `GET /members` y `GET /access-grants` y compáralos con tu programa: crea o corrige lo que falte con `PUT` y retira lo que sobre. Para cargas grandes, usa la *Carga masiva*.

## Autenticación y scopes

Todas las llamadas llevan la clave del centro en la cabecera **`X-API-Key`**:

```http
GET /integrations/v1/members/socio-1042 HTTP/1.1
Host: developers.fitnova.eu
X-API-Key: fnv_live_Xq3vN8bT2kLw9RmZ5cYh7JpD4sGf6AeU1oQiWn0VzKx
```

- La clave identifica al centro: no se envía ningún id de centro.
- Solo HTTPS. La clave es un secreto de servidor: no la pongas en una app móvil ni en una web (para el QR, tu app recibe un secreto propio de cada socio, ver *Código QR*).
- Sin clave, con una clave que no existe, revocada o caducada: `401 unauthorized`.
- Si desde una IP llegan muchas peticiones con claves no válidas (30 en un minuto), esa IP recibe `429 rate_limited` hasta el minuto siguiente, salvo en las peticiones con una clave válida.

### Scopes

Cada clave lleva los scopes que pediste. Una llamada sin el scope necesario responde `403 forbidden`. Cada operación de la referencia indica su scope.

| Scope | Permite |
|---|---|
| `members:read` | `GET /members`, `GET /members/{externalId}` |
| `members:write` | `PUT` y `DELETE /members/{externalId}`, `POST /bulk/members` |
| `credentials:write` | `PUT` y `DELETE /members/{externalId}/credentials/rfid/{rfidNumber}` |
| `credentials:qr` | `POST /members/{externalId}/credentials/qr-secret` y `…/qr-secret/rotate` |
| `grants:read` | `GET /access-profiles`, `GET /access-grants`, `GET /access-grants/{externalId}` |
| `grants:write` | `PUT` y `DELETE /access-grants/{externalId}`, `POST /bulk/access-grants` |
| `events:read` | `GET /access-events` |
| `webhooks:write` | Todo `/webhook` (también su `GET` y `/webhook/deliveries`) |

`GET /ping` no necesita ningún scope.

### IPs permitidas

Al pedir la clave puedes indicar una lista de IPs desde las que llamarás. Con lista, una llamada desde otra IP responde `403 ip_not_allowed`. Indica la IP pública de salida de tus servidores.

### Caducidad

Una clave puede tener fecha de caducidad. A partir de ella responde `401`, igual que una clave revocada. Pide la nueva con tiempo.

### Rotación sin cortes

Un centro puede tener **dos claves activas a la vez**. Para cambiar de clave:

1. Pide a Fitnova una clave nueva para el centro.
2. Despliégala en tus servidores (comprueba con `GET /ping`).
3. Pide que se revoque la anterior.

Si crees que una clave se ha filtrado, pide que se revoque inmediatamente.

### Centro en gestión externa

La API solo funciona con centros en **gestión externa**. Si Fitnova cambia el modo del centro, las llamadas responden `403 tenant_not_external`.

## Convenciones

### Formato

- Cuerpos en JSON UTF-8 con `Content-Type: application/json`.
- En las respuestas todos los campos aparecen siempre; los que no tienen valor van como `null`. Ignora los campos que no conozcas: pueden aparecer campos nuevos (ver *Versionado*).

### Fechas y horas

- Las respuestas dan los instantes en **ISO-8601 UTC**: `2026-11-12T17:03:11Z`.
- En las peticiones, los instantes llevan zona o desfase: `2026-11-12T18:03:11+01:00` o `2026-11-12T17:03:11Z`.
- Las fechas sin hora van como `yyyy-MM-dd`. Los días naturales (pase de un día, límite diario de entradas) se cuentan en la hora del centro, `Europe/Madrid`.

### Tus identificadores (`externalId`)

Socios y permisos se identifican con **tu** identificador, no con uno de Fitnova: de 1 a 100 caracteres de `A–Z a–z 0–9 . _ : -` (sin espacios ni acentos; distingue mayúsculas y minúsculas). Usa el mismo id que en tu programa: así nunca necesitas guardar ids de Fitnova.

### Altas y cambios idempotentes

- `PUT /recurso/{externalId}` crea o actualiza: responde `201` si lo crea y `200` si ya existía. Repetir la misma petición no duplica nada, así que es seguro reintentarla tras un error de red.
- `DELETE` responde `204` también si ya estaba borrado o revocado, y `404` si nunca existió.
- Las cargas masivas (`POST /bulk/…`) son una lista de esos mismos `PUT`.

### Paginación

Los listados devuelven `{"data": [...], "nextCursor": "…"}`:

- `limit`: de 1 a 100 elementos por página (50 por defecto).
- `cursor`: pásale el `nextCursor` de la página anterior. Es opaco: no lo construyas ni lo interpretes.
- `nextCursor: null` = no hay más páginas.
- Excepción: en `GET /access-events`, `nextCursor` nunca es `null` y hay un campo `hasMore` (ver *Eventos de acceso*).

### Límite de peticiones

Cada clave puede hacer un número de peticiones por minuto natural (300 por defecto). Todas las respuestas llevan:

| Cabecera | Significado |
|---|---|
| `X-RateLimit-Limit` | Peticiones permitidas por minuto. |
| `X-RateLimit-Remaining` | Las que te quedan en este minuto. |
| `X-RateLimit-Reset` | Cuándo empieza el minuto siguiente (segundos Unix). |

Al pasarte: `429 rate_limited` con `Retry-After` (segundos que debes esperar). Una carga masiva cuenta como una sola petición: úsala para cargas iniciales o grandes sincronizaciones.

### Tamaño máximo

El cuerpo de una petición no puede pasar de **2 MB** (`413 payload_too_large`). Una carga masiva de 500 elementos cabe de sobra.

### Identificador de petición

Todas las respuestas llevan la cabecera **`X-Request-Id`** (y los errores, el campo `requestId` con el mismo valor). Guárdalo en tus registros e indícalo si contactas con soporte: con él localizamos tu petición.

## Errores

Todos los errores tienen el mismo formato:

```json
{
  "code": "validation_error",
  "message": "Los datos enviados no son válidos",
  "requestId": "3f6c1e0a-6a1b-4f43-9a51-0c2d7e9b8a10",
  "details": [
    { "field": "firstName", "message": "es obligatorio" },
    { "field": "birthDate", "message": "debe ser una fecha con formato yyyy-MM-dd" }
  ]
}
```

- `code`: estable; trátalo por programa.
- `message`: explicación en español para personas; puede cambiar, no lo compares.
- `requestId`: el mismo valor que la cabecera `X-Request-Id`.
- `details`: solo en `validation_error`, un elemento por problema con el campo afectado.

### Códigos

| HTTP | `code` | Cuándo | ¿Reintentar? |
|---|---|---|---|
| 400 | `bad_request` | JSON ilegible, parámetro con formato incorrecto, `cursor` no válido. | No: corrige la petición. |
| 401 | `unauthorized` | Falta `X-API-Key` o la clave no es válida, está revocada o ha caducado. | No. |
| 403 | `forbidden` | A la clave le falta el scope de la operación. | No. |
| 403 | `ip_not_allowed` | La IP de origen no está en la lista de la clave. | No. |
| 403 | `tenant_not_external` | El centro no está en gestión externa. | No: contacta con Fitnova. |
| 404 | `not_found` | El recurso no existe (o la ruta no existe). | No. |
| 405 | `method_not_allowed` | Método HTTP no admitido en esa ruta (la cabecera `Allow` dice cuáles). | No. |
| 406 | `not_acceptable` | No se puede responder en el formato pedido en `Accept`. | No. |
| 409 | `conflict` | Choca con el estado actual: email o tarjeta de otro usuario, centro sin QR activado… | No, salvo que cambie la situación. |
| 413 | `payload_too_large` | El cuerpo supera 2 MB. | No: divide el lote. |
| 415 | `unsupported_media_type` | `Content-Type` distinto de `application/json`. | No. |
| 422 | `validation_error` | Algún dato no es válido; mira `details`. | No: corrige los datos. |
| 429 | `rate_limited` | Límite de peticiones (o de pruebas de webhook, o de rotaciones de QR). | Sí, tras `Retry-After`. |
| 500 | `internal_error` | Error inesperado de Fitnova. | Sí, con espera creciente. |

Los `PUT` y `DELETE` son idempotentes: tras un `5xx` o un error de red puedes repetirlos sin riesgo. Reintenta con espera creciente (por ejemplo 1 s, 2 s, 4 s… hasta un minuto) y deja de reintentar los `4xx` salvo el `429`.

Pueden aparecer códigos nuevos: si no conoces un `code`, trátalo según su estado HTTP.

## Puesta en producción

Antes de pedir la clave de producción (`fnv_live_…`), comprueba en el entorno de pruebas que tu integración cumple esta lista. Es lo que revisaremos contigo: cada punto evita un problema real en el centro (socios que no entran, sesiones mal descontadas, avisos perdidos).

### Seguridad

- [ ] La clave vive solo en tu servidor, en un gestor de secretos. No está en ninguna app, web ni repositorio.
- [ ] Si llamas siempre desde las mismas IPs, nos las has dado para restringir la clave.
- [ ] Verificas la firma de cada webhook (`X-Fitnova-Signature`) y rechazas los que tengan más de 5 minutos (`X-Fitnova-Timestamp`).
- [ ] Si usas el QR, el secreto de cada socio llega a su app por tu canal autenticado y se guarda en el almacenamiento seguro del dispositivo.

### Robustez

- [ ] Reintentas los `5xx` y los errores de red con espera creciente, y los `429` tras los segundos de `Retry-After`. No reintentas los demás `4xx`: corriges la petición.
- [ ] Usas `PUT` con tus propios `externalId`, así un reintento nunca duplica socios ni permisos.
- [ ] Guardas el `requestId` de las respuestas con error, para que podamos encontrar la petición si nos consultas.
- [ ] Las cargas iniciales y las sincronizaciones grandes van por *Carga masiva*, no con miles de llamadas sueltas.

### Eventos

- [ ] Tu receptor responde `2xx` en menos de 10 s: guarda el evento y lo procesa después.
- [ ] Eliminas duplicados por el `id` del evento: un mismo evento puede llegar más de una vez.
- [ ] No dependes del orden de llegada: ordenas por `occurredAt` y emparejas entrada y salida por `visitId`.
- [ ] Tratas `access.denied` y los motivos (`reason`) que no conozcas como `other`.
- [ ] Recorres `GET /access-events` con su cursor como red de seguridad (al arrancar y cada cierto tiempo), por si un webhook no llegó.
- [ ] Una salida con `exitSource: "AUTO_CLOSE"` puede venir seguida de la salida real con el mismo `visitId`: la sustituyes.

### Sincronización

- [ ] Cada alta, baja, renovación, impago o reserva de tu programa se refleja en la API en el momento.
- [ ] Una vez al día comparas `GET /members` y `GET /access-grants` con tu programa y corriges las diferencias.
- [ ] El reloj de tu servidor está en hora (compáralo con `serverTime` de `GET /ping`).

### Prueba de punta a punta

Con el simulador del *Entorno de pruebas*, comprueba al menos:

1. Una entrada y su salida: te llegan `access.entry` y `access.exit` con el mismo `visitId`.
2. Un bono de sesiones que se agota: tras la última entrada retiras el permiso.
3. Un `access.denied` con socio (`no_valid_access`) y otro de una tarjeta que no es de nadie (`card_not_registered`).
4. Tu receptor caído: devuelve un `500`, comprueba que el evento se reintenta y se entrega al volver.

Cuando todo esté en verde, pídenos la clave de producción del centro.

## Versionado

La versión va en la ruta: `/integrations/v1`.

### Qué puede cambiar dentro de la v1

Solo cambios **compatibles**, sin aviso previo:

- Campos nuevos en las respuestas (ignora los que no conozcas).
- Campos nuevos **opcionales** en las peticiones.
- Operaciones, valores de enumeraciones, tipos de evento de webhook y códigos de error nuevos.
- Textos de `message` y de la documentación.

Programa tu integración para que lo tolere: no falles ante campos desconocidos, trata un valor de enumeración desconocido como «otro» y un `code` desconocido según su estado HTTP.

### Cambios incompatibles

Un cambio que rompa la compatibilidad (quitar o renombrar un campo, cambiar su significado o hacer obligatorio uno opcional) abre una versión nueva (`/integrations/v2`). La anterior:

- Sigue funcionando **al menos 12 meses** desde que se publica la nueva.
- Responde con las cabeceras `Deprecation` (desde cuándo está obsoleta) y `Sunset` (fecha a partir de la cual dejará de funcionar), según RFC 9745 y RFC 8594.
- Te avisaremos por correo al contacto técnico de la integración.

## Soporte

- **Dudas técnicas e incidencias:** escribe a tu contacto técnico de Fitnova (te lo damos junto con las claves). Incluye siempre el `requestId` de la respuesta (o de la cabecera `X-Request-Id`), la hora aproximada y el `externalId` afectado: con eso localizamos la petición. **Nunca envíes tu clave.**
- **Algo no funciona en el centro** (un socio no entra y no ves por qué): mira primero sus eventos `access.denied` en `GET /access-events?memberExternalId=…`; el `reason` suele explicarlo (ver *Casos de uso*).
- **Cambios en la API:** todos se anotan en *Cambios*. Los incompatibles (una versión nueva) te los avisamos además por correo con al menos 12 meses de margen (ver *Versionado*).
- **Toda la documentación en un fichero:** las guías y la referencia completa de cada llamada están en un único Markdown, enlazado como *Descargar documentación* en la cabecera del portal. Sirve para consultarla sin conexión o para dársela a tu asistente de IA.

## Cambios

### v1 — 18/11/2026

- Simulador de pasos por el torno para el entorno de pruebas: `POST /sandbox/access-events`.
- Guías nuevas: *Casos de uso*, *Puesta en producción* y *Soporte*.
- Toda la documentación en un único fichero Markdown (*Descargar documentación*).

### v1 — 12/11/2026

Primera versión publicada:

- Autenticación con `X-API-Key`, scopes, IPs permitidas, límite de peticiones y `GET /ping`.
- Socios: alta, actualización parcial, baja y reactivación; foto por URL.
- Tarjetas RFID.
- Perfiles de acceso y permisos `CONTINUOUS`, `WINDOW`, `DAY_PASS` y `SCHEDULED` (franjas semanales), con límite opcional de entradas diarias.
- Cargas masivas de socios y permisos (hasta 500 por petición).
- Eventos de acceso (`access.entry`, `access.exit`, `access.denied` con el motivo del rechazo) por consulta con cursor y por webhook firmado.
- QR `fnv-qr-v1` para la app del gestor (centros con el QR para gestores externos activado).

---

# Referencia

## Estado

Comprobación de la clave. Úsala al configurar la integración y como prueba de vida de tu conexión: responde a qué centro pertenece la clave, su entorno (`LIVE` o `TEST`), sus scopes y la hora del servidor.

### `GET /integrations/v1/ping` — Comprobar la clave

`operationId`: `ping`

Primera llamada recomendada: confirma que la clave es válida y dice a qué centro pertenece, su entorno (`LIVE` o `TEST`), sus scopes y la hora del servidor (úsala para comprobar el reloj de tu sistema).

**Scope requerido:** ninguno (basta con una clave válida).

**Respuestas**

- `200`: La clave es válida.
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden` (a la clave le falta el scope de la operación), `ip_not_allowed` (la IP de origen no está en la lista de la clave) o `tenant_not_external` (el centro no está en gestión externa). Cuerpo: `ApiError`.
- `429`: `rate_limited`: límite de peticiones superado. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

Ejemplo de respuesta `200`:

```json
{
  "apiVersion" : "v1",
  "tenantId" : "3b0f6c1e-7a2d-4e8b-9c5f-1d2e3f4a5b6c",
  "keyName" : "Integración pruebas",
  "environment" : "TEST",
  "scopes" : [ "events:read", "grants:read", "grants:write", "members:read", "members:write" ],
  "serverTime" : "2026-11-12T17:03:11.482Z"
}
```

## Socios

Los socios del centro que gestionas desde tu programa. Cada uno se identifica con **tu** `externalId`.

#### Alta y actualización

`PUT /members/{externalId}` crea al socio (`201`) o lo actualiza (`200`):

- Al crear, `firstName` es obligatorio; el resto de datos son opcionales.
- Al actualizar, **solo cambian los campos que envías**. Un campo ausente se queda como está; uno enviado como `null` se borra (salvo `firstName`, que no se puede borrar).
- El email no puede tenerlo otro usuario habilitado del centro (`409 conflict`). El socio no recibe correos de Fitnova ni tiene contraseña: no entra en las apps de Fitnova.

```bash
curl -X PUT https://dev-developers.fitnova.eu/integrations/v1/members/socio-1042 \
  -H "X-API-Key: fnv_test_Xq3vN8bT2kLw9RmZ5cYh7JpD4sGf6AeU1oQiWn0VzKx" \
  -H "Content-Type: application/json" \
  -d '{"firstName": "Lucía", "lastName": "Martín Sanz", "email": "lucia.martin@example.com",
       "birthDate": "1990-04-17", "photoUrl": "https://cdn.example.com/socios/1042.jpg"}'
```

#### Habilitar, deshabilitar, dar de baja y reactivar

| Quieres… | Llamada | Qué pasa |
|---|---|---|
| Bloquear temporalmente (impago, sanción) | `PUT` con `"enabled": false` | El socio deja de entrar al momento. Sus permisos **no** se revocan: siguen guardados. |
| Desbloquear | `PUT` con `"enabled": true` | Vuelve a entrar con los permisos que tenía. |
| Dar de baja | `DELETE /members/{externalId}` | Queda deshabilitado, se le quitan las tarjetas, se **revocan** todos sus permisos y deja de valer su QR. |
| Reactivar tras una baja | `PUT` con `"enabled": true` y después `PUT` de sus permisos | El socio vuelve; sus permisos revocados no vuelven solos. |

`enabled` ausente al actualizar no cambia nada: un socio deshabilitado o de baja **solo** se reactiva con `"enabled": true` explícito. Así, una actualización de datos (un cambio de teléfono) nunca reactiva a nadie por accidente.

Si el centro ha dado a un usuario creado por la API un rol de personal (monitor, recepción…), deja de ser gestionable por la API: sus llamadas responden `409 conflict`.

#### Foto

Envía `photoUrl` con una URL `https` pública de una imagen JPEG o PNG (hasta 5 MB y 12 megapíxeles). Fitnova la descarga en segundo plano, la reduce a 1600 px de lado mayor como mucho y la guarda (sin metadatos) como foto del socio.

- `photoUrl` ausente: no se toca la foto. `null`: se quita. La misma URL que ya está descargada o descargándose no se vuelve a descargar; si había fallado, sí.
- El resultado se ve en `photo.status` de la respuesta y de `GET /members/{externalId}`: `pending` (descargándose), `ready` o `failed` con el motivo en `photo.error`. Si falla, corrige la imagen y vuelve a enviar la URL.
- No se admiten direcciones internas ni redirecciones; la descarga tiene 10 s de tiempo máximo. Si una descarga no termina en 10 minutos pasa a `failed`.

Motivos de fallo habituales: `No se ha podido acceder a la URL`, `El servidor respondió con el estado 404`, `El servidor respondió con una redirección y no se siguen`, `El tipo de contenido no es image/jpeg ni image/png`, `El formato WebP no está admitido: usa JPEG o PNG`, `La imagen supera los 5 MB`, `La descarga ha tardado demasiado`, `Demasiadas fotos en proceso; reenvía la URL más tarde`.

#### Listado

`GET /members` devuelve los socios creados por la API (también los de baja), en orden de alta y paginados con cursor. Para una sincronización completa, recórrelo hasta `nextCursor: null`.

### `GET /integrations/v1/members` — Listar socios

`operationId`: `listMembers`

Socios creados por la API (no los que el centro tuviera antes), en orden de alta y paginados con cursor: pide la siguiente página con `cursor=nextCursor` hasta que `nextCursor` sea `null`.

**Scope requerido:** `members:read`

**Parámetros**

| Nombre | En | Obligatorio | Tipo | Descripción |
|---|---|---|---|---|
| `limit` | query | no | integer | Tamaño de página, de 1 a 100. Por defecto: `50`. Rango: 1–100. |
| `cursor` | query | no | string | El `nextCursor` de la página anterior; sin él, desde el principio. |

**Respuestas**

- `200`: Una página de socios. Cuerpo: `PageResponseMember`.
- `400`: `bad_request`: `cursor` no válido. Cuerpo: `ApiError`.
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden` (a la clave le falta el scope de la operación), `ip_not_allowed` (la IP de origen no está en la lista de la clave) o `tenant_not_external` (el centro no está en gestión externa). Cuerpo: `ApiError`.
- `422`: `validation_error`: `limit` fuera de 1–100. Cuerpo: `ApiError`.
- `429`: `rate_limited`: límite de peticiones superado. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

### `GET /integrations/v1/members/{externalId}` — Consultar un socio

`operationId`: `getMember`

Devuelve el socio, también si está de baja (`enabled: false`), con sus tarjetas RFID y el estado de la foto.

**Scope requerido:** `members:read`

**Parámetros**

| Nombre | En | Obligatorio | Tipo | Descripción |
|---|---|---|---|---|
| `externalId` | path | sí | string | Tu identificador del socio. Ejemplo: `socio-1042`. |

**Respuestas**

- `200`: El socio. Cuerpo: `Member`.
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden` (a la clave le falta el scope de la operación), `ip_not_allowed` (la IP de origen no está en la lista de la clave) o `tenant_not_external` (el centro no está en gestión externa). Cuerpo: `ApiError`.
- `404`: `not_found`: no hay ningún socio con ese `externalId`. Cuerpo: `ApiError`.
- `422`: `validation_error`: `externalId` con formato no válido. Cuerpo: `ApiError`.
- `429`: `rate_limited`: límite de peticiones superado. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

### `PUT /integrations/v1/members/{externalId}` — Crear o actualizar un socio

`operationId`: `upsertMember`

Alta o actualización del socio identificado por **tu** `externalId` (upsert idempotente: repetir la misma petición no duplica nada).

- **Alta**: `firstName` es obligatorio. `enabled` ausente = `true`.
- **Actualización**: solo cambian los campos que envías; un campo enviado como `null` se borra (salvo `firstName`). `enabled` ausente = no cambia.
- **Reactivar** a un socio dado de baja o deshabilitado: envía `"enabled": true` de forma explícita.
- `enabled: false` retira al momento sus accesos del torno sin revocar sus permisos; `enabled: true` se los devuelve.
- `photoUrl` (https) se descarga en segundo plano: mira `photo.status` en la respuesta o en `GET /members/{externalId}`.

El torno recibe los cambios en segundos (y, en todo caso, en su siguiente sincronización).

**Scope requerido:** `members:write`

**Parámetros**

| Nombre | En | Obligatorio | Tipo | Descripción |
|---|---|---|---|---|
| `externalId` | path | sí | string | Tu identificador del socio: 1–100 caracteres `[A-Za-z0-9._:-]`. Ejemplo: `socio-1042`. |

**Cuerpo de la petición** (obligatorio): `MemberRequest`

**Respuestas**

- `200`: Socio actualizado (o reactivado). Cuerpo: `Member`.
- `201`: Socio creado. Cuerpo: `Member`.
- `400`: `bad_request`: JSON ilegible, parámetro con formato incorrecto o `cursor` no válido. Cuerpo: `ApiError`.
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden` (a la clave le falta el scope de la operación), `ip_not_allowed` (la IP de origen no está en la lista de la clave) o `tenant_not_external` (el centro no está en gestión externa). Cuerpo: `ApiError`.
- `409`: `conflict`: el email ya lo usa otro usuario habilitado del centro, o el usuario tiene ahora un rol de personal y ya no es gestionable por la API. Cuerpo: `ApiError`.
- `413`: `payload_too_large`: el cuerpo supera 2 MB. Cuerpo: `ApiError`.
- `422`: `validation_error`: `externalId` con formato no válido, falta `firstName` en el alta, fecha, email o `photoUrl` no válidos… Cuerpo: `ApiError`.
- `429`: `rate_limited`: límite de peticiones superado. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

### `DELETE /integrations/v1/members/{externalId}` — Dar de baja a un socio

`operationId`: `deleteMember`

Baja del socio: queda deshabilitado, se le quitan las tarjetas RFID, se revocan todos sus permisos de acceso y deja de valer su código QR. El torno lo recibe al momento.

Idempotente: `204` también si ya estaba de baja. Se conserva su `externalId`: para reactivarlo, `PUT /members/{externalId}` con `"enabled": true`; sus permisos no vuelven solos: envíalos otra vez con `PUT /access-grants/{externalId}`.

**Scope requerido:** `members:write`

**Parámetros**

| Nombre | En | Obligatorio | Tipo | Descripción |
|---|---|---|---|---|
| `externalId` | path | sí | string | Tu identificador del socio. Ejemplo: `socio-1042`. |

**Respuestas**

- `204`: Socio dado de baja.
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden` (a la clave le falta el scope de la operación), `ip_not_allowed` (la IP de origen no está en la lista de la clave) o `tenant_not_external` (el centro no está en gestión externa). Cuerpo: `ApiError`.
- `404`: `not_found`: el socio nunca ha existido. Cuerpo: `ApiError`.
- `409`: `conflict`: el usuario tiene ahora un rol de personal y ya no es gestionable por la API. Cuerpo: `ApiError`.
- `422`: `validation_error`: `externalId` con formato no válido. Cuerpo: `ApiError`.
- `429`: `rate_limited`: límite de peticiones superado. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

## Tarjetas RFID

Tarjetas y pulseras RFID con las que el socio se identifica en los lectores.

- El número se envía en **decimal** en la ruta: `PUT /members/socio-1042/credentials/rfid/4000000001`. Es el formato con el que se guarda y el que verás en `rfids` del socio.
- Si tu sistema guarda el UID EM en hexadecimal (10 caracteres con alguna letra, como `4E001D8F8A`), puedes enviarlo tal cual: se convierte a decimal (`335009386378`). Un valor solo de dígitos se interpreta siempre como decimal.
- Un socio puede tener varias tarjetas. Asignar una tarjeta que ya es suya, o quitar una que no tiene, responde `204` sin cambios.
- Una tarjeta no puede ser de dos usuarios del centro: si la tiene otro, `409 conflict`. Para pasarla de un socio a otro, quítasela primero al anterior.
- La baja del socio (`DELETE /members/{externalId}`) le quita todas sus tarjetas.
- El torno recibe los cambios en segundos.

### `PUT /integrations/v1/members/{externalId}/credentials/rfid/{rfidNumber}` — Asignar una tarjeta RFID

`operationId`: `assignRfid`

Asigna la tarjeta al socio. Idempotente: si ya era suya no cambia nada. Un socio puede tener varias tarjetas. No hay traspasos automáticos: si la tarjeta la tiene otro usuario del centro responde `409`; para moverla, quítasela antes a ese socio con `DELETE`.

**Scope requerido:** `credentials:write`

**Parámetros**

| Nombre | En | Obligatorio | Tipo | Descripción |
|---|---|---|---|---|
| `externalId` | path | sí | string | Tu identificador del socio. Ejemplo: `socio-1042`. |
| `rfidNumber` | path | sí | string | Número de la tarjeta en decimal (hasta 18 dígitos, mayor que cero), p. ej. `4000000001`. También se admite el UID EM de 10 caracteres hexadecimales con alguna letra (`4E001D8F8A` = `335009386378`); un valor solo de dígitos se toma siempre como decimal. Ejemplo: `4000000001`. |

**Respuestas**

- `204`: Tarjeta asignada.
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden` (a la clave le falta el scope de la operación), `ip_not_allowed` (la IP de origen no está en la lista de la clave) o `tenant_not_external` (el centro no está en gestión externa). Cuerpo: `ApiError`.
- `404`: `not_found`: el socio no existe o está de baja. Cuerpo: `ApiError`.
- `409`: `conflict`: la tarjeta ya está asignada a otro usuario del centro, o el usuario tiene un rol de personal y no es gestionable por la API. Cuerpo: `ApiError`.
- `422`: `validation_error`: número de tarjeta o `externalId` no válidos. Cuerpo: `ApiError`.
- `429`: `rate_limited`: límite de peticiones superado. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

### `DELETE /integrations/v1/members/{externalId}/credentials/rfid/{rfidNumber}` — Quitar una tarjeta RFID

`operationId`: `removeRfid`

Quita la tarjeta al socio. Idempotente: `204` también si no la tenía.

**Scope requerido:** `credentials:write`

**Parámetros**

| Nombre | En | Obligatorio | Tipo | Descripción |
|---|---|---|---|---|
| `externalId` | path | sí | string | Tu identificador del socio. Ejemplo: `socio-1042`. |
| `rfidNumber` | path | sí | string | Número de la tarjeta en decimal (o UID hexadecimal). Ejemplo: `4000000001`. |

**Respuestas**

- `204`: Tarjeta quitada (o no la tenía).
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden` (a la clave le falta el scope de la operación), `ip_not_allowed` (la IP de origen no está en la lista de la clave) o `tenant_not_external` (el centro no está en gestión externa). Cuerpo: `ApiError`.
- `404`: `not_found`: el socio no existe o está de baja. Cuerpo: `ApiError`.
- `409`: `conflict`: el usuario tiene un rol de personal y no es gestionable por la API. Cuerpo: `ApiError`.
- `422`: `validation_error`: número de tarjeta o `externalId` no válidos. Cuerpo: `ApiError`.
- `429`: `rate_limited`: límite de peticiones superado. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

## Código QR

Tu app móvil puede mostrar al socio un **QR de 9 dígitos que cambia cada 15 segundos** y que los lectores del centro aceptan, sin conexión y sin que tu app conozca ningún secreto del centro. El esquema se llama `fnv-qr-v1`.

**Requisito:** el centro debe tener activado el *QR para gestores externos* (esquema `PARTNER_V1`). Lo activa Fitnova; mientras no esté activado, estas llamadas responden `409 conflict`. Un centro usa este QR o el de la app de Fitnova, no los dos.

#### Flujo

1. Tu servidor pide el secreto del socio: `POST /members/{externalId}/credentials/qr-secret` (scope `credentials:qr`).

   ```json
   { "accessCode": "00042", "secret": "Dgr0OWxS3gdo_UFIbh0ZDnIWYCxqMqfrExhW1j766AE",
     "algorithm": "fnv-qr-v1", "stepSeconds": 15, "digits": 9 }
   ```

2. Se lo entregas a la app del socio por tu canal autenticado. La app lo guarda en el almacenamiento seguro del dispositivo (Keychain, Keystore).
3. La app genera el QR **sin conexión** con el algoritmo de abajo y lo muestra; lo regenera cada vez que cambia el paso de 15 s.
4. El lector lo lee y el programa de tornos lo valida en local.

Pedir el secreto es idempotente: devuelve siempre el mismo mientras no se rote. Trata el secreto como una contraseña: con él se pueden generar los QR del socio.

#### Algoritmo `fnv-qr-v1`

Entradas: `accessCode` (5 dígitos, texto) y `secret` (base64url sin relleno → 32 bytes).

1. `step = floor(unixSeconds / 15)`, con `unixSeconds` = segundos Unix en UTC (no depende de la zona horaria).
2. `sig = HMAC-SHA256(clave = secret decodificado, mensaje = step como entero sin signo de 8 bytes big-endian)`.
3. Truncado dinámico (como TOTP, RFC 4226): `offset = sig[31] & 0x0f`;
   `bin = (sig[offset] & 0x7f) << 24 | sig[offset+1] << 16 | sig[offset+2] << 8 | sig[offset+3]`.
4. `code4 = bin % 10000`, con ceros a la izquierda hasta 4 dígitos.
5. **QR = `accessCode` + `code4`** (9 dígitos), p. ej. `000421401`.

El QR contiene solo esos 9 dígitos, como texto. El lector acepta el paso actual y los dos contiguos (±15 s), así que el reloj del móvil puede desviarse unos segundos; si se desvía más, el QR no valdrá. Sincroniza con `serverTime` de `GET /ping` si tus usuarios tienen relojes poco fiables.

#### Vectores de prueba

Con estos datos tu implementación debe dar exactamente estos códigos:

| `accessCode` | `secret` | `unixSeconds` | QR |
|---|---|---|---|
| `00042` | `Dgr0OWxS3gdo_UFIbh0ZDnIWYCxqMqfrExhW1j766AE` | `1794500000` | `000421401` |
| `00042` | `Dgr0OWxS3gdo_UFIbh0ZDnIWYCxqMqfrExhW1j766AE` | `1794500014` | `000429959` |
| `00001` | `WGizjlCB3t7XfZKgwcqe729_7LOwr8FG59vh6uoiq9k` | `1794500000` | `000019508` |
| `99999` | `kYoYl2zuuPN53i4ITXXjej_wtYZamPj7x8qOMlPu_50` | `1794500000` | `999993723` |

#### Reglas del lector

- Cada código vale **una sola vez**: si el socio necesita volver a pasar enseguida, debe esperar al siguiente código (como mucho 15 s).
- Tras 5 QR con firma incorrecta del mismo `accessCode` en un minuto, sus QR se rechazan durante 60 s.
- Tras 20 lecturas fallidas en un minuto en un mismo lector, ese lector rechaza todos los QR durante 60 s.
- Solo vale para socios habilitados. El QR es solo la identificación: el socio necesita además un permiso de acceso vigente para pasar.

#### Rotación

- **Socio** (móvil perdido o robado): `POST /members/{externalId}/credentials/qr-secret/rotate`. Le asigna un `accessCode` y un secreto nuevos; los QR anteriores dejan de valer al momento en el servidor y en unos 20 s en los tornos con conexión (un torno sin conexión los acepta hasta que la recupera). Como mucho 10 rotaciones por socio y día.
- **Centro** (incidente de seguridad): la hace Fitnova. Invalida los secretos de todos los socios: vuelve a pedirlos con `POST …/qr-secret` y entrégalos a las apps.
- La baja del socio invalida su QR.

#### Ejemplos de generación

Todos reproducen los vectores de prueba de arriba. `accessCode` y `secret` son los de `POST …/qr-secret`.

##### JavaScript / TypeScript (app móvil, navegador, Node.js)

Usa Web Crypto (`crypto.subtle`), disponible en navegadores y en Node.js 18+. En React Native, instala un polyfill de `crypto.subtle` (por ejemplo `react-native-quick-crypto`) o sustituye `hmacSha256` por una implementación en JavaScript puro como `hmac(sha256, key, message)` de `@noble/hashes`.

```ts
const B64URL = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';

/** Decodifica base64url (con o sin relleno) sin depender de atob ni de Buffer. */
function base64UrlToBytes(text: string): Uint8Array {
  const out: number[] = [];
  let buffer = 0;
  let bits = 0;
  for (const ch of text.replace(/=+$/, '')) {
    const value = B64URL.indexOf(ch);
    if (value < 0) throw new Error('El secreto no es base64url');
    buffer = ((buffer << 6) | value) & 0xffff;
    bits += 6;
    if (bits >= 8) {
      bits -= 8;
      out.push((buffer >> bits) & 0xff);
    }
  }
  return new Uint8Array(out);
}

async function hmacSha256(key: Uint8Array, message: Uint8Array): Promise<Uint8Array> {
  const cryptoKey = await crypto.subtle.importKey('raw', key, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
  return new Uint8Array(await crypto.subtle.sign('HMAC', cryptoKey, message));
}

/** QR fnv-qr-v1 del socio (9 dígitos). */
export async function fitnovaQr(accessCode: string, secret: string,
    unixSeconds: number = Math.floor(Date.now() / 1000)): Promise<string> {
  if (!/^\d{5}$/.test(accessCode)) throw new Error('accessCode debe tener 5 dígitos');
  const step = Math.floor(unixSeconds / 15);
  const message = new Uint8Array(8); // step como entero de 8 bytes big-endian
  const view = new DataView(message.buffer);
  view.setUint32(0, Math.floor(step / 2 ** 32));
  view.setUint32(4, step >>> 0);
  const sig = await hmacSha256(base64UrlToBytes(secret), message);
  const offset = sig[31] & 0x0f;
  const bin = ((sig[offset] & 0x7f) << 24) | (sig[offset + 1] << 16) | (sig[offset + 2] << 8) | sig[offset + 3];
  return accessCode + String(bin % 10000).padStart(4, '0');
}

/** Segundos que faltan para que cambie el código: para refrescar el QR justo a tiempo. */
export function secondsToNextQr(unixSeconds: number = Math.floor(Date.now() / 1000)): number {
  return 15 - (unixSeconds % 15);
}

// await fitnovaQr('00042', 'Dgr0OWxS3gdo_UFIbh0ZDnIWYCxqMqfrExhW1j766AE', 1794500000) === '000421401'
```

##### Kotlin (Android)

```kotlin
import java.nio.ByteBuffer
import java.util.Base64
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec

/** QR fnv-qr-v1 del socio (9 dígitos). */
fun fitnovaQr(accessCode: String, secret: String,
              unixSeconds: Long = System.currentTimeMillis() / 1000): String {
    require(accessCode.length == 5 && accessCode.all { it in '0'..'9' }) { "accessCode debe tener 5 dígitos" }
    // java.util.Base64 necesita Android 8 (API 26); antes, usa
    // android.util.Base64.decode(secret, Base64.URL_SAFE or Base64.NO_PADDING or Base64.NO_WRAP).
    val key = Base64.getUrlDecoder().decode(secret)
    val step = Math.floorDiv(unixSeconds, 15L)
    val mac = Mac.getInstance("HmacSHA256").apply { init(SecretKeySpec(key, "HmacSHA256")) }
    val sig = mac.doFinal(ByteBuffer.allocate(8).putLong(step).array()) // 8 bytes big-endian
    val offset = sig[31].toInt() and 0x0f
    val bin = ((sig[offset].toInt() and 0x7f) shl 24) or
        ((sig[offset + 1].toInt() and 0xff) shl 16) or
        ((sig[offset + 2].toInt() and 0xff) shl 8) or
        (sig[offset + 3].toInt() and 0xff)
    return accessCode + (bin % 10000).toString().padStart(4, '0')
}

// fitnovaQr("00042", "Dgr0OWxS3gdo_UFIbh0ZDnIWYCxqMqfrExhW1j766AE", 1794500000) == "000421401"
```

##### Swift (iOS)

```swift
import CryptoKit
import Foundation

/// QR fnv-qr-v1 del socio (9 dígitos).
func fitnovaQr(accessCode: String, secret: String, date: Date = Date()) -> String? {
    guard accessCode.count == 5, accessCode.allSatisfy({ $0.isASCII && $0.isNumber }),
          let key = base64UrlDecode(secret) else { return nil }
    let step = UInt64(floor(date.timeIntervalSince1970 / 15))
    var bigEndian = step.bigEndian // 8 bytes big-endian
    let message = withUnsafeBytes(of: &bigEndian) { Data($0) }
    let sig = Array(HMAC<SHA256>.authenticationCode(for: message, using: SymmetricKey(data: key)))
    let offset = Int(sig[31] & 0x0f)
    let bin = (UInt32(sig[offset] & 0x7f) << 24) | (UInt32(sig[offset + 1]) << 16)
        | (UInt32(sig[offset + 2]) << 8) | UInt32(sig[offset + 3])
    let code = String(bin % 10000)
    return accessCode + String(repeating: "0", count: 4 - code.count) + code
}

func base64UrlDecode(_ text: String) -> Data? {
    var base64 = text.replacingOccurrences(of: "-", with: "+").replacingOccurrences(of: "_", with: "/")
    while base64.count % 4 != 0 { base64 += "=" }
    return Data(base64Encoded: base64)
}

// fitnovaQr(accessCode: "00042", secret: "Dgr0OWxS3gdo_UFIbh0ZDnIWYCxqMqfrExhW1j766AE",
//           date: Date(timeIntervalSince1970: 1794500000)) == "000421401"
```

##### Python

```python
import base64
import hashlib
import hmac
import struct
import time

def fitnova_qr(access_code, secret, unix_seconds=None):
    """QR fnv-qr-v1 del socio (9 dígitos)."""
    if len(access_code) != 5 or not (access_code.isascii() and access_code.isdigit()):
        raise ValueError("access_code debe tener 5 dígitos")
    if unix_seconds is None:
        unix_seconds = int(time.time())
    key = base64.urlsafe_b64decode(secret + "=" * (-len(secret) % 4))
    step = unix_seconds // 15
    sig = hmac.new(key, struct.pack(">Q", step), hashlib.sha256).digest()  # 8 bytes big-endian
    offset = sig[31] & 0x0F
    code = ((sig[offset] & 0x7F) << 24 | sig[offset + 1] << 16 | sig[offset + 2] << 8 | sig[offset + 3]) % 10000
    return access_code + "%04d" % code

# fitnova_qr("00042", "Dgr0OWxS3gdo_UFIbh0ZDnIWYCxqMqfrExhW1j766AE", 1794500000) == "000421401"
```

### `POST /integrations/v1/members/{externalId}/credentials/qr-secret` — Obtener el secreto QR de un socio

`operationId`: `getQrSecret`

Devuelve el código de acceso (5 dígitos) y el secreto del socio para que tu app genere el QR `fnv-qr-v1` sin conexión. La primera vez le asigna un código; después devuelve siempre el mismo secreto (mientras no se rote el del socio o el del centro). No gasta cupo de rotaciones. Guárdalo solo en el dispositivo del socio: con él se pueden generar sus QR.

**Scope requerido:** `credentials:qr`

**Parámetros**

| Nombre | En | Obligatorio | Tipo | Descripción |
|---|---|---|---|---|
| `externalId` | path | sí | string | Tu identificador del socio. Ejemplo: `socio-1042`. |

**Respuestas**

- `200`: Código de acceso y secreto del socio. Cuerpo: `QrSecret`.
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden` (a la clave le falta el scope de la operación), `ip_not_allowed` (la IP de origen no está en la lista de la clave) o `tenant_not_external` (el centro no está en gestión externa). Cuerpo: `ApiError`.
- `404`: `not_found`: el socio no existe o está de baja. Cuerpo: `ApiError`.
- `409`: `conflict`: el centro no tiene activado el QR para gestores externos (`PARTNER_V1`; lo activa Fitnova) o ha agotado los 99.999 códigos. Cuerpo: `ApiError`.
- `422`: `validation_error`: `externalId` con formato no válido. Cuerpo: `ApiError`.
- `429`: `rate_limited`: límite de peticiones superado. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

### `POST /integrations/v1/members/{externalId}/credentials/qr-secret/rotate` — Rotar el secreto QR de un socio

`operationId`: `rotateQrSecret`

Asigna al socio un código de acceso y un secreto nuevos (p. ej. si pierde el móvil): los QR del anterior dejan de valer al momento en el servidor y en unos 20 s en los tornos con conexión. Como mucho 10 rotaciones por socio y día (hora de Madrid); la undécima responde `429` con `Retry-After` hasta medianoche.

**Scope requerido:** `credentials:qr`

**Parámetros**

| Nombre | En | Obligatorio | Tipo | Descripción |
|---|---|---|---|---|
| `externalId` | path | sí | string | Tu identificador del socio. Ejemplo: `socio-1042`. |

**Respuestas**

- `200`: Código de acceso y secreto nuevos. Cuerpo: `QrSecret`.
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden` (a la clave le falta el scope de la operación), `ip_not_allowed` (la IP de origen no está en la lista de la clave) o `tenant_not_external` (el centro no está en gestión externa). Cuerpo: `ApiError`.
- `404`: `not_found`: el socio no existe o está de baja. Cuerpo: `ApiError`.
- `409`: `conflict`: el centro no tiene activado `PARTNER_V1` o ha agotado los códigos. Cuerpo: `ApiError`.
- `422`: `validation_error`: `externalId` con formato no válido. Cuerpo: `ApiError`.
- `429`: `rate_limited`: límite de peticiones de la clave o más de 10 rotaciones del socio hoy. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

## Perfiles de acceso

Un perfil de acceso dice **por qué tornos** puede pasar un socio: *Sala*, *Piscina*, *Sala + Piscina*… Los crea y configura Fitnova con el centro; tú solo los usas.

`GET /access-profiles` devuelve los perfiles habilitados con su `code` (lo que envías en `accessProfile` al conceder un permiso) y su nombre. Si necesitas un perfil nuevo, pídelo a Fitnova.

Si Fitnova deshabilita un perfil, no se pueden conceder permisos nuevos con él (`422`).

### `GET /integrations/v1/access-profiles` — Listar perfiles de acceso

`operationId`: `listAccessProfiles`

Perfiles habilitados del centro: el `code` es lo que envías en `accessProfile` al conceder un permiso. Los crea y configura Fitnova (qué tornos abre cada uno). Van siempre en una sola página (`nextCursor: null`).

**Scope requerido:** `grants:read`

**Respuestas**

- `200`: Los perfiles habilitados. Cuerpo: `PageResponseAccessProfile`.
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden` (a la clave le falta el scope de la operación), `ip_not_allowed` (la IP de origen no está en la lista de la clave) o `tenant_not_external` (el centro no está en gestión externa). Cuerpo: `ApiError`.
- `429`: `rate_limited`: límite de peticiones superado. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

## Permisos de acceso

Un permiso dice que **un socio, con un perfil de acceso, puede entrar en unos momentos**. Lo identificas con tu propio `externalId` (por ejemplo, el id de la cuota o de la reserva en tu programa). Un socio puede tener varios permisos a la vez: varios perfiles, varias ventanas.

Tú decides las reglas (cuotas, bonos, horarios, reservas) y nos mandas el resultado. Cuando el socio ya no deba entrar, retiras el permiso.

#### Tipos

| `type` | Campos | Uso típico |
|---|---|---|
| `CONTINUOUS` | `start`, `end` | Cuota o abono: puede entrar en cualquier momento entre `start` y `end`. |
| `WINDOW` | `start`, `end` | Ventana puntual: la de una clase reservada o una sesión de entrenamiento. Tú eliges los márgenes (p. ej. 15 min antes y después). |
| `DAY_PASS` | `date` | Pase de un día: de las 00:00 a las 24:00 de ese día en hora de Madrid. |
| `SCHEDULED` | `start`, `end`, `weeklySlots`, `timeZone` | Abono con horario: solo en las franjas semanales, dentro de la vigencia `start`–`end`. |

`start` y `end` son instantes ISO-8601 con zona o desfase; `end` es excluido y debe ser posterior a `start`. Todos los tipos admiten `dailyEntryLimit`.

#### Franjas semanales (`SCHEDULED`)

```json
{
  "memberExternalId": "socio-1042",
  "accessProfile": "sala",
  "type": "SCHEDULED",
  "start": "2026-11-01T00:00:00Z",
  "end": "2027-01-01T00:00:00Z",
  "timeZone": "Europe/Madrid",
  "weeklySlots": [
    { "day": "MONDAY", "from": "07:00", "to": "15:00" },
    { "day": "WEDNESDAY", "from": "07:00", "to": "15:00" },
    { "day": "FRIDAY", "from": "22:00", "to": "02:00" }
  ]
}
```

- De 1 a 28 franjas. `day` de `MONDAY` a `SUNDAY`; `from` y `to` en `HH:mm`, en hora local de `timeZone` (zona IANA; por defecto `Europe/Madrid`). Los cambios de hora de marzo y octubre se tienen en cuenta.
- Si `to` es menor o igual que `from`, la franja termina al día siguiente (la del viernes de arriba acaba el sábado a las 02:00). `from` igual a `to` no se admite.
- Las franjas no pueden solaparse, tampoco entre días distintos (la cola de una que cruza la medianoche cuenta en el día siguiente, y la del domingo en el lunes). Las contiguas sí se admiten.
- El torno tiene siempre las franjas de los próximos 14 días, así que sigue funcionando aunque se quede sin conexión ese tiempo.

#### Límite de entradas diarias

`dailyEntryLimit` (de 1 a 50) limita cuántas veces puede **entrar** el socio en un día natural (hora de Madrid). Ausente o `null`: sin límite.

- Se cuentan las entradas del socio, no las de cada permiso: si tiene otro permiso vigente sin límite, entra con ese.
- Al agotar las entradas del día deja de poder entrar hasta el día siguiente. Mientras está dentro conserva el acceso de hoy, para poder salir.
- El torno informa de cada entrada al pasar; si el socio pasa varias veces casi a la vez, el límite se aplica en cuanto llegan esos avisos (normalmente segundos).

#### Sustituir, retirar y revocar

- `PUT` sobre un permiso existente lo **sustituye entero** (envía siempre todos los campos). También sirve para pasarlo a otro socio, cambiar de perfil o de tipo.
- Para quitar el acceso: `DELETE /access-grants/{externalId}` (queda `REVOKED`) o un `PUT` con `end` en el pasado. Un `PUT` sobre un permiso revocado lo vuelve a activar.
- Al **deshabilitar** al socio (`enabled: false`) sus permisos dejan de valer en el torno sin revocarse, y vuelven al habilitarlo.
- Al **dar de baja** al socio se revocan todos sus permisos.
- No se pueden conceder permisos a un socio de baja ni con un perfil deshabilitado (`422`).

#### Bonos de sesiones

El contador de sesiones es tuyo. Recibe cada entrada por webhook (`access.entry`), descuenta la sesión en tu programa y, al agotarse el bono, **retira el permiso**. Si el socio está dentro cuando lo retiras, el torno le deja salir: la salida de emergencia es del propio torno.

#### Cuándo llega al torno

El programa de tornos recibe cada alta, cambio o retirada **en segundos**. Si en ese momento no tiene conexión, lo recoge en su siguiente sincronización completa (cada pocos minutos), que es además la que manda: lo que no viene en ella se borra del torno.

### `GET /integrations/v1/access-grants` — Listar permisos de acceso

`operationId`: `listAccessGrants`

Todos los permisos (activos y revocados) en orden de alta, paginados con cursor. Con `memberExternalId`, solo los de ese socio (lista vacía si el socio no existe).

**Scope requerido:** `grants:read`

**Parámetros**

| Nombre | En | Obligatorio | Tipo | Descripción |
|---|---|---|---|---|
| `memberExternalId` | query | no | string | Solo los permisos de este socio (tu `externalId`). |
| `limit` | query | no | integer | Tamaño de página, de 1 a 100. Por defecto: `50`. Rango: 1–100. |
| `cursor` | query | no | string | El `nextCursor` de la página anterior; sin él, desde el principio. |

**Respuestas**

- `200`: Una página de permisos. Cuerpo: `PageResponseAccessGrant`.
- `400`: `bad_request`: `cursor` no válido. Cuerpo: `ApiError`.
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden` (a la clave le falta el scope de la operación), `ip_not_allowed` (la IP de origen no está en la lista de la clave) o `tenant_not_external` (el centro no está en gestión externa). Cuerpo: `ApiError`.
- `422`: `validation_error`: `limit` fuera de 1–100 o `memberExternalId` con formato no válido. Cuerpo: `ApiError`.
- `429`: `rate_limited`: límite de peticiones superado. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

### `GET /integrations/v1/access-grants/{externalId}` — Consultar un permiso de acceso

`operationId`: `getAccessGrant`

Devuelve el permiso, también si está revocado (`status: REVOKED`).

**Scope requerido:** `grants:read`

**Parámetros**

| Nombre | En | Obligatorio | Tipo | Descripción |
|---|---|---|---|---|
| `externalId` | path | sí | string | Tu identificador del permiso. Ejemplo: `cuota-2026-11-socio-1042`. |

**Respuestas**

- `200`: El permiso. Cuerpo: `AccessGrant`.
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden` (a la clave le falta el scope de la operación), `ip_not_allowed` (la IP de origen no está en la lista de la clave) o `tenant_not_external` (el centro no está en gestión externa). Cuerpo: `ApiError`.
- `404`: `not_found`: no hay ningún permiso con ese `externalId`. Cuerpo: `ApiError`.
- `422`: `validation_error`: `externalId` con formato no válido. Cuerpo: `ApiError`.
- `429`: `rate_limited`: límite de peticiones superado. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

### `PUT /integrations/v1/access-grants/{externalId}` — Conceder o sustituir un permiso de acceso

`operationId`: `upsertAccessGrant`

Crea el permiso identificado por **tu** `externalId` o lo sustituye entero (el `PUT` reemplaza todos los campos). Un permiso revocado vuelve a estar activo al enviarlo otra vez.

Tipos:
- `CONTINUOUS` y `WINDOW`: de `start` a `end` (ISO-8601 con zona o desfase).
- `DAY_PASS`: el día natural `date` (`yyyy-MM-dd`) en hora de Madrid.
- `SCHEDULED`: vigencia `start`–`end` y de 1 a 28 franjas semanales `weeklySlots` en la zona `timeZone` (por defecto `Europe/Madrid`). Una franja con `to <= from` cruza la medianoche; no se admiten franjas solapadas.

`dailyEntryLimit` (1–50, opcional) limita las entradas por día natural de Madrid.

Para retirar un acceso: `DELETE` o un `PUT` con `end` en el pasado. El torno recibe los cambios en segundos y, en todo caso, en su siguiente sincronización.

**Scope requerido:** `grants:write`

**Parámetros**

| Nombre | En | Obligatorio | Tipo | Descripción |
|---|---|---|---|---|
| `externalId` | path | sí | string | Tu identificador del permiso: 1–100 caracteres `[A-Za-z0-9._:-]`. Ejemplo: `cuota-2026-11-socio-1042`. |

**Cuerpo de la petición** (obligatorio): `AccessGrantRequest`

*Cuota mensual*

```json
{
  "memberExternalId" : "socio-1042",
  "accessProfile" : "sala",
  "type" : "CONTINUOUS",
  "start" : "2026-11-01T00:00:00+01:00",
  "end" : "2026-12-01T00:00:00+01:00"
}
```

*Mañanas de lunes a viernes*

```json
{
  "memberExternalId" : "socio-1042",
  "accessProfile" : "sala",
  "type" : "SCHEDULED",
  "start" : "2026-11-01T00:00:00Z",
  "end" : "2027-01-01T00:00:00Z",
  "timeZone" : "Europe/Madrid",
  "weeklySlots" : [ {
    "day" : "MONDAY",
    "from" : "07:00",
    "to" : "15:00"
  }, {
    "day" : "FRIDAY",
    "from" : "22:00",
    "to" : "02:00"
  } ],
  "dailyEntryLimit" : 1
}
```

*Ventana de una clase reservada*

```json
{
  "memberExternalId" : "socio-1042",
  "accessProfile" : "piscina",
  "type" : "WINDOW",
  "start" : "2026-11-20T17:45:00Z",
  "end" : "2026-11-20T19:15:00Z"
}
```

*Pase de un día*

```json
{
  "memberExternalId" : "socio-1042",
  "accessProfile" : "sala",
  "type" : "DAY_PASS",
  "date" : "2026-11-21"
}
```

**Respuestas**

- `200`: Permiso sustituido (o reactivado). Cuerpo: `AccessGrant`.
- `201`: Permiso creado. Cuerpo: `AccessGrant`.
- `400`: `bad_request`: JSON ilegible, parámetro con formato incorrecto o `cursor` no válido. Cuerpo: `ApiError`.
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden` (a la clave le falta el scope de la operación), `ip_not_allowed` (la IP de origen no está en la lista de la clave) o `tenant_not_external` (el centro no está en gestión externa). Cuerpo: `ApiError`.
- `413`: `payload_too_large`: el cuerpo supera 2 MB. Cuerpo: `ApiError`.
- `422`: `validation_error`: tipo o fechas no válidos, `end` no posterior a `start`, franjas no válidas o solapadas, `dailyEntryLimit` fuera de 1–50, el socio no existe o está de baja, el perfil no existe o está deshabilitado. `details` indica el campo. Cuerpo: `ApiError`.
- `429`: `rate_limited`: límite de peticiones superado. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

### `DELETE /integrations/v1/access-grants/{externalId}` — Revocar un permiso de acceso

`operationId`: `revokeAccessGrant`

Revoca el permiso y lo retira del torno al momento. Idempotente: `204` también si ya estaba revocado. Para volver a activarlo, envíalo otra vez con `PUT`.

**Scope requerido:** `grants:write`

**Parámetros**

| Nombre | En | Obligatorio | Tipo | Descripción |
|---|---|---|---|---|
| `externalId` | path | sí | string | Tu identificador del permiso. Ejemplo: `cuota-2026-11-socio-1042`. |

**Respuestas**

- `204`: Permiso revocado.
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden` (a la clave le falta el scope de la operación), `ip_not_allowed` (la IP de origen no está en la lista de la clave) o `tenant_not_external` (el centro no está en gestión externa). Cuerpo: `ApiError`.
- `404`: `not_found`: el permiso nunca ha existido. Cuerpo: `ApiError`.
- `422`: `validation_error`: `externalId` con formato no válido. Cuerpo: `ApiError`.
- `429`: `rate_limited`: límite de peticiones superado. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

## Carga masiva

Para la carga inicial de un centro o una resincronización completa: hasta **500** socios o permisos por petición, que cuenta como **una** sola para el límite de peticiones.

- `POST /bulk/members` con `{"members": [...]}`: cada elemento es el cuerpo de `PUT /members/{externalId}` más su `externalId`.
- `POST /bulk/access-grants` con `{"grants": [...]}`: cada elemento es el cuerpo de `PUT /access-grants/{externalId}` más su `externalId`.

Cada elemento se procesa **por separado**, con las mismas reglas que su `PUT`: un error en uno no afecta al resto. La respuesta es siempre `200` si el lote es aceptable, con un resultado por elemento **en el mismo orden** que la entrada y el recuento:

```json
{
  "results": [
    { "externalId": "socio-1042", "status": "created" },
    { "externalId": "socio-1043", "status": "updated" },
    { "externalId": "socio-1044", "status": "error",
      "error": { "code": "validation_error", "message": "Los datos enviados no son válidos",
                 "details": [{ "field": "firstName", "message": "es obligatorio" }] } }
  ],
  "summary": { "created": 1, "updated": 1, "errors": 1 }
}
```

- `error` tiene el mismo `code`, `message` y `details` que daría la petición unitaria.
- Un `externalId` repetido dentro del lote: se procesa la primera aparición y las demás dan `error` `conflict`.
- Un elemento que no es un objeto o no trae `externalId` de texto da `error` en ese elemento (con `externalId: null` si no se pudo leer).
- Lista ausente, vacía o de más de 500 elementos: `422` para todo el lote.

Carga primero los socios y después sus permisos (un permiso de un socio que aún no existe da error). Reintentar un lote entero es seguro: son upserts.

### `POST /integrations/v1/bulk/access-grants` — Carga masiva de permisos de acceso

`operationId`: `bulkUpsertAccessGrants`

Hasta 500 permisos en una petición (cuenta como una para el límite de peticiones). Cada elemento es el cuerpo de `PUT /access-grants/{externalId}` más su `externalId`, y se procesa por separado. Carga primero los socios: un permiso de un socio que aún no existe da error en ese elemento.

**Scope requerido:** `grants:write`

**Cuerpo de la petición** (obligatorio): `BulkAccessGrantsRequest`

**Respuestas**

- `200`: Lote procesado; mira `status` de cada elemento. Cuerpo: `BulkResponse`.
- `400`: `bad_request`: JSON ilegible, parámetro con formato incorrecto o `cursor` no válido. Cuerpo: `ApiError`.
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden` (a la clave le falta el scope de la operación), `ip_not_allowed` (la IP de origen no está en la lista de la clave) o `tenant_not_external` (el centro no está en gestión externa). Cuerpo: `ApiError`.
- `413`: `payload_too_large`: el cuerpo supera 2 MB. Cuerpo: `ApiError`.
- `422`: `validation_error`: falta la lista `grants`, está vacía o tiene más de 500 elementos. Cuerpo: `ApiError`.
- `429`: `rate_limited`: límite de peticiones superado. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

### `POST /integrations/v1/bulk/members` — Carga masiva de socios

`operationId`: `bulkUpsertMembers`

Hasta 500 altas o actualizaciones de socios en una petición (cuenta como una para el límite de peticiones). Cada elemento es el cuerpo de `PUT /members/{externalId}` más su `externalId`, y se procesa por separado: un error en uno no afecta al resto. La respuesta trae un resultado por elemento, en el mismo orden, y el recuento.

**Scope requerido:** `members:write`

**Cuerpo de la petición** (obligatorio): `BulkMembersRequest`

**Respuestas**

- `200`: Lote procesado; mira `status` de cada elemento. Cuerpo: `BulkResponse`.
- `400`: `bad_request`: JSON ilegible, parámetro con formato incorrecto o `cursor` no válido. Cuerpo: `ApiError`.
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden` (a la clave le falta el scope de la operación), `ip_not_allowed` (la IP de origen no está en la lista de la clave) o `tenant_not_external` (el centro no está en gestión externa). Cuerpo: `ApiError`.
- `413`: `payload_too_large`: el cuerpo supera 2 MB. Cuerpo: `ApiError`.
- `422`: `validation_error`: falta la lista `members`, está vacía o tiene más de 500 elementos. Cuerpo: `ApiError`.
- `429`: `rate_limited`: límite de peticiones superado. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

## Eventos de acceso

Cada vez que un socio creado por la API entra o sale por un torno, o el torno le deniega el paso, Fitnova genera un evento. Te llega por **webhook** (ver *Webhooks*) y además puedes consultarlo con `GET /access-events`, que es la red de seguridad para recuperar lo que no te llegó.

#### Forma del evento

El mismo cuerpo en la consulta y en el webhook:

```json
{
  "id": "evt_000000000123",
  "type": "access.entry",
  "occurredAt": "2026-11-12T17:03:11Z",
  "data": {
    "memberExternalId": "socio-1042",
    "visitId": "vis_000000000456",
    "method": "RFID",
    "credential": "4000000001",
    "turnstile": { "id": "192.168.1.50:4370", "name": "Torno entrada principal" },
    "exitSource": null,
    "reason": null,
    "reasonText": null
  }
}
```

- `type`: `access.entry`, `access.exit` o `access.denied`.
- `id`: único por evento. Úsalo para no procesar dos veces el mismo.
- `visitId`: identifica la visita. La entrada y su salida comparten el mismo `visitId`: con él calculas la duración de la estancia.
- `exitSource` (solo en salidas): `TURNSTILE` (salida por el torno), `MANUAL` (la registró el centro) o `AUTO_CLOSE` (el sistema cerró la visita porque el socio no fichó la salida).

#### Accesos denegados

Cuando el torno rechaza un paso llega un `access.denied`, para que sepas por qué un socio no puede entrar:

```json
{
  "id": "evt_000000000124",
  "type": "access.denied",
  "occurredAt": "2026-11-12T17:05:40Z",
  "data": {
    "memberExternalId": "socio-1042",
    "visitId": null,
    "method": "RFID",
    "credential": "4000000001",
    "turnstile": { "id": "192.168.1.50:4370", "name": "Torno entrada principal" },
    "exitSource": null,
    "reason": "no_valid_access",
    "reasonText": "Usuario sin accesos válidos"
  }
}
```

- `reason`: el motivo como código fijo, para programar sobre él. `reasonText` es el mismo motivo en texto libre, tal como lo mostró el torno.
- **Credencial que no es de nadie.** Si se pasa una tarjeta o un QR que no corresponde a ningún socio, el evento llega con `memberExternalId: null` y la credencial leída, con `reason: "card_not_registered"` en tarjetas. Te sirve para detectar una tarjeta que no has dado de alta (o que diste de alta con otro número).
- `visitId` siempre es `null`: un paso denegado no abre visita.
- Si se insiste con la misma credencial y el mismo motivo, los intentos de los siguientes **10 s** no generan más eventos.

| `reason` | Qué significa |
|---|---|
| `card_not_registered` | La tarjeta no es de ningún socio. |
| `member_inactive` | El socio está dado de baja. |
| `no_access_grant` | El socio no tiene ningún permiso de acceso. |
| `no_valid_access` | Tiene permisos, pero ninguno vale ahora: caducado, fuera de su franja o con el tope de entradas diarias alcanzado. |
| `antipassback_wait` | Acaba de pasar y debe esperar unos segundos. |
| `outside_opening_hours` | El torno está fuera de su horario de funcionamiento. |
| `capacity_full` | La zona ha llegado a su aforo máximo. |
| `wrong_zone` | El socio consta en otra zona (por ejemplo, intenta entrar sin haber salido). |
| `reader_disabled` | El lector está deshabilitado. |
| `qr_invalid` | El QR no es válido (firma incorrecta, caducado, ya usado…). |
| `internal_error` | Fallo del sistema de control de accesos. |
| `other` | Otro motivo; consulta `reasonText`. |

Pueden aparecer códigos nuevos: trata uno que no conozcas como `other`.

#### Seguir la cola sin perder nada

`GET /access-events` devuelve los eventos en orden de registro, con `nextCursor` y `hasMore`:

1. La primera vez, llama sin `cursor` (o con `from` para empezar en una fecha).
2. Guarda el `nextCursor` de cada respuesta. **Nunca es `null`**: si la página viene vacía, es el mismo punto del que partías.
3. Con `hasMore: true`, pide enseguida la siguiente página. Con `false`, espera (por ejemplo 30–60 s) y vuelve a pedir con el mismo cursor.
4. Usa los mismos filtros (`memberExternalId`, `from`, `to`) en todas las peticiones de un mismo seguimiento.

Así recibes todo lo nuevo sin huecos ni repeticiones. Un evento tarda **al menos 5 s** en aparecer en la consulta (margen para que ninguno se quede atrás); los webhooks no tienen ese retardo.

`from` y `to` (ISO-8601 con zona) filtran por `occurredAt`: desde `from` incluido hasta `to` excluido.

#### Limitaciones

- **Denegados sin conexión.** Si el torno pierde la conexión con Fitnova, los pasos que deniegue mientras tanto no generan `access.denied`; las entradas y salidas sí se recuperan.
- En una salida, `method`, `credential` y `turnstile` son **los de la entrada** de esa visita: el registro de la visita guarda solo los de la entrada.
- **Cierres automáticos.** Si el socio no ficha la salida, el sistema cierra la visita y te llega un `access.exit` con `exitSource: "AUTO_CLOSE"`. Si más tarde se registra la salida real, llega otro `access.exit` con el **mismo `visitId`** y la hora real: sustituye con él la salida automática.
- Solo se generan eventos de socios creados por la API (más los denegados de credenciales que no son de nadie) y con el centro en gestión externa.
- Los eventos se conservan 90 días.
- En una sobrecarga extrema del servidor un paso podría quedarse sin evento (ni en la consulta ni en el webhook). Es excepcional y queda registrado en Fitnova; si tu contador de sesiones depende de ello, concilia de vez en cuando con el centro.

### `GET /integrations/v1/access-events` — Listar eventos de acceso

`operationId`: `listAccessEvents`

Entradas y salidas de tus socios por orden de registro. Es la red de seguridad de los webhooks: con ella recuperas lo que no te llegó.

`nextCursor` **nunca es `null`**: guárdalo y vuelve a pedir con él. Con `hasMore: true` pide la siguiente página enseguida; con `false`, espera (p. ej. 30–60 s) y repite con el mismo cursor. Usa los mismos filtros en todas las peticiones de un seguimiento.

Un evento tarda al menos 5 s en aparecer aquí (los webhooks no tienen ese retardo).

**Scope requerido:** `events:read`

**Parámetros**

| Nombre | En | Obligatorio | Tipo | Descripción |
|---|---|---|---|---|
| `memberExternalId` | query | no | string | Solo los eventos de este socio (tu `externalId`). |
| `from` | query | no | string | Desde este instante, incluido (ISO-8601 con zona, sobre `occurredAt`). |
| `to` | query | no | string | Hasta este instante, excluido (ISO-8601 con zona, sobre `occurredAt`). |
| `limit` | query | no | integer | Tamaño de página, de 1 a 100. Por defecto: `50`. Rango: 1–100. |
| `cursor` | query | no | string | El `nextCursor` de la respuesta anterior; sin él, desde el principio. |

**Respuestas**

- `200`: Una página de eventos. Cuerpo: `AccessEventPage`.
- `400`: `bad_request`: `cursor` no válido. Cuerpo: `ApiError`.
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden` (a la clave le falta el scope de la operación), `ip_not_allowed` (la IP de origen no está en la lista de la clave) o `tenant_not_external` (el centro no está en gestión externa). Cuerpo: `ApiError`.
- `422`: `validation_error`: `limit` fuera de 1–100, fechas no ISO-8601, `to` no posterior a `from` o `memberExternalId` no válido. Cuerpo: `ApiError`.
- `429`: `rate_limited`: límite de peticiones superado. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

## Webhooks

Fitnova te avisa de cada entrada, salida y acceso denegado de tus socios con una petición `POST` firmada a tu servidor. Un centro tiene como mucho un webhook.

#### Alta

```bash
curl -X PUT https://dev-developers.fitnova.eu/integrations/v1/webhook \
  -H "X-API-Key: fnv_test_Xq3vN8bT2kLw9RmZ5cYh7JpD4sGf6AeU1oQiWn0VzKx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://gestor.example.com/webhooks/fitnova", "events": ["access.entry", "access.exit", "access.denied"]}'
```

- `events`: los tipos que quieres recibir (`access.entry`, `access.exit`, `access.denied`).

- La URL debe ser `https`, puerto 443, sin usuario ni contraseña, y pública (no se admiten direcciones internas). No se siguen redirecciones.
- La respuesta de alta (`201`) trae el **secreto** `whsec_…` para verificar la firma. Guárdalo: no se vuelve a mostrar. Si lo pierdes, `POST /webhook/rotate-secret` genera otro (el anterior deja de usarse en el siguiente envío).
- Comprueba tu receptor con `POST /webhook/test`: envía un evento `webhook.test` firmado y te dice qué respondió tu servidor. Como mucho 6 pruebas por minuto.

#### Qué recibes

Un `POST` con el evento como cuerpo JSON (el mismo formato que `GET /access-events`) y estas cabeceras:

| Cabecera | Valor |
|---|---|
| `Content-Type` | `application/json` |
| `X-Fitnova-Event` | Tipo de evento: `access.entry`, `access.exit`, `access.denied` o `webhook.test`. |
| `X-Fitnova-Delivery` | Id de la entrega (`dlv_…`), el de `GET /webhook/deliveries`. |
| `X-Fitnova-Timestamp` | Momento del envío, en segundos Unix. |
| `X-Fitnova-Signature` | `v1=` + HMAC-SHA256 en hexadecimal de `timestamp + "." + cuerpo`, con tu secreto como clave. |

El evento de prueba tiene la misma forma con `data` vacío:

```json
{ "id": "evt_test_5f2c9a1b7e3d", "type": "webhook.test", "occurredAt": "2026-11-12T17:03:11Z", "data": {} }
```

#### Cómo responder

- Responde **cualquier 2xx en 10 s como mucho** para darlo por entregado. Lo mejor: verifica la firma, guarda el evento y responde `200` enseguida; procésalo después.
- **Deduplica por `id`.** La entrega es «al menos una vez»: el mismo evento puede llegar más de una vez (por ejemplo, si tu respuesta se pierde).
- **El orden no está garantizado.** Usa `occurredAt` y `visitId` para ordenar y emparejar.

#### Reintentos y deshabilitado automático

Si tu servidor no responde 2xx, se reintenta a los 1 min, 5 min, 30 min, 2 h, 6 h y 12 h (7 intentos en unas 21 h). Después la entrega queda `failed`; puedes recuperar el evento con `GET /access-events`.

El webhook se **deshabilita automáticamente** cuando acumula 50 entregas `failed` seguidas o cuando lleva 24 h sin ninguna entrega con éxito (contando desde el último éxito, el alta o el último cambio de configuración). Mientras está deshabilitado los eventos se siguen guardando y sus entregas esperan; un `PUT /webhook` lo rehabilita y las reanuda. `GET /webhook` muestra el estado y el motivo; `GET /webhook/deliveries`, el detalle de cada entrega.

`DELETE /webhook` lo borra y da por fallidas las entregas pendientes.

#### Verificar la firma

Verifica **todas** las peticiones antes de usarlas. Así sabes que vienen de Fitnova y que nadie las ha cambiado ni las está repitiendo:

1. Lee el cuerpo **en bruto**, byte a byte como llegó. No lo parsees y vuelvas a serializar: un espacio de diferencia cambia la firma.
2. Calcula `HMAC-SHA256(clave = tu secreto whsec_… tal cual, en UTF-8, mensaje = X-Fitnova-Timestamp + "." + cuerpo)` en hexadecimal en minúsculas.
3. Compáralo con lo que va tras `v1=` en `X-Fitnova-Signature` **en tiempo constante** (nunca con `==`).
4. Rechaza la petición si `X-Fitnova-Timestamp` se aleja más de **5 minutos** de tu hora (protege frente a reenvíos). Mantén el reloj de tu servidor sincronizado (NTP).

Si algo falla, responde `401` y no proceses el evento.

**Vector de prueba** (compruébalo con tu código): secreto `whsec_prueba`, `X-Fitnova-Timestamp: 1731430991`, cuerpo `{"id":"evt_000000000123","type":"access.entry"}` → `X-Fitnova-Signature: v1=a804f3abe85f64c907d16b11bc9279f79279da8b2d85169dcc5b37f0b1dc4384`.

##### Node.js

```js
const crypto = require('node:crypto');

const TOLERANCE_SECONDS = 5 * 60;

/** rawBody: Buffer con los bytes EXACTOS recibidos. */
function verifyFitnovaSignature(secret, timestamp, signature, rawBody,
    nowSeconds = Math.floor(Date.now() / 1000)) {
  if (typeof timestamp !== 'string' || typeof signature !== 'string') return false;
  if (!/^\d+$/.test(timestamp) || !signature.startsWith('v1=')) return false;
  if (Math.abs(nowSeconds - Number(timestamp)) > TOLERANCE_SECONDS) return false;
  const expected = crypto.createHmac('sha256', secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest('hex');
  const a = Buffer.from(expected, 'utf8');
  const b = Buffer.from(signature.slice(3), 'utf8');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express: el cuerpo en bruto con express.raw, no express.json.
app.post('/webhooks/fitnova', express.raw({ type: 'application/json' }), (req, res) => {
  const ok = verifyFitnovaSignature(process.env.FITNOVA_WEBHOOK_SECRET,
    req.get('X-Fitnova-Timestamp'), req.get('X-Fitnova-Signature'), req.body);
  if (!ok) return res.sendStatus(401);
  const event = JSON.parse(req.body.toString('utf8'));
  // Guarda el evento (deduplicando por event.id) y procésalo después.
  res.sendStatus(200);
});
```

##### Python

```python
import hashlib
import hmac
import time

TOLERANCE_SECONDS = 5 * 60

def verify_fitnova_signature(secret, timestamp, signature, raw_body, now=None):
    """raw_body: bytes EXACTOS recibidos (en Flask, request.get_data())."""
    if not timestamp or not signature:
        return False
    if not (timestamp.isascii() and timestamp.isdigit()) or not signature.startswith("v1="):
        return False
    now = int(time.time()) if now is None else now
    if abs(now - int(timestamp)) > TOLERANCE_SECONDS:
        return False
    message = timestamp.encode("ascii") + b"." + raw_body
    expected = hmac.new(secret.encode("utf-8"), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature[3:])

# Flask
@app.post("/webhooks/fitnova")
def fitnova_webhook():
    if not verify_fitnova_signature(os.environ["FITNOVA_WEBHOOK_SECRET"],
                                    request.headers.get("X-Fitnova-Timestamp"),
                                    request.headers.get("X-Fitnova-Signature"),
                                    request.get_data()):
        return "", 401
    event = json.loads(request.get_data())
    # Guarda el evento (deduplicando por event["id"]) y procésalo después.
    return "", 200
```

##### PHP

```php
<?php
function verifyFitnovaSignature(string $secret, ?string $timestamp, ?string $signature,
                                string $rawBody, ?int $now = null): bool
{
    if ($timestamp === null || $signature === null) return false;
    if (!ctype_digit($timestamp) || strncmp($signature, 'v1=', 3) !== 0) return false;
    $now = $now ?? time();
    if (abs($now - (int) $timestamp) > 300) return false;
    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
    return hash_equals($expected, substr($signature, 3));
}

$rawBody = file_get_contents('php://input');
$ok = verifyFitnovaSignature(getenv('FITNOVA_WEBHOOK_SECRET'),
    $_SERVER['HTTP_X_FITNOVA_TIMESTAMP'] ?? null,
    $_SERVER['HTTP_X_FITNOVA_SIGNATURE'] ?? null,
    $rawBody);
if (!$ok) {
    http_response_code(401);
    exit;
}
$event = json_decode($rawBody, true);
// Guarda el evento (deduplicando por $event['id']) y procésalo después.
http_response_code(200);
```

##### Java

```java
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public final class FitnovaWebhooks {

    private static final long TOLERANCE_SECONDS = 5 * 60;

    /** rawBody: bytes EXACTOS recibidos (en Spring, @RequestBody byte[] body). */
    public static boolean verifySignature(String secret, String timestamp, String signature, byte[] rawBody,
            long nowSeconds) throws Exception {
        if (timestamp == null || signature == null || !timestamp.matches("\\d{1,18}")
                || !signature.startsWith("v1=")) {
            return false;
        }
        if (Math.abs(nowSeconds - Long.parseLong(timestamp)) > TOLERANCE_SECONDS) {
            return false;
        }
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        mac.update((timestamp + ".").getBytes(StandardCharsets.UTF_8));
        byte[] expected = HexFormat.of().formatHex(mac.doFinal(rawBody)).getBytes(StandardCharsets.UTF_8);
        byte[] received = signature.substring(3).getBytes(StandardCharsets.UTF_8);
        return MessageDigest.isEqual(expected, received);
    }
}

// Uso: verifySignature(secret, request.getHeader("X-Fitnova-Timestamp"),
//     request.getHeader("X-Fitnova-Signature"), body, Instant.now().getEpochSecond())
```

##### C#

```csharp
using System.Globalization;
using System.Security.Cryptography;
using System.Text;

public static class FitnovaWebhooks
{
    private const long ToleranceSeconds = 5 * 60;

    /// rawBody: bytes EXACTOS recibidos (en ASP.NET Core, lee Request.Body a un MemoryStream).
    public static bool VerifySignature(string secret, string? timestamp, string? signature, byte[] rawBody,
        long? nowSeconds = null)
    {
        if (string.IsNullOrEmpty(timestamp) || string.IsNullOrEmpty(signature)) return false;
        if (!signature.StartsWith("v1=", StringComparison.Ordinal)) return false;
        if (!long.TryParse(timestamp, NumberStyles.None, CultureInfo.InvariantCulture, out var ts)) return false;
        var now = nowSeconds ?? DateTimeOffset.UtcNow.ToUnixTimeSeconds();
        if (Math.Abs(now - ts) > ToleranceSeconds) return false;

        var prefix = Encoding.UTF8.GetBytes(timestamp + ".");
        var message = new byte[prefix.Length + rawBody.Length];
        Buffer.BlockCopy(prefix, 0, message, 0, prefix.Length);
        Buffer.BlockCopy(rawBody, 0, message, prefix.Length, rawBody.Length);
        var hash = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), message);
        var expected = Encoding.ASCII.GetBytes(Convert.ToHexString(hash).ToLowerInvariant());
        var received = Encoding.ASCII.GetBytes(signature.Substring(3));
        return CryptographicOperations.FixedTimeEquals(expected, received);
    }
}
```

### `GET /integrations/v1/webhook` — Consultar el webhook

`operationId`: `getWebhook`

Configuración y estado del webhook (sin el secreto): si está habilitado, por qué se deshabilitó y los contadores de entregas.

**Scope requerido:** `webhooks:write`

**Respuestas**

- `200`: El webhook. Cuerpo: `Webhook`.
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden` (a la clave le falta el scope de la operación), `ip_not_allowed` (la IP de origen no está en la lista de la clave) o `tenant_not_external` (el centro no está en gestión externa). Cuerpo: `ApiError`.
- `404`: `not_found`: el centro no tiene webhook. Cuerpo: `ApiError`.
- `429`: `rate_limited`: límite de peticiones superado. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

### `PUT /integrations/v1/webhook` — Configurar el webhook

`operationId`: `upsertWebhook`

Crea o cambia el webhook del centro (uno como mucho). Al **crearlo** la respuesta trae `secret` (`whsec_…`): guárdalo, no se vuelve a mostrar (si lo pierdes, `POST /webhook/rotate-secret`). Al cambiarlo no hay secreto en la respuesta.

La URL debe ser `https`, puerto 443, sin usuario ni contraseña y pública (no se admiten direcciones internas). Un `PUT` también rehabilita un webhook deshabilitado y reanuda sus entregas pendientes.

**Scope requerido:** `webhooks:write`

**Cuerpo de la petición** (obligatorio): `WebhookRequest`

**Respuestas**

- `200`: Webhook cambiado (y rehabilitado si estaba deshabilitado). Cuerpo: `Webhook`.
- `201`: Webhook creado; incluye `secret` (solo esta vez). Cuerpo: `Webhook`.
- `400`: `bad_request`: JSON ilegible, parámetro con formato incorrecto o `cursor` no válido. Cuerpo: `ApiError`.
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden` (a la clave le falta el scope de la operación), `ip_not_allowed` (la IP de origen no está en la lista de la clave) o `tenant_not_external` (el centro no está en gestión externa). Cuerpo: `ApiError`.
- `413`: `payload_too_large`: el cuerpo supera 2 MB. Cuerpo: `ApiError`.
- `422`: `validation_error`: URL no válida o no permitida, o `events` vacío o con tipos desconocidos. Cuerpo: `ApiError`.
- `429`: `rate_limited`: límite de peticiones superado. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

### `DELETE /integrations/v1/webhook` — Borrar el webhook

`operationId`: `deleteWebhook`

Borra el webhook; sus entregas pendientes quedan `failed`. Idempotente: `204` también si no había webhook.

**Scope requerido:** `webhooks:write`

**Respuestas**

- `204`: Webhook borrado (o no había).
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden` (a la clave le falta el scope de la operación), `ip_not_allowed` (la IP de origen no está en la lista de la clave) o `tenant_not_external` (el centro no está en gestión externa). Cuerpo: `ApiError`.
- `429`: `rate_limited`: límite de peticiones superado. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

### `GET /integrations/v1/webhook/deliveries` — Listar entregas del webhook

`operationId`: `listWebhookDeliveries`

Entregas del centro, las más recientes primero, paginadas con cursor (`nextCursor` `null` = no hay más). Sirve para ver qué falló y cuándo se reintenta.

**Scope requerido:** `webhooks:write`

**Parámetros**

| Nombre | En | Obligatorio | Tipo | Descripción |
|---|---|---|---|---|
| `cursor` | query | no | string | El `nextCursor` de la página anterior; sin él, las más recientes. |
| `limit` | query | no | integer | Tamaño de página, de 1 a 100. Por defecto: `50`. Rango: 1–100. |
| `status` | query | no | string: `pending`, `delivered`, `failed` | Solo las entregas en este estado. |

**Respuestas**

- `200`: Una página de entregas. Cuerpo: `PageResponseWebhookDelivery`.
- `400`: `bad_request`: `cursor` no válido. Cuerpo: `ApiError`.
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden` (a la clave le falta el scope de la operación), `ip_not_allowed` (la IP de origen no está en la lista de la clave) o `tenant_not_external` (el centro no está en gestión externa). Cuerpo: `ApiError`.
- `422`: `validation_error`: `limit` fuera de 1–100 o `status` desconocido. Cuerpo: `ApiError`.
- `429`: `rate_limited`: límite de peticiones superado. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

### `POST /integrations/v1/webhook/rotate-secret` — Rotar el secreto del webhook

`operationId`: `rotateWebhookSecret`

Genera un secreto nuevo y lo devuelve (solo esta vez). El anterior deja de usarse en el siguiente envío: actualiza tu receptor a la vez.

**Scope requerido:** `webhooks:write`

**Respuestas**

- `200`: El secreto nuevo. Cuerpo: `WebhookSecret`.
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden` (a la clave le falta el scope de la operación), `ip_not_allowed` (la IP de origen no está en la lista de la clave) o `tenant_not_external` (el centro no está en gestión externa). Cuerpo: `ApiError`.
- `404`: `not_found`: el centro no tiene webhook. Cuerpo: `ApiError`.
- `429`: `rate_limited`: límite de peticiones superado. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

### `POST /integrations/v1/webhook/test` — Probar el webhook

`operationId`: `testWebhook`

Envía ahora un evento `webhook.test` firmado con el secreto actual y devuelve lo que respondió tu receptor (espera 10 s como mucho). Funciona aunque el webhook esté deshabilitado y no cuenta como entrega. Como mucho 6 pruebas por minuto.

**Scope requerido:** `webhooks:write`

**Respuestas**

- `200`: Resultado del envío (`delivered` dice si respondió 2xx). Cuerpo: `WebhookTestResult`.
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden` (a la clave le falta el scope de la operación), `ip_not_allowed` (la IP de origen no está en la lista de la clave) o `tenant_not_external` (el centro no está en gestión externa). Cuerpo: `ApiError`.
- `404`: `not_found`: el centro no tiene webhook. Cuerpo: `ApiError`.
- `429`: `rate_limited`: más de 6 pruebas en el minuto, demasiadas pruebas en curso en el servidor o límite de peticiones de la clave. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

## Entorno de pruebas

En el entorno de pruebas no tienes un torno delante, así que puedes **simular los pasos** de tus socios: entradas, salidas y accesos denegados. El evento te llega exactamente como uno real (por webhook y en `GET /access-events`), con el torno `{"id": "sandbox", "name": "Torno simulado"}`.

Solo funciona en el entorno de pruebas (`dev-developers.fitnova.eu`) y con claves `fnv_test_`. En producción responde `404`.

```bash
curl -X POST https://dev-developers.fitnova.eu/integrations/v1/sandbox/access-events \
  -H "X-API-Key: fnv_test_Xq3vN8bT2kLw9RmZ5cYh7JpD4sGf6AeU1oQiWn0VzKx" \
  -H "Content-Type: application/json" \
  -d '{"type": "access.entry", "memberExternalId": "socio-1042"}'
```

Cambia el cuerpo para simular otros pasos:

| Quieres simular | Cuerpo |
|---|---|
| La salida del socio | `{"type": "access.exit", "memberExternalId": "socio-1042"}` |
| Un denegado por permiso caducado | `{"type": "access.denied", "memberExternalId": "socio-1042", "reason": "no_valid_access"}` |
| Una tarjeta que no es de nadie | `{"type": "access.denied", "credential": "4000000999"}` |
| Un QR rechazado | `{"type": "access.denied", "memberExternalId": "socio-1042", "reason": "qr_invalid"}` |

- La credencial, si no la indicas, es la primera tarjeta del socio.
- El simulador **no comprueba permisos**: registra lo que le pides. Para probar tu gestión de un rechazo, simula el `access.denied` con el `reason` correspondiente.
- Los denegados repetidos con la misma credencial y el mismo motivo en 10 s cuentan como uno, igual que en un torno real.
- Para probar tu receptor caído, haz que devuelva un error y simula un paso: verás los reintentos en `GET /webhook/deliveries`.

### `POST /integrations/v1/sandbox/access-events` — Simular un paso por el torno

`operationId`: `simulateAccessEvent`

Solo en el **entorno de pruebas** y con claves `fnv_test_`. Registra una entrada, una salida o un acceso denegado como si lo hubiera hecho el torno: el evento llega por el mismo camino (webhook y `GET /access-events`) y con la misma forma que uno real, con el torno `{"id": "sandbox", "name": "Torno simulado"}`.

No comprueba los permisos del socio: el torno real sí lo haría. Usa `access.denied` con el `reason` que quieras probar.

**Scope requerido:** `events:read`

**Cuerpo de la petición** (obligatorio): `SandboxAccessEventRequest`

*Entrada de un socio*

```json
{
  "type" : "access.entry",
  "memberExternalId" : "socio-1042"
}
```

*Su salida*

```json
{
  "type" : "access.exit",
  "memberExternalId" : "socio-1042"
}
```

*Denegado: permiso caducado*

```json
{
  "type" : "access.denied",
  "memberExternalId" : "socio-1042",
  "reason" : "no_valid_access"
}
```

*Tarjeta que no es de nadie*

```json
{
  "type" : "access.denied",
  "credential" : "4000000999"
}
```

**Respuestas**

- `202`: Paso registrado; el evento llega en unos segundos. Cuerpo: `SandboxAccessEventResult`.
- `400`: `bad_request`: JSON ilegible, parámetro con formato incorrecto o `cursor` no válido. Cuerpo: `ApiError`.
- `401`: `unauthorized`: falta `X-API-Key`, la clave no existe, está revocada o ha caducado. Cuerpo: `ApiError`.
- `403`: `forbidden`: la clave es `fnv_live_` o le falta `events:read`. Cuerpo: `ApiError`.
- `404`: `not_found`: el socio no existe, o el simulador no existe en este entorno (producción). Cuerpo: `ApiError`.
- `409`: `conflict`: ese usuario no es un socio de la API. Cuerpo: `ApiError`.
- `413`: `payload_too_large`: el cuerpo supera 2 MB. Cuerpo: `ApiError`.
- `422`: `validation_error`: `type`, `method` o `reason` desconocidos, falta el socio en una entrada o salida, el socio está de baja, o falta `credential` en un denegado sin socio. Cuerpo: `ApiError`.
- `429`: `rate_limited`: límite de peticiones superado. Espera los segundos de `Retry-After`. Cuerpo: `ApiError`.
- `500`: `internal_error`: error inesperado. Reintenta más tarde e indica el `requestId` a Fitnova. Cuerpo: `ApiError`.

---

# Esquemas

Campos de cada objeto de las peticiones y las respuestas. En las respuestas todos los campos aparecen siempre; los que no tienen valor van como `null`.

## `AccessEvent`

Evento de acceso: el mismo cuerpo en la consulta y en el webhook. Los campos sin valor van como `null`.

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | no | Identificador del evento. Úsalo para no procesar dos veces el mismo (los webhooks se entregan al menos una vez). Ejemplo: `evt_000000000123`. |
| `type` | string: `access.entry`, `access.exit`, `access.denied` | no | `access.entry`, `access.exit` o `access.denied`. Ejemplo: `access.entry`. |
| `occurredAt` | string (date-time) | no | Cuándo pasó (UTC). Ejemplo: `2026-11-12T17:03:11Z`. |
| `data` | `AccessEventData` | no |  |

## `AccessEventData`

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `memberExternalId` | string | no | Tu identificador del socio. `null` en un `access.denied` de una tarjeta o un QR que no es de ningún socio. Ejemplo: `socio-1042`. |
| `visitId` | string | no | Visita: la comparten la entrada, su salida y, si la salida fue un `AUTO_CLOSE`, la salida real que la corrige. `null` en `access.denied`. Ejemplo: `vis_000000000456`. |
| `method` | string | no | Cómo se identificó (p. ej. `RFID`, `QR`), tal como lo informa el torno. Ejemplo: `RFID`. |
| `credential` | string | no | Credencial usada (número de tarjeta, código…), tal como la informa el torno. Ejemplo: `4000000001`. |
| `turnstile` | `AccessEventTurnstile` | no | Torno; `null` si el registro no lo identificó. |
| `exitSource` | string | no | Solo en `access.exit`: `TURNSTILE` (el torno), `MANUAL` (la registró el centro) o `AUTO_CLOSE` (la cerró el sistema porque el socio no fichó la salida); puede ser `null`. |
| `reason` | string | no | Solo en `access.denied`: por qué lo rechazó el torno. `card_not_registered` (la tarjeta no es de ningún socio), `member_inactive`, `no_access_grant` (el socio no tiene ningún permiso), `no_valid_access` (ningún permiso vigente ahora: caducado, fuera de franja o tope de entradas diarias), `antipassback_wait` (pasó hace muy poco), `outside_opening_hours`, `capacity_full`, `wrong_zone`, `reader_disabled`, `qr_invalid`, `internal_error` u `other`. Pueden añadirse códigos nuevos: trata uno desconocido como `other`. Ejemplo: `no_valid_access`. |
| `reasonText` | string | no | Solo en `access.denied`: el motivo tal como lo mostró el torno (texto libre en español, para leerlo una persona). Ejemplo: `Usuario sin accesos válidos`. |

## `AccessEventPage`

Página de eventos de acceso.

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `data` | `AccessEvent`[] | no | Eventos en orden de registro. |
| `nextCursor` | string | no | Cursor para seguir la cola. **Nunca es `null`**: si la página viene vacía es el mismo punto del que partías. Ejemplo: `AAAAAAAAAcg`. |
| `hasMore` | boolean | no | `true` si ya hay más eventos: pide la siguiente página enseguida. `false`: espera y vuelve a pedir con el mismo `nextCursor`. Ejemplo: `false`. |

## `AccessEventTurnstile`

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | no | Ejemplo: `192.168.1.50:4370`. |
| `name` | string | no | Ejemplo: `Torno entrada principal`. |

## `AccessGrant`

Permiso de acceso. Fechas en ISO-8601 UTC.

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `externalId` | string | no | Tu identificador del permiso. Ejemplo: `cuota-2026-11-socio-1042`. |
| `memberExternalId` | string | no | Tu identificador del socio. Ejemplo: `socio-1042`. |
| `accessProfile` | string | no | Código del perfil de acceso. Ejemplo: `sala`. |
| `type` | string: `CONTINUOUS`, `SCHEDULED`, `WINDOW`, `DAY_PASS` | no | Ejemplo: `CONTINUOUS`. |
| `start` | string (date-time) | no | Inicio (UTC). En `DAY_PASS`, las 00:00 de Madrid de ese día. Ejemplo: `2026-10-31T23:00:00Z`. |
| `end` | string (date-time) | no | Fin, excluido (UTC). Ejemplo: `2026-11-30T23:00:00Z`. |
| `timeZone` | string | no | Solo `SCHEDULED`; `null` en los demás. Ejemplo: `Europe/Madrid`. |
| `weeklySlots` | `WeeklySlot`[] | no | Solo `SCHEDULED`; `null` en los demás. |
| `dailyEntryLimit` | integer (int32) | no | Máximo de entradas por día; `null` = sin límite. Ejemplo: `1`. |
| `status` | string: `ACTIVE`, `REVOKED` | no | `ACTIVE` o `REVOKED`. Un permiso `ACTIVE` con `end` pasado ya no da acceso. Ejemplo: `ACTIVE`. |
| `createdAt` | string (date-time) | no | Ejemplo: `2026-11-12T09:16:40Z`. |
| `updatedAt` | string (date-time) | no | Ejemplo: `2026-11-12T09:16:40Z`. |

## `AccessGrantRequest`

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `memberExternalId` | string | sí | Tu `externalId` del socio. Debe existir y estar de alta. Ejemplo: `socio-1042`. |
| `accessProfile` | string | sí | Código del perfil de acceso (`GET /access-profiles`): decide por qué tornos pasa. Ejemplo: `sala`. |
| `type` | string: `CONTINUOUS`, `SCHEDULED`, `WINDOW`, `DAY_PASS` | sí | Tipo de permiso. Ejemplo: `CONTINUOUS`. |
| `start` | string (date-time) | no | Inicio (ISO-8601 con zona o desfase). Obligatorio salvo en `DAY_PASS`; en `SCHEDULED` es el inicio de la vigencia. Ejemplo: `2026-11-01T00:00:00+01:00`. |
| `end` | string (date-time) | no | Fin, excluido (ISO-8601 con zona o desfase), posterior a `start`. Obligatorio salvo en `DAY_PASS`. Un `end` en el pasado retira el acceso. Ejemplo: `2026-12-01T00:00:00+01:00`. |
| `date` | string (date) | no | Solo `DAY_PASS`, obligatorio: el día natural (`yyyy-MM-dd`) en hora de Madrid, de 00:00 a 00:00 del día siguiente. Ejemplo: `2026-11-21`. |
| `timeZone` | string | no | Solo `SCHEDULED`: zona IANA de las franjas. Ejemplo: `Europe/Madrid`. Por defecto: `Europe/Madrid`. |
| `weeklySlots` | `WeeklySlot`[] | no | Solo `SCHEDULED`, obligatorio: de 1 a 28 franjas semanales. Una franja con `to <= from` termina al día siguiente; `from == to` no se admite. No se admiten franjas solapadas (las contiguas sí). Elementos: 1–28. |
| `dailyEntryLimit` | integer (int32) | no | Opcional, cualquier tipo: máximo de entradas por día natural (hora de Madrid), de 1 a 50. Ausente o `null` = sin límite. Ejemplo: `1`. Rango: 1–50. |

## `AccessProfile`

Perfil de acceso (qué tornos abre lo configura Fitnova).

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `code` | string | no | Lo que envías en `accessProfile`. Ejemplo: `sala`. |
| `name` | string | no | Nombre para mostrar. Ejemplo: `Sala de musculación`. |

## `ApiError`

Formato único de los errores de la API.

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `code` | string | sí | Código estable del error, para tratarlo por programa. Pueden aparecer códigos nuevos: trata uno desconocido según el estado HTTP. Ejemplo: `validation_error`. |
| `message` | string | sí | Explicación para personas, en español. Puede cambiar: no la compares. Ejemplo: `Los datos enviados no son válidos`. |
| `requestId` | string | sí | Identificador de la petición; es el mismo que la cabecera `X-Request-Id`. Ejemplo: `3f6c1e0a-6a1b-4f43-9a51-0c2d7e9b8a10`. |
| `details` | `ApiErrorDetail`[] | no | Solo en `validation_error`: un elemento por problema. |

## `ApiErrorDetail`

Un problema concreto de validación.

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `field` | string | sí | Campo o parámetro afectado. Ejemplo: `firstName`. |
| `message` | string | sí | Qué le pasa. Ejemplo: `es obligatorio`. |

## `BulkAccessGrant`

Los campos de `PUT /access-grants/{externalId}` más el `externalId`.

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `memberExternalId` | string | sí | Tu `externalId` del socio. Debe existir y estar de alta. Ejemplo: `socio-1042`. |
| `accessProfile` | string | sí | Código del perfil de acceso (`GET /access-profiles`): decide por qué tornos pasa. Ejemplo: `sala`. |
| `type` | string: `CONTINUOUS`, `SCHEDULED`, `WINDOW`, `DAY_PASS` | sí | Tipo de permiso. Ejemplo: `CONTINUOUS`. |
| `start` | string (date-time) | no | Inicio (ISO-8601 con zona o desfase). Obligatorio salvo en `DAY_PASS`; en `SCHEDULED` es el inicio de la vigencia. Ejemplo: `2026-11-01T00:00:00+01:00`. |
| `end` | string (date-time) | no | Fin, excluido (ISO-8601 con zona o desfase), posterior a `start`. Obligatorio salvo en `DAY_PASS`. Un `end` en el pasado retira el acceso. Ejemplo: `2026-12-01T00:00:00+01:00`. |
| `date` | string (date) | no | Solo `DAY_PASS`, obligatorio: el día natural (`yyyy-MM-dd`) en hora de Madrid, de 00:00 a 00:00 del día siguiente. Ejemplo: `2026-11-21`. |
| `timeZone` | string | no | Solo `SCHEDULED`: zona IANA de las franjas. Ejemplo: `Europe/Madrid`. Por defecto: `Europe/Madrid`. |
| `weeklySlots` | `WeeklySlot`[] | no | Solo `SCHEDULED`, obligatorio: de 1 a 28 franjas semanales. Una franja con `to <= from` termina al día siguiente; `from == to` no se admite. No se admiten franjas solapadas (las contiguas sí). Elementos: 1–28. |
| `dailyEntryLimit` | integer (int32) | no | Opcional, cualquier tipo: máximo de entradas por día natural (hora de Madrid), de 1 a 50. Ausente o `null` = sin límite. Ejemplo: `1`. Rango: 1–50. |
| `externalId` | string | sí | Tu identificador del permiso: 1–100 caracteres `[A-Za-z0-9._:-]`. Si se repite en el lote, solo se procesa la primera aparición. Ejemplo: `cuota-2026-11-socio-1042`. |

## `BulkAccessGrantsRequest`

Lote de 1 a 500 permisos de acceso.

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `grants` | `BulkAccessGrant`[] | no | Elementos: 1–500. |

## `BulkItemError`

El mismo `code` y `message` que daría la petición unitaria.

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `code` | string | no | Ejemplo: `validation_error`. |
| `message` | string | no | Ejemplo: `Los datos enviados no son válidos`. |
| `details` | object[] | no | Detalles por campo (`field`, `message`); lista vacía si no hay. Ejemplo: `[{"field":"firstName","message":"es obligatorio"}]`. |

## `BulkItemResult`

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `externalId` | string | no | El del elemento; `null` si no lo traía o no era texto. Ejemplo: `socio-1042`. |
| `status` | string: `created`, `updated`, `error` | no | Ejemplo: `created`. |
| `error` | `BulkItemError` | no | Solo cuando `status` es `error`. |

## `BulkMember`

Los campos de `PUT /members/{externalId}` más el `externalId`.

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `firstName` | string | no | Nombre. Obligatorio al crear; no se puede borrar. Ejemplo: `Lucía`. Longitud: 0–100. |
| `lastName` | string | no | Apellidos. Ejemplo: `Martín Sanz`. Longitud: 0–150. |
| `email` | string (email) | no | Email (se guarda en minúsculas). No puede tenerlo otro usuario habilitado del centro. El socio no recibe correos de Fitnova. Ejemplo: `lucia.martin@example.com`. Longitud: 0–255. |
| `phone` | string | no | Teléfono, tal cual. Ejemplo: `+34 600 123 456`. Longitud: 0–50. |
| `documentId` | string | no | Documento de identidad (DNI, NIE, pasaporte…). Ejemplo: `12345678Z`. Longitud: 0–50. |
| `birthDate` | string (date) | no | Fecha de nacimiento `yyyy-MM-dd`, no posterior a hoy. Ejemplo: `1990-04-17`. |
| `enabled` | boolean | no | `false` deshabilita al socio (retira sus accesos del torno sin revocar sus permisos); `true` lo habilita o reactiva. Ausente: `true` al crear, sin cambios al actualizar. Ejemplo: `true`. |
| `photoUrl` | string (uri) | no | URL `https` pública de la foto (JPEG o PNG, hasta 5 MB y 12 megapíxeles). Se descarga en segundo plano: mira `photo.status`. Ausente = no tocar la foto; `null` = quitarla. Ejemplo: `https://cdn.example.com/socios/1042.jpg`. Longitud: 0–2000. |
| `externalId` | string | sí | Tu identificador del socio: 1–100 caracteres `[A-Za-z0-9._:-]`. Si se repite en el lote, solo se procesa la primera aparición. Ejemplo: `socio-1042`. |

## `BulkMembersRequest`

Lote de 1 a 500 socios.

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `members` | `BulkMember`[] | no | Elementos: 1–500. |

## `BulkResponse`

Resultado de una carga masiva: uno por elemento, en el mismo orden que la entrada, y el recuento.

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `results` | `BulkItemResult`[] | no |  |
| `summary` | `BulkSummary` | no |  |

## `BulkSummary`

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `created` | integer (int32) | no | Ejemplo: `498`. |
| `updated` | integer (int32) | no | Ejemplo: `1`. |
| `errors` | integer (int32) | no | Ejemplo: `1`. |

## `Member`

Socio. Nunca incluye ids internos ni contraseña; los campos sin valor van como `null`.

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `externalId` | string | no | Tu identificador del socio. Ejemplo: `socio-1042`. |
| `firstName` | string | no | Ejemplo: `Lucía`. |
| `lastName` | string | no | Ejemplo: `Martín Sanz`. |
| `email` | string | no | Ejemplo: `lucia.martin@example.com`. |
| `phone` | string | no | Ejemplo: `+34 600 123 456`. |
| `documentId` | string | no | Ejemplo: `12345678Z`. |
| `birthDate` | string (date) | no | Ejemplo: `1990-04-17`. |
| `enabled` | boolean | no | `false` si está de baja o deshabilitado: no entra. Ejemplo: `true`. |
| `rfids` | integer (int64)[] | no | Tarjetas RFID asignadas, en decimal. Ejemplo: `[4000000001]`. |
| `createdAt` | string (date-time) | no | Alta (UTC). Ejemplo: `2026-11-12T09:15:02Z`. |
| `updatedAt` | string (date-time) | no | Último cambio (UTC). Ejemplo: `2026-11-12T09:15:02Z`. |
| `photo` | `MemberPhoto` | no | Estado de la foto pedida con `photoUrl`. Nunca `null`. |

## `MemberPhoto`

Estado de la foto pedida con `photoUrl` (no dice nada de una foto que el centro haya puesto por su cuenta).

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `status` | string: `none`, `pending`, `ready`, `failed` | no | `none` (sin foto pedida), `pending` (descargándose), `ready` o `failed`. Ejemplo: `ready`. |
| `error` | string | no | Motivo del fallo; `null` salvo en `failed`. Ejemplo: `No se ha podido acceder a la URL`. |

## `MemberRequest`

Datos del socio. Al actualizar, un campo ausente no cambia y uno enviado como `null` se borra (salvo `firstName`).

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `firstName` | string | no | Nombre. Obligatorio al crear; no se puede borrar. Ejemplo: `Lucía`. Longitud: 0–100. |
| `lastName` | string | no | Apellidos. Ejemplo: `Martín Sanz`. Longitud: 0–150. |
| `email` | string (email) | no | Email (se guarda en minúsculas). No puede tenerlo otro usuario habilitado del centro. El socio no recibe correos de Fitnova. Ejemplo: `lucia.martin@example.com`. Longitud: 0–255. |
| `phone` | string | no | Teléfono, tal cual. Ejemplo: `+34 600 123 456`. Longitud: 0–50. |
| `documentId` | string | no | Documento de identidad (DNI, NIE, pasaporte…). Ejemplo: `12345678Z`. Longitud: 0–50. |
| `birthDate` | string (date) | no | Fecha de nacimiento `yyyy-MM-dd`, no posterior a hoy. Ejemplo: `1990-04-17`. |
| `enabled` | boolean | no | `false` deshabilita al socio (retira sus accesos del torno sin revocar sus permisos); `true` lo habilita o reactiva. Ausente: `true` al crear, sin cambios al actualizar. Ejemplo: `true`. |
| `photoUrl` | string (uri) | no | URL `https` pública de la foto (JPEG o PNG, hasta 5 MB y 12 megapíxeles). Se descarga en segundo plano: mira `photo.status`. Ausente = no tocar la foto; `null` = quitarla. Ejemplo: `https://cdn.example.com/socios/1042.jpg`. Longitud: 0–2000. |

## `PageResponseAccessGrant`

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `data` | `AccessGrant`[] | no | Elementos de la página. |
| `nextCursor` | string | no | Cursor de la página siguiente (pásalo en `cursor`); `null` si no hay más. Ejemplo: `AAAAAAAABBI`. |

## `PageResponseAccessProfile`

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `data` | `AccessProfile`[] | no | Elementos de la página. |
| `nextCursor` | string | no | Cursor de la página siguiente (pásalo en `cursor`); `null` si no hay más. Ejemplo: `AAAAAAAABBI`. |

## `PageResponseMember`

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `data` | `Member`[] | no | Elementos de la página. |
| `nextCursor` | string | no | Cursor de la página siguiente (pásalo en `cursor`); `null` si no hay más. Ejemplo: `AAAAAAAABBI`. |

## `PageResponseWebhookDelivery`

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `data` | `WebhookDelivery`[] | no | Elementos de la página. |
| `nextCursor` | string | no | Cursor de la página siguiente (pásalo en `cursor`); `null` si no hay más. Ejemplo: `AAAAAAAABBI`. |

## `QrSecret`

Lo que necesita la app para generar el QR del socio sin conexión.

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `accessCode` | string | no | Código de acceso del socio, siempre con 5 dígitos: son los 5 primeros del QR. Ejemplo: `00042`. |
| `secret` | string | no | Secreto del socio (32 bytes) en base64url sin relleno. Trátalo como una contraseña. Ejemplo: `Dgr0OWxS3gdo_UFIbh0ZDnIWYCxqMqfrExhW1j766AE`. |
| `algorithm` | string | no | Siempre `fnv-qr-v1`. Ejemplo: `fnv-qr-v1`. |
| `stepSeconds` | integer (int32) | no | Duración del paso, en segundos. Ejemplo: `15`. |
| `digits` | integer (int32) | no | Longitud del QR. Ejemplo: `9`. |

## `SandboxAccessEventRequest`

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `type` | string: `access.entry`, `access.exit`, `access.denied` | sí | Qué pasa en el torno. Ejemplo: `access.entry`. |
| `memberExternalId` | string | no | Tu `externalId` del socio. Obligatorio en `access.entry` y `access.exit`. En `access.denied`, sin él se simula una credencial que no es de nadie (y entonces `credential` es obligatoria). Ejemplo: `socio-1042`. |
| `method` | string: `RFID`, `QR` | no | `RFID` (por defecto) o `QR`. Ejemplo: `RFID`. |
| `credential` | string | no | Credencial leída. Por defecto, la primera tarjeta del socio (o `SANDBOX` si no tiene). Ejemplo: `4000000001`. |
| `reason` | string | no | Solo `access.denied`: el `reason` del evento (ver *Eventos de acceso*). Por defecto, `no_valid_access` con socio y `card_not_registered` sin él. `qr_invalid` fuerza `method: QR`. Ejemplo: `no_valid_access`. |

## `SandboxAccessEventResult`

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `type` | string | no | Ejemplo: `access.entry`. |
| `memberExternalId` | string | no | Ejemplo: `socio-1042`. |
| `visitId` | string | no | Visita de la entrada o la salida (el `visitId` del evento); `null` en `access.denied`. Ejemplo: `vis_000000000456`. |
| `message` | string | no | Ejemplo: `Paso simulado. El evento aparecerá en unos segundos en GET /access-events y en tu webhook.`. |

## `Webhook`

Webhook del centro.

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `url` | string | no | Ejemplo: `https://gestor.example.com/webhooks/fitnova`. |
| `events` | string[] | no | Ejemplo: `["access.entry","access.exit"]`. |
| `enabled` | boolean | no | `false` si se deshabilitó (automáticamente por fallos sostenidos); un `PUT` lo rehabilita. Ejemplo: `true`. |
| `disabledReason` | string | no | Por qué se deshabilitó; `null` si está habilitado. |
| `lastSuccessAt` | string (date-time) | no | Última entrega con éxito (UTC). Ejemplo: `2026-11-12T17:03:12Z`. |
| `lastFailureAt` | string (date-time) | no | Último intento fallido (UTC). |
| `consecutiveFailures` | integer (int32) | no | Entregas seguidas que acabaron `failed` (agotados los reintentos). Vuelve a 0 con cualquier entrega con éxito. Ejemplo: `0`. |
| `secret` | string | no | Solo en la respuesta que crea el webhook: el secreto para verificar la firma. Guárdalo; no se vuelve a mostrar. Ejemplo: `whsec_4mJ9cJk2Qw8o1VtX0bq7yH3nR5sLp6Ze2uDfGiA8KcM`. |

## `WebhookDelivery`

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | no | Valor de la cabecera `X-Fitnova-Delivery`. Ejemplo: `dlv_000000000789`. |
| `eventId` | string | no | El `id` del evento enviado. Ejemplo: `evt_000000000123`. |
| `status` | string: `pending`, `delivered`, `failed` | no | Ejemplo: `delivered`. |
| `attempts` | integer (int32) | no | Intentos hechos (como mucho 7). Ejemplo: `1`. |
| `lastStatus` | integer (int32) | no | Estado HTTP del último intento; `null` si no hubo respuesta. Ejemplo: `200`. |
| `lastError` | string | no | Error del último intento. |
| `nextAttemptAt` | string (date-time) | no | Próximo intento (UTC), si queda alguno. |
| `createdAt` | string (date-time) | no | Ejemplo: `2026-11-12T17:03:11Z`. |
| `deliveredAt` | string (date-time) | no | Ejemplo: `2026-11-12T17:03:12Z`. |

## `WebhookRequest`

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `url` | string (uri) | sí | URL `https` pública, puerto 443, sin usuario ni contraseña. Ejemplo: `https://gestor.example.com/webhooks/fitnova`. Longitud: 0–2000. |
| `events` | cualquiera: `access.entry`, `access.exit`, `access.denied`[] | no | Elementos: 1–…. |

## `WebhookSecret`

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `secret` | string | no | El secreto nuevo, solo esta vez. Ejemplo: `whsec_Zt3pQ9xL0aV7mN2cB8kR4yW6eU1sJ5hDgFoIqTlXrPc`. |

## `WebhookTestResult`

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `delivered` | boolean | no | `true` si tu receptor respondió 2xx en 10 s o menos. Ejemplo: `true`. |
| `status` | integer (int32) | no | Estado HTTP que respondió; `null` si no hubo respuesta. Ejemplo: `200`. |
| `durationMs` | integer (int64) | no | Duración del envío. Ejemplo: `184`. |
| `error` | string | no | Qué falló; `null` si se entregó. |

## `WeeklySlot`

Franja semanal en hora local de `timeZone`.

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `day` | string: `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`, `SUNDAY` | no | Día de la semana. Ejemplo: `MONDAY`. |
| `from` | string | no | Hora de inicio `HH:mm`. Ejemplo: `07:00`. Patrón: `^([01][0-9]\|2[0-3]):[0-5][0-9]$`. |
| `to` | string | no | Hora de fin `HH:mm`. Si es menor o igual que `from`, termina al día siguiente. Ejemplo: `15:00`. Patrón: `^([01][0-9]\|2[0-3]):[0-5][0-9]$`. |
