Sincronização de Alunos

Antes de registrar qualquer check-in, os alunos precisam estar cadastrados na plataforma.

O processo de Student Sync é a forma de informar à API quais alunos existem no seu sistema e quais integrações cada um possui.

---

Por que é obrigatório?

A plataforma valida o aluno antes de autorizar cada check-in. Alunos não sincronizados terão seus check-ins recusados com o status STUDENT_NOT_FOUND.

---

Dois endpoints disponíveis

Endpoint	Quando usar
POST /api/v1/students/sync	Sincronização incremental — enviar apenas novos alunos ou alterações
POST /api/v1/students/sync/full	Sincronização completa — enviar toda a base de alunos

Ambos utilizam o mesmo payload e retornam a mesma estrutura de resposta.

---

Quando usar cada um

Sync incremental (/students/sync)

Use para: - Cadastrar um novo aluno - Atualizar o plano de um aluno existente - Desativar um aluno que saiu

Envie apenas os alunos que mudaram desde a última sincronização.

Full Sync (/students/sync/full)

Use para: - Primeira implantação — enviar toda a base de uma vez - Recuperação de inconsistências — garantir que a plataforma está com os dados corretos - Após interrupção prolongada — quando não é possível saber quais registros mudaram

O Full Sync é equivalente ao Sync em termos de comportamento por aluno — a diferença está apenas na intenção de uso. A plataforma processa cada aluno individualmente: cria se não existe, atualiza se já existe.

---

Payload

POST /api/v1/students/sync
Authorization: Bearer {token}
Content-Type: application/json

{
  "students": [
    {
      "canonicalStudentId": "ALUNO-001",
      "wellhubMemberId": "WH12345",
      "totalPassMemberId": null,
      "status": "ACTIVE"
    },
    {
      "canonicalStudentId": "ALUNO-002",
      "wellhubMemberId": null,
      "totalPassMemberId": "TP98765",
      "status": "ACTIVE"
    }
  ]
}

Campos do payload

Campo	Tipo	Obrigatório	Descrição
students	array	sim	Lista de alunos a sincronizar
students[].canonicalStudentId	string	sim	Identificador único do aluno no seu sistema. Máx. 200 caracteres.
students[].wellhubMemberId	string	não	ID do aluno no Wellhub. Omitir ou enviar null se não aplicável.
students[].totalPassMemberId	string	não	ID do aluno no TotalPass. Omitir ou enviar null se não aplicável.
students[].status	string	sim	ACTIVE ou INACTIVE

Importante: o canonicalStudentId deve ser o identificador permanente do aluno no seu sistema. Este é o mesmo valor que você enviará como externalStudentId nos check-ins do tipo INTERNAL.

---

Resposta — 200 OK

{
  "total": 2,
  "created": 1,
  "updated": 1,
  "deactivated": 0,
  "results": [
    {
      "studentIdentityId": "550e8400-e29b-41d4-a716-446655440001",
      "canonicalStudentId": "ALUNO-001",
      "action": "CREATED"
    },
    {
      "studentIdentityId": "550e8400-e29b-41d4-a716-446655440002",
      "canonicalStudentId": "ALUNO-002",
      "action": "UPDATED"
    }
  ]
}

Campos da resposta

Campo	Tipo	Descrição
total	integer	Total de alunos processados
created	integer	Novos alunos cadastrados
updated	integer	Alunos existentes atualizados
deactivated	integer	Alunos desativados (status: INACTIVE)
results[].studentIdentityId	Guid	ID interno do aluno na plataforma
results[].canonicalStudentId	string	Seu ID do aluno (espelho do enviado)
results[].action	string	CREATED, UPDATED ou DEACTIVATED

---

Comportamentos importantes

Idempotência

Enviar o mesmo aluno múltiplas vezes é seguro. A plataforma cria na primeira vez e atualiza nas seguintes, sem duplicar registros.

Desativação

Para desativar um aluno, envie "status": "INACTIVE". O histórico de check-ins do aluno é preservado; apenas novos check-ins serão recusados.

Reativação

Para reativar, envie "status": "ACTIVE" novamente.

Alunos sem parceiros externos

Alunos que usam apenas check-in interno (sem Wellhub ou TotalPass) devem ser sincronizados normalmente, com wellhubMemberId e totalPassMemberId como null.

---

Exemplos prontos

A coleção Postman inclui requisições de Sync e Full Sync com payloads de exemplo prontos para usar. Importe o arquivo postman/Partner Integration.postman_collection.json.

Exemplos de payload:

Aluno sem parceiros externos (apenas check-in interno)

{
  "students": [
    {
      "canonicalStudentId": "ALUNO-001",
      "wellhubMemberId": null,
      "totalPassMemberId": null,
      "status": "ACTIVE"
    }
  ]
}

Aluno com Wellhub

{
  "students": [
    {
      "canonicalStudentId": "ALUNO-002",
      "wellhubMemberId": "WH-MEMBER-98765",
      "totalPassMemberId": null,
      "status": "ACTIVE"
    }
  ]
}

Aluno com TotalPass

{
  "students": [
    {
      "canonicalStudentId": "ALUNO-003",
      "wellhubMemberId": null,
      "totalPassMemberId": "TP-MEMBER-54321",
      "status": "ACTIVE"
    }
  ]
}