API para software de gestión externo

1. Qué permiten las API

Con una clave API puedes, desde tu software, leer y escribir en el calendario de tus instalaciones:

• leer instalaciones y pistas con sus identificadores, necesarios para todas las demás llamadas;
• leer las reservas de un periodo, de una instalación o de una pista individual, para alinearlas con tu archivo;
• crear reservas desde el exterior (por ejemplo, cuando un cliente reserva desde tu sitio web), con los mismos controles de solapamiento y cierre del panel;
• modificar o cancelar una reserva existente (cambio de horario o pista, cobro, notas, cancelación);
• leer la disponibilidad de una pista en un día: franjas ya ocupadas, horarios de apertura y cierres extraordinarios, para así proponer las franjas libres sin replicar las reglas;
• leer la lista de precios de una pista para mostrar los precios al cliente final.

No forman parte de estas API las solicitudes de los organizadores para el uso de las pistas en los torneos (se aprueban desde la app), la creación de estructuras y pistas, el guardado de horarios, cierres y lista de precios: son operaciones del panel del gestor.

2. Requisitos y activación

1. Una cuenta de gestor de pistas VolleyFriends con al menos una estructura y una pista.
2. Una suscripción activa con un plan que incluya la función «API para sistemas de gestión externos». Toda la v1 — incluso las de solo lectura — está reservada para quienes tengan esta función: es una función de pago, no un accesorio del panel.
3. Una clave API generada desde el panel de gestión: admin.volleyfriends.com → Configuración → Claves API → Nueva clave.

La clave tiene la forma vfk_ seguido de 40 caracteres hexadecimales (44 caracteres en total) y se muestra una sola vez, inmediatamente después de su creación: en la base de datos solo queda su huella sha256, por lo que no se puede recuperar de ninguna manera. Si la pierdes, revócala y genera una nueva. En la lista del panel solo verás el prefijo (p. ej., vfk_9f2c), la fecha de creación y la del último uso.

3. Autenticación

Cada solicitud debe autenticarse con la cabecera X-Api-Key. No se necesitan tokens, inicios de sesión, caducidades ni renovaciones: la clave sigue siendo válida hasta que la revoques.

# Las claves de esta página son de ejemplo: sustitúyelas por la tuya.
curl -s https://www.volleyfriends.com/api/manager-api/v1/venues   -H "X-Api-Key: vfk_9f2c41a7b83d05e6c19af4728b60d35e1c9a7f42"

En los siguientes ejemplos, la clave se lee de la variable de entorno VF_API_KEY, tal como conviene hacer también en producción.

Cabecera ausente, de menos de 12 caracteres, desconocida o perteneciente a una clave revocada: la respuesta es 401 con este cuerpo.

{
  "error": "invalid_key",
  "message": "Chiave API mancante o non valida (header X-Api-Key)."
}

4. URL base

https://www.volleyfriends.com/api

Las rutas documentadas a continuación deben añadirse a la base. El prefijo /api pertenece al proxy inverso, por lo que la dirección completa de un endpoint es, por ejemplo:

GET https://www.volleyfriends.com/api/manager-api/v1/availability

Todas las respuestas son application/json con codificación UTF-8. Las solicitudes con cuerpo (POST, PATCH) deben tener Content-Type: application/json.

5. Límite de peticiones

El límite es de 120 solicitudes por minuto por clave API (ventana deslizante de 1 minuto). El recuento es por clave, no por dirección IP: los sistemas de gestión suelen estar detrás de la misma dirección del proveedor y un límite por IP penalizaría a distintos gestores alojados en la misma infraestructura. Si el encabezado X-Api-Key falta por completo, el recuento recae en la dirección IP.

Cada respuesta muestra el estado del contador en los encabezados x-ratelimit-limit, x-ratelimit-remaining y x-ratelimit-reset (segundos para el restablecimiento). Al superarlo, también se añade retry-after.

Respuesta al superar el límite — 429

{
  "error": "rate_limited",
  "message": "Limite di 120 richieste al minuto superato per questa chiave API."
}

6. Endpoints

Seis endpoints, todos bajo /manager-api/v1. Cada llamada pasa por la misma cadena de controles, en este orden: clave API válida → función «API para sistemas de gestión externos» incluida en el plan → rate limit → validación de parámetros → verificación de que el recurso sea tuyo.

