Registro de Check-in¶

O check-in registra a presença de um aluno na plataforma.

Nesta etapa, o fluxo suportado é o Check-in Interno (source: INTERNAL), utilizado diretamente pelo seu sistema de gestão.

Registrar check-in¶

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

Request¶

{
  "source": "INTERNAL",
  "partnerTransactionId": "TXN-2026-07-03-001",
  "externalStudentId": "ALUNO-001",
  "occurredAt": "2026-07-03T08:30:00Z"
}

Campo	Tipo	Obrigatório	Descrição
`source`	string	sim	Origem do check-in. Nesta etapa, sempre `INTERNAL`.
`partnerTransactionId`	string	sim	Identificador único da transação no seu sistema. Usado para idempotência.
`externalStudentId`	string	sim	ID do aluno conforme enviado no `canonicalStudentId` durante a sincronização.
`occurredAt`	string (ISO 8601 UTC)	sim	Data e hora exata em que o check-in ocorreu. Deve ser UTC.

Sobre partnerTransactionId: este campo é a chave de idempotência. Use um identificador único por evento de check-in no seu sistema (ex: UUID gerado no momento do check-in, ou ID da transação do seu PDV). Não reutilize este valor para check-ins distintos.

Respostas¶

201 Created — check-in registrado com sucesso¶

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "isDuplicate": false
}

200 OK — check-in duplicado (idempotência)¶

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "isDuplicate": true
}

Campo	Tipo	Descrição
`id`	Guid	Identificador do check-in na plataforma. Use para consultar o status.
`isDuplicate`	boolean	`true` se este `partnerTransactionId` já foi processado anteriormente.

Idempotência¶

A plataforma detecta automaticamente check-ins duplicados com base na combinação de:

Tenant (seu tenant, identificado pelo token)
source
partnerTransactionId

Se você enviar o mesmo partnerTransactionId mais de uma vez:

A plataforma retorna 200 OK (não 201) com isDuplicate: true
O check-in não é processado novamente
O id retornado é o mesmo do processamento original

Isso garante que re-tentativas de rede não gerem check-ins duplicados.

Fluxo de processamento¶

Após receber o check-in, a plataforma executa automaticamente:

1. Receber        → check-in registrado
2. Identificar    → aluno localizado pelo externalStudentId
3. Autorizar      → validar se o aluno está autorizado
4. Registrar      → persistir o resultado
5. Publicar       → disponibilizar para sistemas consumidores

Se o aluno não for encontrado ou não estiver autorizado, o check-in é encerrado com o status correspondente. O id retornado permite consultar o status final via GET /api/v1/checkins/{id}.

Resultados possíveis¶

Após o processamento, o check-in pode ter os seguintes status finais:

Status	Significado
`PUBLISHED`	Check-in aprovado e registrado com sucesso
`REJECTED`	Aluno identificado, mas sem autorização válida

A plataforma também rastreia internamente o caso em que o aluno não é encontrado. Neste caso, o check-in fica com status REJECTED e o motivo indica STUDENT_NOT_FOUND. Consulte via GET /api/v1/checkins/{id} para verificar o rejectionReason.

Check-ins simultâneos de origens diferentes¶

Se o mesmo aluno realizar check-in por múltiplas origens (ex: INTERNAL e Wellhub) no mesmo instante, todos são válidos. A plataforma não trata como duplicata check-ins de origens distintas.

Erros da requisição¶

HTTP	Situação
`401`	Token ausente ou inválido
`404`	Tenant não encontrado
`422`	Campos obrigatórios ausentes ou inválidos
`500`	Erro interno — acionar suporte

Exemplos prontos¶

A coleção Postman inclui a requisição Registrar Check-in com payload pronto e script de automação que salva o id do check-in para uso imediato na consulta. Importe o arquivo postman/Partner Integration.postman_collection.json.

Check-in válido

{
  "source": "INTERNAL",
  "partnerTransactionId": "TXN-2026-07-03-001",
  "externalStudentId": "ALUNO-001",
  "occurredAt": "2026-07-03T08:30:00Z"
}

Aluno não sincronizado (resultará em REJECTED + STUDENT_NOT_FOUND)

{
  "source": "INTERNAL",
  "partnerTransactionId": "TXN-2026-07-03-002",
  "externalStudentId": "ALUNO-NAO-CADASTRADO",
  "occurredAt": "2026-07-03T08:35:00Z"
}