API: Booking (Agendamentos e aulas)

A API de Booking permite que o seu sistema espelhe a grade de aulas da academia diretamente no aplicativo da TotalPass. Através dela, você gerencia não apenas a criação das aulas, mas também o controle de vagas (slots), mapas de posições e aprovação de reservas.

Veja abaixo o fluxo completo de implementação.

1. Autenticação e Geração de Token

Assim como na API de Check-in, o processo se inicia autenticando a unidade.

⚠️ Atenção Crítica: Apesar das credenciais (partner_api_key e place_api_key) serem exatamente as mesmas, os endpoints de autenticação são diferentes para cada API!

• Utilize o endpoint de autenticação de Booking para realizar o vínculo.

• A resposta retornará os planos ativos da unidade na TotalPass e o token de acesso.

• Este token expira em 24 horas. O seu sistema deve estar preparado para gerar um novo token sempre que for consumir os demais endpoints.

2. Configuração da Unidade e Webhooks

Para que as reservas feitas pelos alunos no app cheguem até o seu sistema, você precisa configurar a unidade e a URL de recebimento.

• Cadastro do Webhook: Registre a sua URL de recebimento através do endpoint de cadastro de webhook. Você pode usar o mesmo link para todas as unidades, desde que o seu código identifique a origem pelas credenciais.

• Confirmação de Reservas (Recomendado): Recomendamos fortemente habilitar a funcionalidade de "confirmação de reservas" em todos os locais autenticados para garantir a sincronização.

• Aprovação ou Recusa: Ao receber uma reserva, o seu sistema pode aprová-la ou negá-la. Caso opte por negar, é obrigatório retornar à TotalPass o campo "reason" informando o motivo dentro dos padrões previstos na documentação técnica. Essa informação de recusa também deve ficar visível para o seu cliente (a academia) dentro do painel do seu ERP.

3. Criação de Aulas (Eventos) e Gestão de Vagas (Slots)

Com o webhook configurado, você já pode enviar a grade de aulas para o app da TotalPass.

• Criar Aulas: Utilize o endpoint de criação de evento individual. Preste muita atenção aos campos obrigatórios, como plano e fuso horário — o envio em branco ou incorreto causará falhas de reserva para o aluno.

• Gestão de Vagas Externas (Sincronização): Ao criar uma aula, você define o número de vagas disponíveis (slots). Se essas vagas forem divididas com alunos de fora da TotalPass, o seu ERP deve nos avisar sempre que uma vaga for consumida externamente. Utilize o endpoint de update event occurrence slots para atualizar as vagas disponíveis e evitar overbooking.

Regras de Alteração e Cancelamento de Aulas:

• Não é possível alterar o horário (startTime) ou a data (eventDate) de uma aula já criada.

• Fluxo de reagendamento: Para mudar uma aula de horário, o seu sistema deve: 1) Criar uma nova aula com o horário correto; 2) Cancelar a antiga via PUT PUT /partner/event-occurrence/{occurrenceUuid} definindo isCancelled: true (para notificar os usuários); 3) Por fim, deletar a antiga via DELETE.

• Exclusão: Ao deletar uma aula que já possui reservas, a TotalPass cancelará as reservas automaticamente e enviará um Push/E-mail para os alunos.

4. Mapas de Posições (Seat Maps)

Se a academia utiliza bicicletas numeradas, sacos de pancada ou posições fixas, você pode utilizar a nossa funcionalidade de Seat Maps. Seu uso não é obrigatório.

• Se for utilizar, você deve criar o mapa através do endpoint de criação de mapa de posições antes de criar a aula.

• Pegue o ID devolvido e envie-o no momento da criação da aula.

• Cada mapa pertence unicamente a um local específico (o local cujo token foi utilizado para criá-lo).

• Sempre será possível fazer alterações em um mapa de posições já existente, mas é importante entender as consequências das alterações (descritas na documentação técnica).