6.1 Instalaciones y pistas

Muestra tus instalaciones, cada una con sus propias pistas anidadas. Es la llamada de partida: los id de las pistas (courtId) se necesitan para todos los demás endpoints. Las instalaciones están ordenadas por nombre, las pistas por nombre.

Parámetros

Ninguno.

Ejemplo de solicitud

curl -s https://www.volleyfriends.com/api/manager-api/v1/venues   -H "X-Api-Key: $VF_API_KEY"

Ejemplo de respuesta — 200

{
  "venues": [
    {
      "id": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
      "name": "Centro Sportivo Aurora",
      "city": "Verona",
      "address": "Via delle Palestre 12",
      "verified": true,
      "courts": [
        {
          "id": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
          "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
          "name": "Campo 1",
          "surface": "parquet",
          "indoor": true,
          "lighting": true
        },
        {
          "id": "e2a71f64-9c03-4bd8-b512-38f6cd90a7e1",
          "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
          "name": "Campo 2 beach",
          "surface": "sabbia",
          "indoor": false,
          "lighting": true
        }
      ]
    }
  ]
}

Campos de la respuesta

Si la cuenta aún no tiene instalaciones, la respuesta es {"venues": []}.

Errores específicos

Ninguno además de los generales.

6.2 Lista de reservas

Devuelve las reservas de tus instalaciones, ordenadas por hora de inicio creciente. La lista está paginada: como máximo limit filas por llamada (por defecto 500, límite máximo 1000) — si recibes exactamente limit filas, vuelve a llamar con el offset incrementado para la página siguiente. En producción, filtra siempre, en cualquier caso, al menos por intervalo de fechas.

Parámetros (query string)

Ejemplo de solicitud

curl -s -G https://www.volleyfriends.com/api/manager-api/v1/bookings   -H "X-Api-Key: $VF_API_KEY"   --data-urlencode "courtId=7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05"   --data-urlencode "from=2026-08-01"   --data-urlencode "to=2026-08-31"

Ejemplo de respuesta — 200

{
  "bookings": [
    {
      "id": "9d51c7b4-0e28-4f3a-a6d9-72b48e105c3f",
      "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
      "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
      "courtName": "Campo 1",
      "startsAt": "2026-08-12T16:00:00.000Z",
      "endsAt": "2026-08-12T17:30:00.000Z",
      "customerName": "Marta Bellini",
      "customerPhone": "+39 340 1122334",
      "customerEmail": "marta.bellini@example.com",
      "priceCents": 3000,
      "playersCount": null,
      "status": "confirmed",
      "paymentMethod": null,
      "paymentLink": null,
      "notes": "Prenotato dal sito della struttura",
      "source": "api",
      "recurrenceId": null,
      "createdAt": "2026-07-28T09:14:02.517Z",
      "updatedAt": "2026-07-28T09:14:02.517Z"
    }
  ],
  "limit": 500,
  "offset": 0
}

Campos de una reserva

La misma estructura es devuelta por POST y PATCH (dentro de la clave booking).

Errores específicos

6.3 Nueva reserva

Crea una reserva en una de tus pistas. La reserva se crea con source: "api", de modo que en el panel se distingue de las introducidas a mano, y el gestor recibe una notificación push «Nueva reserva» en la app.

Se aplican las mismas reglas del panel, en el siguiente orden:

1. cierre extraordinario de la instalación en la fecha de inicio → 409 venue_closed;
2. solapamiento con otra reserva no cancelada de la misma pista → 409 overlap;
3. precio ausente → calculado a partir de la tarifa de la pista (null si la hora de inicio no entra en ninguna franja). Si la franja tiene precio por persona, también se requiere playersCount: de lo contrario, la solicitud se rechaza con 400 players_required (a menos que se indique un priceCents explícito).

Los horarios de apertura no bloquean la creación: son informativos, el gestor sigue siendo soberano sobre su propia pista. Si quieres impedir reservas fuera de horario, comprueba tú mismo hours devuelto por /availability antes de llamar al POST.

Cuerpo de la solicitud (JSON)

Ejemplo de solicitud

