API de Playtomic: Guía Completa

La API de Playtomic permite a los clubs acceder a sus datos de reservas y pagos desde sistemas externos. Esta guía explica quién puede usarla, cómo obtener las credenciales, qué datos están disponibles y cuáles son los límites.

¿Qué es la API de Playtomic?

La API de Playtomic es una interfaz segura y de solo lectura que permite a los clubs acceder a sus datos de reservas y pagos desde otros sistemas. Tanto si gestionas un club como varios, puedes usarla para:

• Integrarla con tus sistemas actuales, como CRM, herramientas de marketing, plataformas de fidelización o software de gestión de instalaciones
• Acceder a los datos de reservas de los últimos 3 meses y a todas las reservas futuras
• Acceder a datos detallados de pagos, incluidos periodos de más de 1 año de antigüedad
• Automatizar la sincronización de datos para agilizar la gestión del club
• Mejorar la comunicación con los socios a través de herramientas y plataformas externas

¿Quién puede acceder a la API?

El acceso a la API está disponible para:

• Clubs con una sola sede que tengan un plan de suscripción Champion o Master
• Clubs con varias sedes en los que cada tenant tenga una suscripción Champion o Master
• Propietarios de cadenas, que obtienen acceso unificado a los datos de todos los clubs de su organización

¿Qué datos puedo obtener de la API?

La API es de solo lectura. Puedes consultar datos, pero no crearlos, editarlos ni eliminarlos.

Reservas

• ID de la reserva y marcas de tiempo (UTC)
• Información de la pista (ID, nombre)
• Datos de los jugadores (ID, correo electrónico, preferencias de comunicación)
• Información del pago
• Y más (consulta la especificación completa de los datos)

Pagos

• Datos detallados de cada pago y reembolso de tu club, incluidos el ID del pago y el ID del reembolso
• Consulta la documentación del endpoint de pagos para ver todos los campos

¿Qué funcionalidades llegarán próximamente?

Estamos trabajando en:

• Endpoints de datos de jugadores (con la misma autorización)
• Datos detallados de eventos, actividades y clínicas

Contacta con tu gestor de cuenta para solicitar funcionalidades específicas.

¿Cómo obtengo las credenciales de la API?

Clubs individuales

Puedes crear y gestionar tus propias credenciales de la API en Playtomic Manager. Ve a Ajustes > Herramientas para desarrolladores. Desde ahí puedes:

• Generar credenciales
• Regenerar credenciales
• Eliminar credenciales
• Consultar la documentación

📄 Documentación completa de la API (v1.1)

Nota: copia tu Client ID y tu Client Secret y guárdalos en un lugar seguro. Trata tu Client Secret como una contraseña: no lo compartas públicamente ni lo expongas en código front-end. Si lo pierdes, genera nuevas credenciales. Esto invalida las anteriores.

Propietarios de cadenas

Si gestionas varios clubs como parte de una cadena:

1. Contacta con tu gestor de cuenta de Playtomic o con Customer Care por chat para solicitar acceso unificado a la API para todas tus sedes.
2. Abre el enlace seguro que recibirás con tus credenciales. El enlace es válido durante 3 días y se puede abrir 3 veces como máximo.
3. Guarda tus credenciales en un lugar seguro. El enlace caduca y no se puede volver a generar fácilmente.
4. Lee la documentación y empieza tu integración.

Nota: las credenciales de cadena dan acceso a todos los clubs de tu organización. Guárdalas en un lugar seguro y compártelas solo con los miembros autorizados de tu equipo.

¿Cómo funciona la autenticación?

La API usa OAuth 2.0:

• Client ID y Client Secret: identificadores únicos de tu club o sistema
• Token de acceso: una credencial temporal (normalmente válida durante 1 hora) que usas para las llamadas a la API

Ejemplo de solicitud de token:

POST <https://thirdparty.playtomic.io/api/v1/oauth/token>
Content-Type: application/json

{
  "client_id": "your_client_id",
  "secret": "your_client_secret"
}

Ejemplo de llamada a la API:

GET <https://thirdparty.playtomic.io/api/v1/bookings>
Authorization: Bearer your_access_token

🔒 Buenas prácticas de seguridad:

• Mantén tu Client Secret en secreto.
• No expongas nunca tus credenciales en repositorios públicos.
• Configura la renovación automática de tokens en tus sistemas.

¿Cuántos datos puedo obtener y cuáles son los límites?

Reservas

• Reservas pasadas: solo de los últimos 3 meses. Las reservas más antiguas no se devuelven.
• Reservas futuras: disponibles según su programación.
• Intervalo máximo por solicitud: 365 días (por ejemplo, los últimos 3 meses más los próximos 9 meses).

Pagos

• Intervalo máximo por solicitud: 13 meses. Esto limita la duración de cada solicitud, no hasta qué fecha puedes remontarte.
• Periodos más largos: divídelos en varias solicitudes consecutivas de hasta 13 meses cada una. Por ejemplo, de 2024 a 2026:
  1. 1 de enero de 2024 – 31 de enero de 2025
  2. 1 de febrero de 2025 – 28 de febrero de 2026
  3. 1 de marzo de 2026 – hoy
• Sin filtro de fecha: si no indicas ningún filtro de fecha, la API devuelve por defecto los últimos 13 meses.
• Tipo de fecha: cada solicitud filtra por fecha de pago o por fecha del servicio, no por ambas.
• Primera solicitud: es posible que la API responda 202 Accepted mientras prepara el historial de pagos de tu club. Esto suele tardar unos minutos. Espera y vuelve a intentarlo.

