API: Validação de Check-in

A API de Validação de Check-in foi desenhada para ser simples e direta. O objetivo principal é permitir que o seu sistema de gestão (ERP) receba a solicitação de entrada do aluno e valide o acesso diretamente na sua catraca ou sistema próprio.

Entenda abaixo o fluxo completo de funcionamento.

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

O primeiro passo para o seu ERP é autenticar a unidade do seu cliente ao seu sistema.

• Realize a requisição pelo endpoint de autenticação para que a TotalPass reconheça o vínculo.

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

• Esse token deve ser usado para utilizar todos os endpoints relacionados aos webhooks.

   

⚠️ Atenção à validade do Token: Ele expira a cada 24 horas. Você só precisa gerar um novo token se for realizar alguma alteração ou consulta no endereço de recebimento dos webhooks.

2. Cadastro e Gestão de Webhooks

Para que a TotalPass saiba para onde enviar as informações quando um aluno fizer check-in, você precisará cadastrar uma URL de recebimento (webhook) nessa unidade.

• Faça o cadastro através do endpoint de criação de webhook.

• Dica de Arquitetura: Você pode usar o mesmo endereço de webhook para todas as unidades vinculadas ao seu ERP. Porém, é fundamental que exista um tratamento a nível de código no seu sistema para identificar as unidades através de suas credenciais.

   

Para o gerenciamento dessas URLs, disponibilizamos endpoints específicos de:

• Update (atualização) do endereço.

• Deleção do endereço.

• Buscar todos os endereços.

   

3. O Fluxo de Recebimento e Validação do Check-in

Com a academia autenticada e o webhook cadastrado, o fluxo de acesso passa a funcionar da seguinte forma:

1. Sempre que um aluno da TotalPass realizar o check-in no aplicativo, nós enviaremos um webhook para a sua URL com todas as informações daquele acesso e um link exclusivo para a validação.

2. Para liberar a entrada (validar o check-in), o seu sistema precisa fazer uma requisição do tipo POST no link enviado dentro da variável "endpoint" do payload do webhook.

⌛️ Prazo Limite de Validação: Todos os check-ins possuem 90 minutos para serem validados através do POST. Após esse tempo limite, o check-in será considerado expirado pela TotalPass.

4. Erros Comuns e Hardwares de Terceiros

Como ERP, você pode utilizar o fluxo de validação da nossa API para acionar integrações com catracas, sistemas de reconhecimento facial ou biometria da unidade. Importante: A TotalPass se responsabiliza e auxilia exclusivamente na integração com as nossas APIs, não oferecendo suporte para integrações com hardwares de terceiros.

Entendendo o Erro HTTP 422: A nossa integração não bloqueia o uso do Portal da TotalPass por parte do cliente. O cliente sempre poderá validar o check-in manualmente pela nossa plataforma.

• Caso a recepção valide o check-in manualmente antes do seu sistema, a sua tentativa de validação via API retornará o erro 422 - Check-in não disponível (pois ele já foi validado).

• Lembre-se sempre de alinhar previamente com o seu cliente qual será o fluxo operacional oficial (manual ou automatizado via ERP) para evitar esse conflito.