La API de Playtomic Club permite a los propietarios de clubes integrar sin problemas sus datos de reservas con sistemas externos, optimizando las operaciones y mejorando la experiencia de los miembros. Esta guía completa cubre todo lo que necesitas saber sobre cómo acceder y usar nuestra API.

¿Qué es la API de Playtomic Club?

La API de Playtomic Club es una interfaz segura de solo lectura que permite a los clubes acceder a sus datos de reservas de manera programática. Ya sea que operes en una sola ubicación o gestiones múltiples instalaciones, la API te permite:

• Integrar con sistemas existentes como CRM, herramientas de marketing, plataformas de fidelización o software de gestión de instalaciones
• Acceder a datos de reservas en tiempo real e históricos de los últimos 3 meses
• Automatizar la sincronización de datos para optimizar las operaciones del club

• Mejorar la comunicación con los miembros a través de herramientas y plataformas externas

   

  📋 Nota para Clubes Syltek: Puedes usar la API con la misma visibilidad de datos que en Manager. Aunque las reservas se sincronizan desde Syltek, ten en cuenta que no todos los elementos del horario (como las clases) pueden estar sincronizados.

¿Quién puede acceder a la API?

El acceso a la API está disponible para:

• Clubes de una sola ubicación con planes de suscripción Champion o Master
• Clubes de múltiples ubicaciones donde cada inquilino tiene una suscripción Champion o Master
• Propietarios de cadenas que obtienen acceso unificado a todos los datos del club dentro de su organización

Características actuales de la API

Nuestra API de solo lectura proporciona acceso a datos de reservas completos, incluyendo:

• ID de reserva y marcas de tiempo (formato UTC)
• Información de la pista (ID, nombre)
• Detalles del jugador (IDs, correo electrónico, preferencias de comunicación)
• Información de pago
• Y mucho más (ver especificación completa de datos)

Próximas características

Estamos ampliando activamente la API con:

• Puntos de acceso a datos de jugadores (usando la misma autorización)
• Acceso mejorado al historial de pagos
• Datos detallados de eventos, actividades y clínicas

Contacta a tu gerente de cuenta para solicitar características específicas o expresar interés en capacidades futuras.

Comenzando

1. Solicitar acceso

1. Contacta a tu gerente de cuenta de Playtomic o al Servicio de Atención al Cliente a través del chat para solicitar acceso a la API
2. Recibe tus credenciales a través de un enlace seguro (válido por 3 días, máximo 3 aperturas)
3. Almacena las credenciales de forma segura - el enlace temporal expirará
4. Accede a la documentación y comienza la integración

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

⚠️ Importante: Guarda tus credenciales inmediatamente ya que el enlace de acceso expira rápidamente y no se puede regenerar fácilmente.

2. Comprender la autenticación

La API utiliza OAuth 2.0 para un acceso seguro:

Tus credenciales:

• ID de cliente y secreto de cliente: Identificadores únicos para tu club/sistema
• Token de acceso: Credencial temporal (típicamente válida por 1 hora) para llamadas a la API

Ejemplo de solicitud de token:

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

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "grant_type": "client_credentials"
}

Realizando llamadas a la API:

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

🔒 Mejores prácticas de seguridad:

• Mantén tu secreto de cliente confidencial
• Nunca expongas credenciales en repositorios públicos
• Implementa la renovación automática de tokens en tus sistemas

Especificaciones y limitaciones de datos

Manejo de zonas horarias

• Todos los sellos de tiempo están en UTC - asegúrate de que tus sistemas conviertan a la zona horaria local
• Verifica la configuración de la zona horaria de tu club en Playtomic Manager > Ajustes > Información del Club

Disponibilidad de datos

• Datos históricos: Últimos 90 días
• Reservas futuras: Disponibles según lo programado
• Rango máximo de solicitud: 365 días (90 pasados + 275 futuros, o 365 futuros)

Límites de tasa

Las llamadas a la API están sujetas a limitación de tasa (típicamente 1 llamada por minuto) para garantizar la estabilidad del sistema. Consulta la documentación para conocer los límites actuales.

Casos de uso comunes

Transforma las operaciones de tu club con estas integraciones populares:

• Sincronización de CRM: Importa datos de reservas para campañas de marketing dirigidas
• Análisis e informes: Analiza la utilización de pistas y los patrones de frecuencia de los jugadores
• Comunicación con los miembros: Envía confirmaciones y recordatorios automáticos a través de herramientas externas
• Gestión de instalaciones: Integra con cerraduras inteligentes, iluminación u otros sistemas IoT
• Programas de fidelización: Rastrea la actividad de los miembros para programas de recompensas y retención