Zona horaria

• Todas las marcas de tiempo están en UTC. Asegúrate de que tus sistemas las conviertan a tu zona horaria local.
• Consulta la zona horaria de tu club en Playtomic Manager > Ajustes > Información del club.

Límites de llamadas

Las llamadas a la API tienen un límite de frecuencia (normalmente 1 llamada por minuto) para mantener la estabilidad del sistema. Consulta la documentación para ver los límites actuales.

¿Para qué puedo usar la API?

• Sincronización con el CRM: importa los datos de reservas para crear campañas de marketing segmentadas
• Análisis e informes: analiza el uso de las pistas, la frecuencia de los jugadores y los pagos
• Comunicación con los socios: envía confirmaciones y recordatorios automáticos a través de herramientas externas
• Gestión de instalaciones: intégrala con cerraduras inteligentes, iluminación u otros sistemas IoT
• Programas de fidelización: haz un seguimiento de la actividad de los socios para ofrecer recompensas y mejorar la retención

¿Dónde puedo obtener ayuda con la API?

• Gestor de cuenta: estudios de viabilidad, solicitudes de acceso para cadenas y solicitudes de funcionalidades
• Soporte técnico: resolución de problemas con la API y ayuda con la integración
• Documentación: ejemplos completos, parámetros y descripciones de los endpoints

No hay un entorno de pruebas independiente. Puedes hacer pruebas de forma segura con tus datos reales usando consultas limitadas durante el desarrollo.

Preguntas frecuentes

Autenticación y acceso

¿Cómo obtengo las credenciales de la API? Si gestionas un solo club, ve a Ajustes > Herramientas para desarrolladores en Playtomic Manager y genéralas tú mismo. Si eres propietario de una cadena, contacta con tu gestor de cuenta o con Customer Care por chat. Recibirás un enlace seguro (válido durante 3 días, que se puede abrir 3 veces como máximo) con tu Client ID y tu Client Secret.

¿Qué hago si recibo errores "Unauthorized" (401/403)? Comprueba que:

• Tu solicitud incluye la cabecera Authorization: Bearer token.
• Tu token de acceso no ha caducado. Renuévalo si es necesario.
• Tu Client ID y tu Client Secret son correctos.
• No has superado los límites de llamadas.

¿Puede otra persona de mi organización crear nuevas credenciales? Sí, pero las nuevas credenciales invalidan las anteriores. Comparte las credenciales dentro de tu organización para no interrumpir las integraciones existentes.

Acceso a los datos

¿Puedo crear o editar reservas a través de la API? No. La API es de solo lectura. Puedes consultar y analizar datos, pero no puedes crear, editar ni eliminar reservas.

¿Cuánto historial de reservas puedo obtener? Las reservas de los últimos 3 meses y todas las reservas futuras. Cada solicitud puede cubrir hasta 365 días.

¿Puedo obtener pagos de hace más de 13 meses? Sí. 13 meses es el intervalo máximo de una sola solicitud, no un límite de antigüedad de los datos. Para obtener un periodo más largo, haz varias solicitudes consecutivas de hasta 13 meses cada una.

¿Puedo obtener todas mis reservas y pagos de años anteriores?

• Pagos: sí, a través de la API. Divide el periodo en varias solicitudes de hasta 13 meses cada una.
• Reservas: no. Tanto la API como la lista de reservas de Playtomic Manager solo incluyen los últimos 3 meses.
• La sección Informes de Playtomic Manager muestra los totales de periodos anteriores, pero no cada reserva o pago.

¿En qué zona horaria están las marcas de tiempo? Todas las marcas de tiempo están en UTC. Tu integración debe convertirlas a tu zona horaria local.

Gestión de varias sedes y cadenas

Como propietario de una cadena, ¿puedo acceder a los datos de todos mis clubs? Sí. Los propietarios de cadenas obtienen acceso unificado a los datos de todos los clubs de su organización. Puedes filtrar por club u obtener los datos de todas las sedes.

¿Todas las sedes necesitan una suscripción Champion o Master? Sí. Para el acceso con varias sedes, cada tenant necesita una suscripción Champion o Master.

Implementación técnica

¿Con qué frecuencia puedo llamar a la API? Se aplican límites de llamadas (normalmente 1 llamada por minuto). Consulta la documentación para ver los límites actuales.

¿Puedo probar la API antes de ponerla en marcha? No hay un entorno de pruebas independiente. Puedes hacer pruebas de forma segura con tus datos reales usando consultas limitadas.

¿Se añadirán más funcionalidades a la API? Sí. Estamos trabajando en endpoints de datos de jugadores y en datos detallados de eventos, actividades y clínicas. Contacta con tu gestor de cuenta para solicitar funcionalidades específicas.

Soporte

¿Qué información debo incluir cuando contacte con soporte?

• El mensaje de error completo
• El endpoint al que estabas llamando
• El ID de tu club
• Los pasos que ya has probado

¿A quién debo contactar según el tipo de problema?

• Acceso para cadenas: tu gestor de cuenta o Customer Care por chat
• Integración técnica: el equipo de soporte técnico
• Solicitudes de funcionalidades: tu gestor de cuenta
• Facturación o suscripción: tu gestor de cuenta

💬 ¿Necesitas ayuda?

Si tienes alguna pregunta o necesitas más ayuda, ¡no te preocupes! 😊 Siempre puedes contactarnos. ¡Estamos aquí para ayudarte!