API Playtomic: Guia Completo

A API Playtomic permite que os clubes acedam aos seus dados de reservas e pagamentos a partir de sistemas externos. Este guia explica quem a pode usar, como obter as credenciais, que dados estão disponíveis e quais são os limites.

O que é a API Playtomic?

A API Playtomic é uma interface segura e só de leitura que permite que os clubes acedam aos seus dados de reservas e pagamentos a partir de outros sistemas. Quer geres um clube ou vários, podes usá-la para:

• Integrar com os teus sistemas atuais, como CRM, ferramentas de marketing, plataformas de fidelização ou software de gestão de instalações
• Aceder aos dados de reservas dos últimos 3 meses e a todas as reservas futuras
• Aceder a dados detalhados de pagamentos, incluindo períodos com mais de 1 ano
• Automatizar a sincronização de dados para simplificar a gestão do clube
• Melhorar a comunicação com os sócios através de ferramentas e plataformas externas

Quem pode aceder à API?

O acesso à API está disponível para:

• Clubes com uma só localização com um plano de subscrição Champion ou Master
• Clubes com várias localizações em que cada tenant tem uma subscrição Champion ou Master
• Proprietários de cadeias, que têm acesso unificado aos dados de todos os clubes da sua organização

Que dados posso obter através da API?

A API é só de leitura. Podes consultar dados, mas não os podes criar, editar nem eliminar.

Reservas

• ID da reserva e registos de data e hora (UTC)
• Informações do campo (ID, nome)
• Dados dos jogadores (IDs, e-mail, preferências de comunicação)
• Informações de pagamento
• E mais (consulta a especificação completa dos dados)

Pagamentos

• Dados detalhados de cada pagamento e reembolso no teu clube, incluindo o ID do pagamento e o ID do reembolso
• Consulta a documentação do endpoint de pagamentos para ver todos os campos

Que funcionalidades vão chegar a seguir?

Estamos a trabalhar em:

• Endpoints de dados de jogadores (com a mesma autorização)
• Dados detalhados de eventos, atividades e clínicas

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

Como obtenho as credenciais da API?

Clubes individuais

Podes criar e gerir as tuas próprias credenciais da API no Playtomic Manager. Vai a Definições > Ferramentas de programador. A partir daí, podes:

• Gerar credenciais
• Voltar a gerar credenciais
• Eliminar credenciais
• Consultar a documentação

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

Nota: copia o teu Client ID e o teu Client Secret e guarda-os num local seguro. Trata o teu Client Secret como uma palavra-passe: não o partilhes publicamente nem o exponhas em código front-end. Se o perderes, gera novas credenciais. Isto invalida as anteriores.

Proprietários de cadeias

Se geres vários clubes como parte de uma cadeia:

1. Contacta o teu gestor de conta Playtomic ou o Customer Care por chat para pedir acesso unificado à API para todas as tuas localizações.
2. Abre a ligação segura que vais receber com as tuas credenciais. A ligação é válida durante 3 dias e pode ser aberta 3 vezes, no máximo.
3. Guarda as tuas credenciais num local seguro. A ligação expira e não pode ser gerada novamente com facilidade.
4. Lê a documentação e começa a tua integração.

Nota: as credenciais de cadeia dão acesso a todos os clubes da tua organização. Guarda-as num local seguro e partilha-as apenas com membros autorizados da tua equipa.

Como funciona a autenticação?

A API usa OAuth 2.0:

• Client ID e Client Secret: identificadores únicos do teu clube ou sistema
• Token de acesso: uma credencial temporária (normalmente válida durante 1 hora) que usas nas chamadas à API

Exemplo de pedido de token:

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

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

Exemplo de chamada à API:

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

🔒 Boas práticas de segurança:

• Mantém o teu Client Secret confidencial.
• Nunca exponhas as credenciais em repositórios públicos.
• Configura a renovação automática do token nos teus sistemas.

Quantos dados posso obter e quais são os limites?

Reservas

• Reservas passadas: apenas dos últimos 3 meses. As reservas mais antigas não são devolvidas.
• Reservas futuras: disponíveis conforme estão agendadas.
• Intervalo máximo por pedido: 365 dias (por exemplo, os últimos 3 meses mais os próximos 9 meses).

Pagamentos

• Intervalo máximo por pedido: 13 meses. Isto limita a duração de cada pedido, não até quando podes recuar.
• Períodos mais longos: divide-os em vários pedidos consecutivos de até 13 meses cada. Por exemplo, de 2024 a 2026:
  1. 1 de janeiro de 2024 – 31 de janeiro de 2025
  2. 1 de fevereiro de 2025 – 28 de fevereiro de 2026
  3. 1 de março de 2026 – hoje
• Sem filtro de data: se não indicares nenhum filtro de data, a API devolve, por predefinição, os últimos 13 meses.
• Tipo de data: cada pedido filtra por data de pagamento ou por data do serviço, não por ambas.
• Primeiro pedido: a API pode responder 202 Accepted enquanto prepara o histórico de pagamentos do teu clube. Normalmente, isto demora alguns minutos. Aguarda e tenta novamente.