curl -s -X POST https://www.volleyfriends.com/api/manager-api/v1/bookings   -H "X-Api-Key: $VF_API_KEY"   -H "Content-Type: application/json"   -d '{
    "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
    "startsAt": "2026-08-12T18:00:00+02:00",
    "endsAt": "2026-08-12T19:30:00+02:00",
    "customerName": "Marta Bellini",
    "customerPhone": "+39 340 1122334",
    "customerEmail": "marta.bellini@example.com",
    "notes": "Prenotato dal sito della struttura"
  }'

Ejemplo de respuesta — 201

{
  "booking": {
    "id": "9d51c7b4-0e28-4f3a-a6d9-72b48e105c3f",
    "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
    "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
    "courtName": "Campo 1",
    "startsAt": "2026-08-12T16:00:00.000Z",
    "endsAt": "2026-08-12T17:30:00.000Z",
    "customerName": "Marta Bellini",
    "customerPhone": "+39 340 1122334",
    "customerEmail": "marta.bellini@example.com",
    "priceCents": 3000,
    "playersCount": null,
    "status": "confirmed",
    "paymentMethod": null,
    "paymentLink": null,
    "notes": "Prenotato dal sito della struttura",
    "source": "api",
    "recurrenceId": null,
    "createdAt": "2026-07-28T09:14:02.517Z",
    "updatedAt": "2026-07-28T09:14:02.517Z"
  }
}

En el ejemplo no se había indicado priceCents: 90 minutos en un tramo de 20,00 €/hora dan 3000 céntimos (el cálculo es proporcional a los minutos reales, con la tarifa del tramo en el que comienza la reserva).

Errores específicos

// 409 — solapamiento
{ "error": "overlap", "message": "Il campo è già prenotato in quell'orario." }

// 409 — cierre extraordinario (el motivo, si lo indica el administrador, está en el mensaje)
{ "error": "venue_closed", "message": "Struttura chiusa in quella data (manutenzione)." }

6.4 Modificación de reserva

Actualiza una reserva existente. Es una actualización parcial: envía solo los campos que cambian, los demás permanecen sin cambios. El cuerpo debe contener al menos un campo.

No existe un endpoint de cancelación: para cancelar una reserva se establece status: "cancelled". El historial permanece en el panel y el hueco vuelve a quedar libre (las reservas canceladas no ocupan la pista y no generan overlap).

Parámetro de ruta

Cuerpo de la solicitud (JSON)

Todos los campos son opcionales. Los marcados como «anulable» aceptan null para vaciar el valor.

Ejemplo de solicitud — desplazamiento y cobro

curl -s -X PATCH   https://www.volleyfriends.com/api/manager-api/v1/bookings/9d51c7b4-0e28-4f3a-a6d9-72b48e105c3f   -H "X-Api-Key: $VF_API_KEY"   -H "Content-Type: application/json"   -d '{
    "startsAt": "2026-08-12T19:00:00+02:00",
    "endsAt": "2026-08-12T20:30:00+02:00",
    "status": "paid",
    "paymentMethod": "cash",
    "priceCents": 3000
  }'

Ejemplo de solicitud — cancelación

curl -s -X PATCH   https://www.volleyfriends.com/api/manager-api/v1/bookings/9d51c7b4-0e28-4f3a-a6d9-72b48e105c3f   -H "X-Api-Key: $VF_API_KEY"   -H "Content-Type: application/json"   -d '{ "status": "cancelled" }'

Ejemplo de respuesta — 200

La reserva actualizada, en el mismo formato que la POST:

{
  "booking": {
    "id": "9d51c7b4-0e28-4f3a-a6d9-72b48e105c3f",
    "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
    "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
    "courtName": "Campo 1",
    "startsAt": "2026-08-12T17:00:00.000Z",
    "endsAt": "2026-08-12T18:30:00.000Z",
    "customerName": "Marta Bellini",
    "customerPhone": "+39 340 1122334",
    "customerEmail": "marta.bellini@example.com",
    "priceCents": 3000,
    "playersCount": null,
    "status": "paid",
    "paymentMethod": "cash",
    "paymentLink": null,
    "notes": "Prenotato dal sito della struttura",
    "source": "api",
    "recurrenceId": null,
    "createdAt": "2026-07-28T09:14:02.517Z",
    "updatedAt": "2026-07-28T11:02:47.883Z"
  }
}

Errores específicos

6.5 Disponibilidad de una pista en un día

