A API do Playtomic Club permite que os proprietários de clubes integrem perfeitamente os seus dados de reservas com sistemas externos, simplificando as operações e melhorando a experiência dos membros. Este guia abrangente cobre tudo o que precisas de saber sobre como aceder e usar a nossa API.

O que é a API do Playtomic Club?

A API do Playtomic Club é uma interface segura, apenas de leitura, que permite aos clubes aceder aos seus dados de reservas programaticamente. Quer operes num único local ou gerencies várias instalações, a API permite-te:

• Integrar com sistemas existentes como CRMs, ferramentas de marketing, plataformas de fidelização ou software de gestão de instalações
• Aceder a dados de reservas em tempo real e históricos dos últimos 3 meses
• Automatizar a sincronização de dados para simplificar as operações do clube

• Melhorar a comunicação com os membros através de ferramentas e plataformas externas

   

  📋 Nota para Clubes Syltek: Podes usar a API com a mesma visibilidade de dados que no Manager. Embora as reservas sejam sincronizadas a partir do Syltek, nota que nem todos os elementos do horário (como aulas) podem ser sincronizados.

Quem Pode Aceder à API?

O acesso à API está disponível para:

• Clubes de localização única com planos de subscrição Champion ou Master
• Clubes de múltiplas localizações onde cada inquilino tem uma subscrição Champion ou Master
• Proprietários de cadeias que obtêm acesso unificado a todos os dados do clube dentro da sua organização

Funcionalidades Atuais da API

A nossa API apenas de leitura fornece acesso a dados de reservas abrangentes, incluindo:

• ID de reserva e carimbos de data/hora (formato UTC)
• Informação sobre o campo (ID, nome)
• Detalhes do jogador (IDs, email, preferências de comunicação)
• Informação de pagamento
• E muito mais (ver especificação completa dos dados)

Funcionalidades Futuras

Estamos a expandir ativamente a API com:

• Endpoints de dados de jogadores (usando a mesma autorização)
• Acesso melhorado ao histórico de pagamentos
• Dados detalhados de eventos, atividades e clínicas

Contacta o teu gestor de conta para solicitar funcionalidades específicas ou manifestar interesse em capacidades futuras.

Começar

1. Solicitar Acesso

1. Contacta o teu gestor de conta Playtomic ou o Atendimento ao Cliente via chat para solicitar acesso à API
2. Recebe as tuas credenciais através de um link seguro (válido por 3 dias, máximo de 3 aberturas)
3. Armazena as credenciais de forma segura - o link temporário expirará
4. Acede à documentação e começa a integração

📄 Documentação Completa da API (v1.1)

⚠️ Importante: Guarda as tuas credenciais imediatamente, pois o link de acesso expira rapidamente e não pode ser regenerado facilmente.

2. Compreender a Autenticação

A API usa OAuth 2.0 para acesso seguro:

As Tuas Credenciais:

• ID do Cliente & Segredo do Cliente: Identificadores únicos para o teu clube/sistema
• Token de Acesso: Credencial temporária (tipicamente válida por 1 hora) para chamadas à API

Exemplo de Pedido 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"
}

Fazer Chamadas à API:

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

🔒 Melhores Práticas de Segurança:

• Mantém o teu Segredo do Cliente confidencial
• Nunca exponhas credenciais em repositórios públicos
• Implementa a renovação automática de tokens nos teus sistemas

Especificações e Limitações dos Dados

Gestão de Fuso Horário

• Todos os carimbos de data/hora estão em UTC - garante que os teus sistemas convertem para o fuso horário local
• Verifica as definições de fuso horário do teu clube em Playtomic Manager > Definições > Informações do Clube

Disponibilidade de Dados

• Dados históricos: Últimos 90 dias
• Reservas futuras: Disponíveis conforme agendado
• Intervalo máximo de pedidos: 365 dias (90 passados + 275 futuros, ou 365 futuros)

Limites de Taxa

As chamadas à API estão sujeitas a limites de taxa (tipicamente 1 chamada por minuto) para garantir a estabilidade do sistema. Verifica a documentação para limites atuais.

Casos de Uso Comuns

Transforma as operações do teu clube com estas integrações populares:

• Sincronização de CRM: Importa dados de reservas para campanhas de marketing direcionadas
• Análise e Relatórios: Analisa a utilização do campo e padrões de frequência dos jogadores
• Comunicação com Membros: Envia confirmações e lembretes automáticos através de ferramentas externas
• Gestão de Instalações: Integra com fechaduras inteligentes, iluminação ou outros sistemas IoT
• Programas de Fidelização: Acompanha a atividade dos membros para programas de recompensas e retenção