Solución de problemas y soporte

Obteniendo ayuda

• Account Manager: Evaluación de viabilidad y solicitudes de acceso
• Soporte Técnico: Solución de problemas de API y asistencia de integración
• Documentación: Ejemplos completos, parámetros y descripciones de endpoints

Prueba de tu Integración

Aunque no proporcionamos un entorno de prueba separado, puedes probar de manera segura con tus datos de reservas reales utilizando consultas limitadas durante el desarrollo.

Preguntas Frecuentes (FAQ)

Autenticación y Acceso

P: ¿Cómo obtengo credenciales de API?

R: Contacta a tu account manager de Playtomic o al equipo de soporte. Una vez aprobado, recibirás un enlace seguro (válido por 3 días, máximo 3 aperturas) que contiene tu ID de Cliente y Secreto de Cliente.

P: ¿Qué debo hacer si recibo errores de "No autorizado" (401/403)?

R: Soluciones comunes:

• Verifica que tu encabezado Authorization: Bearer token esté incluido
• Comprueba si tu token de acceso ha expirado (actualiza si es necesario)
• Confirma que tu ID de Cliente y Secreto de Cliente son correctos

• Asegúrate de no haber excedido los límites de tasa

   

P: ¿Puede alguien más en mi organización solicitar nuevas credenciales?

R: Sí, pero importante: Las solicitudes de nuevas credenciales revocarán las antiguas. Comparte las credenciales dentro de tu organización para evitar interrumpir las integraciones existentes.

Acceso a Datos y Capacidades

P: ¿Puedo crear o modificar reservas a través de la API?

R: No, la API actual es solo de lectura. Puedes recuperar y analizar datos de reservas, pero no puedes crear, actualizar o eliminar reservas.

P: ¿Cuántos datos históricos puedo acceder?

R: Puedes acceder a datos de reservas de los últimos 90 días más todas las reservas futuras. El rango máximo de solicitud es de 365 días en total.

P: ¿En qué zona horaria están las marcas de tiempo de la API?

R: Todas las marcas de tiempo están en UTC. Tu integración debe convertirlas a tu zona horaria local. Verifica que la zona horaria de tu club esté correctamente configurada en Playtomic Manager.

Gestión de Múltiples Ubicaciones y Cadenas

P: Como propietario de una cadena, ¿tengo acceso a los datos de todos mis clubes?

R: ¡Sí! Los propietarios de cadenas reciben acceso unificado a los datos de reservas de todos los clubes en su organización. Puedes filtrar solicitudes para clubes específicos o recuperar datos de todas las ubicaciones.

P: ¿Todas las ubicaciones necesitan suscripciones Champion/Master?

R: Sí, para acceso a múltiples ubicaciones, cada inquilino debe tener un plan de suscripción Champion o Master.

Implementación Técnica

P: ¿Con qué frecuencia puedo llamar a la API?

R: Hay límites de tasa establecidos (típicamente 1 llamada por minuto) para asegurar la estabilidad del sistema. Consulta la documentación para conocer los límites actuales y planifica tu integración en consecuencia.

P: ¿Puedo probar la API antes de ponerla en producción?

R: Aunque no hay un entorno de prueba separado, puedes probar de manera segura con tus datos de reservas reales utilizando consultas limitadas durante el desarrollo.

P: ¿Se añadirán más funciones a la API?

R: ¡Sí! Estamos desarrollando activamente:

• Endpoints de datos de jugadores (misma autorización)
• Historial de pagos mejorado
• Datos detallados de eventos y clínicas

Contacta a tu account manager para solicitar funciones específicas.

Soporte y Solución de Problemas

P: ¿Qué información debo proporcionar al solicitar soporte?

R: Incluye:

• Mensaje de error completo
• Endpoint específico que estabas llamando
• Tu ID de Club

• Pasos que ya has intentado

   

P: ¿A quién debo contactar para diferentes tipos de problemas?

R:

• Solicitudes de acceso: Account manager o Atención al Cliente vía chat para solicitar acceso a la API
• Integración técnica: Equipo de soporte técnico
• Solicitudes de funciones: Account manager
• Facturación/suscripción: Account manager

¿Necesitas asistencia adicional? Contacta a tu account manager de Playtomic o a nuestro equipo de Atención al Cliente para obtener ayuda personalizada con tu integración de API.