Ir para o conteúdo

Roteiro de Homologação

Este guia orienta o processo de validação da integração com a Partner Integration API no ambiente de homologação.

Informações do ambiente de homologação

Item Valor
URL base Fornecida pela equipe de onboarding
Swagger {baseUrl}/swagger
ClientId Fornecido no onboarding
ClientSecret Fornecido no onboarding
Vigência do ambiente Conforme acordo de homologação

Acesse /swagger no browser para explorar os endpoints interativamente. Você pode autenticar diretamente pelo Swagger clicando em Authorize e inserindo Bearer {token}.

Como solicitar acesso ao ambiente

Entre em contato com a equipe de onboarding informando:

  1. Nome da empresa / assessoria
  2. Email técnico de contato
  3. URL do endpoint para recebimento de webhooks (se aplicável)

Você receberá: ClientId, ClientSecret e URL da API de homologação.

Checklist de homologação

Fase 1 — Autenticação

  • [ ] POST /api/v1/auth/token com credenciais válidas → retorna accessToken
  • [ ] POST /api/v1/auth/token com credenciais inválidas → retorna 401
  • [ ] Utilizar token expirado em qualquer endpoint → retorna 401

Fase 2 — Sincronização de Alunos

  • [ ] POST /api/v1/students/sync/full com lista de alunos → retorna 200 com created > 0
  • [ ] POST /api/v1/students/sync/full com mesmos alunos (reenvio) → retorna 200 com updated > 0 (idempotência)
  • [ ] POST /api/v1/students/sync com um novo aluno → retorna action: CREATED
  • [ ] POST /api/v1/students/sync com aluno existente → retorna action: UPDATED
  • [ ] POST /api/v1/students/sync com status: INACTIVE → retorna action: DEACTIVATED
  • [ ] POST /api/v1/students/sync sem o campo canonicalStudentId → retorna 422

Fase 3 — Check-in

  • [ ] POST /api/v1/checkins com aluno válido e ativo → retorna 201 Created, isDuplicate: false
  • [ ] GET /api/v1/checkins/{id} com ID retornado acima → retorna status: PUBLISHED
  • [ ] POST /api/v1/checkins com o mesmo partnerTransactionId → retorna 200 OK, isDuplicate: true
  • [ ] POST /api/v1/checkins com externalStudentId não sincronizado → retorna 201, GET mostra REJECTED com STUDENT_NOT_FOUND
  • [ ] POST /api/v1/checkins com aluno desativado → retorna 201, GET mostra REJECTED
  • [ ] GET /api/v1/checkins/{id} com ID inválido → retorna 404

Fase 4 — Webhooks (se habilitado)

  • [ ] Receber checkin.received após POST /checkins
  • [ ] Receber checkin.published ao final do fluxo bem-sucedido
  • [ ] Receber checkin.not-identified quando aluno não encontrado
  • [ ] Verificar assinatura HMAC do header X-Signature
  • [ ] Confirmar que correlationId do webhook bate com o da requisição original

Fase 5 — Erros e tratamentos

  • [ ] Requisição sem Authorization header → retorna 401
  • [ ] Payload inválido (campo faltando) → retorna 422 com detalhes dos campos
  • [ ] Check-in com source inválido → retorna 422

Como validar a integração

Validação básica (obrigatória)

  1. Autentique e obtenha um token válido
  2. Sincronize ao menos 3 alunos com POST /students/sync/full
  3. Registre check-in para um aluno sincronizado
  4. Consulte o check-in via GET /checkins/{id} e confirme status: PUBLISHED
  5. Teste idempotência: re-envie o mesmo check-in e confirme isDuplicate: true
  6. Teste rejeição: registre check-in para aluno não sincronizado e confirme STUDENT_NOT_FOUND

Validação avançada (recomendada)

  1. Desative um aluno e tente fazer check-in → confirme rejeição
  2. Reative o aluno e tente novamente → confirme aprovação
  3. Valide webhook se o endpoint estiver configurado

Dúvidas e suporte durante homologação

Para reportar problemas durante a homologação, forneça ao suporte:

  • O correlationId da requisição com problema (presente na resposta de erro)
  • Timestamp da requisição
  • Payload enviado (sem o clientSecret)
  • Resposta recebida

Critérios de aprovação para produção

A equipe de onboarding validará se todos os itens do checklist foram executados com sucesso antes de liberar acesso ao ambiente de produção.