Devuelve, para una pista y un día, los slots ocupados, los horarios de apertura de ese día de la semana y el posible cierre extraordinario. Es el endpoint que se debe usar para calcular los slots libres en un sitio web externo sin duplicar las reglas del sistema de gestión: resta las reservas de la ventana de apertura.

Se enumeran todos los slots que ocupan la pista, en cualquier estado excepto cancelled: por lo tanto, también las solicitudes de reserva online que aún estén pending. El día es el local italiano y los intervalos son semiabiertos: una reserva que termina exactamente a medianoche pertenece al día anterior. Una reserva que abarca la medianoche aparece en ambos días que interseca, con sus instantes reales (que pueden caer fuera del día solicitado).

Parámetros (query string)

Ejemplo de solicitud

curl -s -G https://www.volleyfriends.com/api/manager-api/v1/availability   -H "X-Api-Key: $VF_API_KEY"   --data-urlencode "courtId=7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05"   --data-urlencode "date=2026-08-12"

Ejemplo de respuesta — 200

{
  "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
  "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
  "date": "2026-08-12",
  "timezone": "Europe/Rome",
  "hours": {
    "weekday": 2,
    "openMinute": 540,
    "closeMinute": 1380,
    "closed": false,
    "configured": true
  },
  "closure": null,
  "bookings": [
    {
      "startsAt": "2026-08-12T16:00:00.000Z",
      "endsAt": "2026-08-12T17:30:00.000Z",
      "status": "confirmed"
    },
    {
      "startsAt": "2026-08-12T18:00:00.000Z",
      "endsAt": "2026-08-12T19:00:00.000Z",
      "status": "paid"
    },
    {
      "startsAt": "2026-08-12T19:00:00.000Z",
      "endsAt": "2026-08-12T20:30:00.000Z",
      "status": "pending"
    }
  ]
}

Campos de la respuesta

Errores específicos

6.6 Tarifas de una pista

Las tarifas de la pista en solo lectura: sirve para mostrar los precios al cliente antes de la reserva, con las mismas franjas que el sistema de gestión utiliza para calcular el precio automático. Las franjas solo se modifican desde el panel. Están ordenadas por fromMinute creciente.

Parámetros (query string)

Ejemplo de solicitud

curl -s -G https://www.volleyfriends.com/api/manager-api/v1/rates   -H "X-Api-Key: $VF_API_KEY"   --data-urlencode "courtId=7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05"

Ejemplo de respuesta — 200

{
  "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
  "rates": [
    {
      "id": "4a1e0b72-6d35-4c81-93af-0b7e2d5814c6",
      "label": "Mattina infrasettimanale",
      "daysMask": 31,
      "fromMinute": 480,
      "toMinute": 840,
      "pricePerHourCents": 1500,
      "pricingMode": "court",
      "minPlayers": null
    },
    {
      "id": "c07d9b31-8f42-4a05-b6e9-15d3c8017a2b",
      "label": "Serale",
      "daysMask": 127,
      "fromMinute": 1080,
      "toMinute": 1380,
      "pricePerHourCents": 600,
      "pricingMode": "person",
      "minPlayers": 10
    }
  ]
}

Campos de la respuesta

Errores específicos

Un campo sin lista de precios responde 200 con "rates": [].

7. Convenciones de datos

7.1 Fechas y horarios

• De entrada los instantes son cadenas ISO 8601 con offset obligatorio: 2026-08-12T18:00:00+02:00 o 2026-08-12T18:00:00Z. Una cadena sin offset (2026-08-12T18:00:00) se rechaza con 400: sería ambigua, y para un calendario es una ambigüedad que se paga con reservas incorrectas de una hora.
• De salida los instantes están siempre normalizados en UTC con sufijo Z y milisegundos: "2026-08-12T16:00:00.000Z". Conviértelos al huso local antes de mostrarlos.
• Las fechas sin hora (date, closure.from, closure.to y from/to cuando los usas en formato de día) son AAAA-MM-GG y se refieren al día local italiano.
• Los intervalos son semiabiertos [inizio, fine): 18:00–19:00 y 19:00–20:00 no están en conflicto.

7.2 Huso horario

Las reservas se conservan como instantes absolutos, pero todas las reglas del calendario — día de la semana, franjas de precios, horarios de apertura, fechas de cierre, límites del día — se evalúan en la zona horaria Europe/Rome, con el horario de verano gestionado automáticamente. El campo timezone de la respuesta de /availability lo declara explícitamente. Si tu servidor funciona en UTC o en otra zona horaria, no conviertas a mano los minutos: ya están expresados en hora local italiana.

