Perguntas Frequentes (FAQ)¶
Autenticação¶
O token JWT expira. Com que frequência preciso renová-lo?¶
O token expira após o período indicado no campo expiresIn da resposta (padrão: 3600 segundos = 1 hora). Recomendamos renovar alguns minutos antes da expiração para evitar interrupções. Ao receber 401 Unauthorized, basta chamar POST /api/v1/auth/token novamente com as mesmas credenciais.
Posso usar o mesmo token em múltiplos workers / processos paralelos?¶
Sim. O token é stateless (JWT) e pode ser reutilizado por múltiplas instâncias simultaneamente, desde que ainda seja válido.
O clientSecret é enviado junto nas requisições?¶
Não. O clientSecret é usado apenas em POST /api/v1/auth/token. Após obter o token, use apenas o accessToken nas demais requisições.
Sincronização de Alunos¶
É obrigatório sincronizar os alunos antes de fazer check-in?¶
Sim. A plataforma valida o aluno antes de autorizar cada check-in. Alunos não sincronizados resultarão em check-in com rejectionReason: STUDENT_NOT_FOUND.
O que acontece se eu sincronizar o mesmo aluno duas vezes?¶
A operação é idempotente. Na primeira vez o aluno é criado (action: CREATED), nas seguintes ele é atualizado (action: UPDATED) — sem duplicação de registros.
Posso enviar centenas de alunos em uma única requisição?¶
Sim. A plataforma suporta grandes volumes por requisição. Para a primeira implantação, use POST /api/v1/students/sync/full e envie todos os alunos de uma vez.
Qual a diferença entre Sync Incremental e Full Sync?¶
O comportamento por aluno é idêntico — a plataforma cria se não existe, atualiza se já existe. A diferença é de intenção:
- Sync Incremental (
/students/sync): use no dia a dia para enviar apenas alunos novos ou alterados - Full Sync (
/students/sync/full): use na primeira implantação ou para garantir consistência total quando não é possível rastrear apenas as mudanças
Desativei um aluno e quero reativá-lo. Como fazer?¶
Envie o aluno novamente via POST /api/v1/students/sync com "status": "ACTIVE". O histórico de check-ins é preservado.
Um aluno pode ter múltiplos IDs (Wellhub, TotalPass e interno ao mesmo tempo)?¶
Sim. O canonicalStudentId é o ID principal do aluno no seu sistema. Os campos wellhubMemberId e totalPassMemberId são opcionais e independentes. Um aluno pode ter todos preenchidos simultaneamente.
Check-in¶
O que é o partnerTransactionId?¶
É o identificador único da transação de check-in no seu sistema. Use um ID que seja único por evento de check-in — por exemplo, um UUID gerado no momento do check-in ou o ID interno do seu PDV. A plataforma usa este campo para garantir idempotência.
O que acontece se eu enviar o mesmo check-in duas vezes?¶
A plataforma detecta a duplicata pela combinação de tenant + source + partnerTransactionId e retorna 200 OK com isDuplicate: true. O check-in não é reprocessado e o mesmo id é retornado. Isso é intencional e seguro — re-tentativas de rede não geram duplicatas.
O check-in retornou 201 Created mas o status está REJECTED. Por quê?¶
O 201 Created confirma que o check-in foi recebido pela plataforma. O processamento ocorre de forma assíncrona. Consulte GET /api/v1/checkins/{id} para verificar o status final e o rejectionReason. Os motivos mais comuns são STUDENT_NOT_FOUND (aluno não sincronizado) e STUDENT_INACTIVE (aluno desativado).
O externalStudentId no check-in deve ser o mesmo que o canonicalStudentId do sync?¶
Sim, exatamente. Para check-ins do tipo source: INTERNAL, o externalStudentId deve corresponder ao canonicalStudentId que você enviou na sincronização.
Posso registrar check-ins de origens diferentes para o mesmo aluno?¶
Sim. Check-ins de origens distintas (INTERNAL, Wellhub, TotalPass) são independentes e não se cancelam mutuamente.
Webhooks¶
Os webhooks são obrigatórios?¶
Não. O fluxo de integração funciona sem webhooks. Você pode sempre consultar o status de um check-in via GET /api/v1/checkins/{id}. Os webhooks são úteis quando você precisa reagir em tempo real a eventos da plataforma.
O mesmo evento pode ser entregue mais de uma vez?¶
Sim. Em caso de falha na entrega, a plataforma realiza re-tentativas. Use o campo eventId para detectar e ignorar eventos duplicados no seu sistema.
Como configuro meu endpoint de webhook?¶
O endpoint é configurado pela equipe de onboarding. Para alterar o endpoint ou a chave de assinatura após a configuração inicial, entre em contato com o suporte.
Preciso verificar a assinatura do webhook?¶
Sim, é fortemente recomendado. A assinatura HMAC-SHA256 no header X-Signature garante que o evento foi enviado genuinamente pela plataforma. Veja os exemplos de verificação em webhooks.md.
Erros e tratamento¶
Recebi 422 Unprocessable Entity. O que devo verificar?¶
Verifique se todos os campos obrigatórios estão presentes e com os valores corretos. O corpo da resposta inclui um campo errors com a lista de campos com problema e a mensagem de validação. Re-tentar sem corrigir o payload resultará no mesmo erro.
Recebi 500 Internal Server Error. O que devo fazer?¶
Registre o correlationId da resposta e entre em contato com o suporte. Não re-tente automaticamente sem verificar o estado do recurso, pois a operação pode ter sido parcialmente executada. No caso de check-ins, use o partnerTransactionId para verificar via GET /checkins/{id} se o registro ocorreu.
Como obtenho suporte durante homologação?¶
Forneça ao suporte: o correlationId da requisição problemática, o timestamp, o payload enviado (sem o clientSecret) e a resposta recebida. Consulte homologation.md para o roteiro completo.