Fuso horário

• Todos os registos de data e hora estão em UTC. Certifica-te de que os teus sistemas os convertem para o teu fuso horário local.
• Consulta o fuso horário do teu clube em Playtomic Manager > Definições > Informações do clube.

Limites de chamadas

As chamadas à API têm um limite de frequência (normalmente 1 chamada por minuto) para manter o sistema estável. Consulta a documentação para ver os limites atuais.

Para que posso usar a API?

• Sincronização com o CRM: importa dados de reservas para campanhas de marketing segmentadas
• Análise e relatórios: analisa a utilização dos campos, a frequência dos jogadores e os pagamentos
• Comunicação com os sócios: 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 sócios para recompensas e retenção

Onde posso obter ajuda com a API?

• Gestor de conta: análises de viabilidade, pedidos de acesso para cadeias e pedidos de funcionalidades
• Suporte técnico: resolução de problemas da API e ajuda com a integração
• Documentação: exemplos completos, parâmetros e descrições dos endpoints

Não existe um ambiente de testes separado. Podes testar em segurança com os teus dados reais, usando consultas limitadas durante o desenvolvimento.

Perguntas frequentes

Autenticação e acesso

Como obtenho as credenciais da API? Se geres um clube, vai a Definições > Ferramentas de programador no Playtomic Manager e gera-as tu mesmo. Se és proprietário de uma cadeia, contacta o teu gestor de conta ou o Customer Care por chat. Vais receber uma ligação segura (válida durante 3 dias e que pode ser aberta 3 vezes, no máximo) com o teu Client ID e o teu Client Secret.

O que devo fazer se receber erros "Unauthorized" (401/403)? Verifica se:

• O teu pedido inclui o cabeçalho Authorization: Bearer token.
• O teu token de acesso não expirou. Renova-o, se necessário.
• O teu Client ID e o teu Client Secret estão corretos.
• Não excedeste os limites de chamadas.

Outra pessoa da minha organização pode criar novas credenciais? Sim, mas as novas credenciais invalidam as anteriores. Partilha as credenciais dentro da tua organização para não interromper as integrações existentes.

Acesso aos dados

Posso criar ou editar reservas através da API? Não. A API é só de leitura. Podes consultar e analisar dados, mas não podes criar, editar nem eliminar reservas.

Que histórico de reservas posso obter? As reservas dos últimos 3 meses e todas as reservas futuras. Cada pedido pode abranger até 365 dias.

Posso obter pagamentos com mais de 13 meses? Sim. 13 meses é o intervalo máximo de um único pedido, não um limite de antiguidade dos dados. Para obter um período mais longo, faz vários pedidos consecutivos de até 13 meses cada.

Posso obter todas as minhas reservas e pagamentos de anos anteriores?

• Pagamentos: sim, através da API. Divide o período em vários pedidos de até 13 meses cada.
• Reservas: não. Tanto a API como a lista de reservas do Playtomic Manager só incluem os últimos 3 meses.
• A secção Relatórios do Playtomic Manager mostra os totais de períodos anteriores, mas não cada reserva ou pagamento.

Em que fuso horário estão os registos de data e hora? Todos os registos de data e hora estão em UTC. A tua integração tem de os converter para o teu fuso horário local.

Gestão de várias localizações e cadeias

Como proprietário de uma cadeia, posso aceder aos dados de todos os meus clubes? Sim. Os proprietários de cadeias têm acesso unificado aos dados de todos os clubes da sua organização. Podes filtrar por clube ou obter dados de todas as localizações.

Todas as localizações precisam de uma subscrição Champion ou Master? Sim. Para o acesso a várias localizações, cada tenant precisa de uma subscrição Champion ou Master.

Implementação técnica

Com que frequência posso chamar a API? Aplicam-se limites de chamadas (normalmente 1 chamada por minuto). Consulta a documentação para ver os limites atuais.

Posso testar a API antes de a pôr em funcionamento? Não existe um ambiente de testes separado. Podes testar em segurança com os teus dados reais, usando consultas limitadas.

Vão ser adicionadas mais funcionalidades à API? Sim. Estamos a trabalhar em endpoints de dados de jogadores e em dados detalhados de eventos, atividades e clínicas. Contacta o teu gestor de conta para pedir funcionalidades específicas.

Suporte

Que informações devo incluir quando contacto o suporte?

• A mensagem de erro completa
• O endpoint que estavas a chamar
• O ID do teu clube
• Os passos que já experimentaste

Quem devo contactar para cada tipo de problema?

• Acesso para cadeias: o teu gestor de conta ou o Customer Care por chat
• Integração técnica: a equipa de suporte técnico
• Pedidos de funcionalidades: o teu gestor de conta
• Faturação ou subscrição: o teu gestor de conta

💬 Precisas de ajuda?

Se tiveres alguma dúvida ou precisares de mais ajuda, não te preocupes! 😊 Podes sempre contactar-nos. Estamos aqui para ajudar!