7.3 Minutos desde la medianoche

Los horarios «de calendario» (openMinute, closeMinute, fromMinute, toMinute) son enteros de 0 a 1440 que cuentan los minutos desde la medianoche local. Conversiones: ore = ⌊m / 60⌋, minuti = m mod 60.

7.4 Importes

Todos los importes son enteros en céntimos de euro (priceCents, pricePerHourCents): ningún valor en coma flotante, ningún símbolo de moneda. 2000 = 20,00 €. En una reserva, priceCents: null significa «precio por definir» y es diferente de 0, que significa «gratuito».

7.5 Estados de una reserva

7.6 Origen y método de pago

Ambos son dominios de texto: se pueden añadir nuevos valores en el futuro sin cambiar de versión, por lo que tu código no debe fallar ante un valor que no conozca.

7.7 Datos personales de los clientes

El nombre, teléfono y email que envías en las reservas son datos personales de tus clientes: tú eres el responsable del tratamiento, VolleyFriends los conserva por tu cuenta como encargado del tratamiento de acuerdo con el art. 28 GDPR. Envía solo lo necesario para la gestión de la pista e informa a tus clientes. Los detalles se encuentran en la privacy policy.

8. Errores generales

Cada error tiene el mismo cuerpo: un código estable en error, pensado para tu código, y un message en italiano, pensado para las personas. Toma tus decisiones sobre error y sobre el estado HTTP, no sobre el texto del mensaje, que puede cambiar.

{
  "error": "overlap",
  "message": "Il campo è già prenotato in quell'orario."
}

Los errores de validación añaden issues, la lista detallada de los problemas campo por campo:

{
  "error": "invalid_input",
  "message": "Dati non validi",
  "issues": [
    {
      "code": "invalid_string",
      "validation": "datetime",
      "path": ["startsAt"],
      "message": "Invalid datetime"
    }
  ]
}

Una ruta inexistente bajo la base responde 404; lo mismo se aplica a un método no previsto en una ruta existente:

{
  "error": "not_found",
  "message": "Risorsa non trovata"
}

Las respuestas 502, 503 y 504 llegan desde el proxy inverso cuando la API no está accesible (reinicio o mantenimiento): en esos casos no se garantiza que el cuerpo esté en formato JSON. Trátalas como errores temporales e inténtalo de nuevo con backoff, sin intentar leer su contenido.

9. Versiones y compatibilidad

La versión está en la ruta: /manager-api/v1. No existen encabezados de versión ni fechas de lanzamiento que especificar: la única versión publicada actualmente es la v1.

Qué podemos cambiar sin avisarte

• Añadir campos a las respuestas existentes.
• Añadir parámetros opzionales a las solicitudes, con un valor predeterminado que conserve el comportamiento actual.
• Añadir nuevos endpoints bajo /v1.
• Añadir valores a los campos de texto abiertos (source, paymentMethod, surface).
• Reformular los message de los errores, manteniendo invariables los códigos error.

Qué no cambia dentro de la v1

• Ningún campo será eliminado o renombrado de las respuestas.
• Ningún campo cambiará de tipo o significado.
• Ningún parámetro hoy opcional pasará a ser obligatorio.
• Los códigos error y los estados HTTP documentados aquí seguirán siendo los mismos.

Cualquier modificación que rompa estas garantías llegará con un nuevo prefijo (/v2), manteniendo la v1 en servicio y con un aviso previo a los gestores que la estén utilizando.

Registro de cambios

10. Soporte para la integración

Para preguntas técnicas, comportamientos inesperados o solicitudes de endpoints que no encuentres aquí, escríbenos desde la página Contacto. Para ir directo al grano, indica en el mensaje:

• endpoint y método que estás llamando;
• fecha y hora de la llamada (con la zona horaria) y el código HTTP recibido;
• código error y mensaje de la respuesta;
• prefijo de la clave utilizada (ej. vfk_9f2c).

Si necesitas probar la integración sin tocar el calendario real, crea una instalación de prueba con una pista dedicada y usa esa: todas las llamadas están limitadas a las instalaciones del propietario de la clave, por lo que el resto de tu cuenta no está involucrado.