Resolução de Problemas e Suporte

Obter Ajuda

• Gestor de Conta: Avaliação de viabilidade e pedidos de acesso
• Suporte Técnico: Resolução de problemas da API e assistência na integração
• Documentação: Exemplos completos, parâmetros e descrições de endpoints

Testar a Tua Integração

Embora não forneçamos um ambiente de teste separado, podes testar com segurança com os teus dados reais de reservas usando consultas limitadas durante o desenvolvimento.

Perguntas Frequentes (FAQ)

Autenticação & Acesso

P: Como obtenho credenciais da API?

R: Contacta o teu gestor de conta Playtomic ou a equipa de suporte. Uma vez aprovado, receberás um link seguro (válido por 3 dias, máximo de 3 aberturas) contendo o teu ID de Cliente e Segredo de Cliente.

P: O que devo fazer se receber erros de "Não Autorizado" (401/403)?

R: Soluções comuns:

• Verifica se o cabeçalho Authorization: Bearer token está incluído
• Verifica se o teu token de acesso expirou (atualiza se necessário)
• Confirma se o teu ID de Cliente e Segredo de Cliente estão corretos

• Certifica-te de que não excedeste os limites de taxa

   

P: Alguém mais na minha organização pode solicitar novas credenciais?

R: Sim, mas importante: Pedidos de novas credenciais revogarão as antigas. Partilha as credenciais dentro da tua organização para evitar interromper integrações existentes.

Acesso a Dados & Capacidades

P: Posso criar ou modificar reservas através da API?

R: Não, a API atual é apenas de leitura. Podes recuperar e analisar dados de reservas, mas não podes criar, atualizar ou eliminar reservas.

P: Quanto tempo de dados históricos posso aceder?

R: Podes aceder a dados de reservas dos últimos 90 dias mais todas as reservas futuras. O intervalo máximo de pedido é de 365 dias no total.

P: Em que fuso horário estão os timestamps da API?

R: Todos os timestamps estão em UTC. A tua integração deve converter estes para o teu fuso horário local. Verifica se o fuso horário do teu clube está corretamente definido no Gestor Playtomic.

Gestão de Múltiplas Localizações & Cadeias

P: Como proprietário de uma cadeia, tenho acesso aos dados de todos os meus clubes?

R: Sim! Os proprietários de cadeias recebem acesso unificado aos dados de reservas de todos os clubes na sua organização. Podes filtrar pedidos para clubes específicos ou recuperar dados de todas as localizações.

P: Todas as localizações precisam de subscrições Champion/Master?

R: Sim, para acesso a múltiplas localizações, cada inquilino deve ter um plano de subscrição Champion ou Master.

Implementação Técnica

P: Com que frequência posso chamar a API?

R: Existem limites de taxa (tipicamente 1 chamada por minuto) para garantir a estabilidade do sistema. Verifica a documentação para os limites atuais e planeia a tua integração em conformidade.

P: Posso testar a API antes de entrar em produção?

R: Embora não haja um ambiente de teste separado, podes testar com segurança com os teus dados reais de reservas usando consultas limitadas durante o desenvolvimento.

P: Serão adicionadas mais funcionalidades à API?

R: Sim! Estamos a desenvolver ativamente:

• Endpoints de dados de jogadores (mesma autorização)
• Histórico de pagamentos melhorado
• Dados detalhados de eventos e clínicas

Contacta o teu gestor de conta para solicitar funcionalidades específicas.

Suporte & Resolução de Problemas

P: Que informação devo fornecer ao solicitar suporte?

R: Inclui:

• Mensagem de erro completa
• Endpoint específico que estavas a chamar
• O teu ID de Clube

• Passos que já tentaste

   

P: Quem devo contactar para diferentes tipos de problemas?

R:

• Pedidos de acesso: Gestor de conta ou Atendimento ao Cliente via chat para solicitar acesso à API
• Integração técnica: Equipa de suporte técnico
• Pedidos de funcionalidades: Gestor de conta
• Faturação/subscrição: Gestor de conta

Precisas de assistência adicional? Contacta o teu gestor de conta Playtomic ou a nossa equipa de Atendimento ao Cliente para ajuda personalizada com a tua integração API.