Fluxo de Integração¶

Guia visual completo do fluxo recomendado para integrar com a Partner Integration API.

Visão geral¶

Autenticar
    ↓
Full Sync de Alunos (primeira vez)
    ↓
Manter Sync Incremental (recorrente)
    ↓
Registrar Check-in
    ↓
Consultar Status (opcional)
    ↓
Receber Webhooks (quando habilitado)

Etapa 1 — Autenticar¶

Quando: antes de qualquer outra chamada, e sempre que o token expirar.

POST /api/v1/auth/token

{
  "clientId": "sua-assessoria",
  "clientSecret": "sua-senha"
}

Resultado esperado: accessToken com validade de 1 hora.

Dica: implemente renovação automática do token antes de ele expirar para evitar interrupções.

Etapa 2 — Full Sync de Alunos¶

Quando: apenas na primeira implantação ou após longa interrupção.

POST /api/v1/students/sync/full

{
  "students": [
    { "canonicalStudentId": "ALUNO-001", "status": "ACTIVE" },
    { "canonicalStudentId": "ALUNO-002", "status": "ACTIVE" },
    ...
  ]
}

Objetivo: garantir que a plataforma conhece todos os alunos ativos antes de começar a registrar check-ins.

Volume: envie todos os alunos de uma vez. A plataforma suporta grandes volumes por requisição.

Etapa 3 — Sync Incremental de Alunos¶

Quando: sempre que houver mudança na base de alunos — novos cadastros, atualizações, desativações.

POST /api/v1/students/sync

{
  "students": [
    { "canonicalStudentId": "ALUNO-NOVO-003", "status": "ACTIVE" },
    { "canonicalStudentId": "ALUNO-001", "status": "INACTIVE" }
  ]
}

Frequência recomendada: envie em tempo real ou em batches periódicos (ex: a cada 15 minutos) para manter a plataforma atualizada.

Etapa 4 — Registrar Check-in¶

Quando: sempre que um aluno fizer presença no seu sistema.

POST /api/v1/checkins

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

Resultado: retorna o id do check-in na plataforma (201 Created para novo, 200 OK para duplicata).

Dica: use o partnerTransactionId como identificador único da transação no seu sistema. A plataforma garante que re-envios com o mesmo ID não geram duplicatas.

Etapa 5 — Consultar Status (opcional)¶

Quando: para verificar o resultado do processamento ou auditar um check-in.

GET /api/v1/checkins/{id}

Status finais:

Status	Significado
`PUBLISHED`	Check-in aprovado ✓
`REJECTED`	Negado (ver `rejectionReason`)

Etapa 6 — Receber Webhooks (quando habilitado)¶

Quando: se o seu sistema precisar reagir em tempo real a eventos da plataforma.

A plataforma envia notificações HTTP para o endpoint configurado no onboarding.

Consulte webhooks.md para o contrato completo.

Eventos do check-in (em ordem):

checkin.received            → check-in recebido
checkin.identified          → aluno identificado
checkin.authorization-started → verificação de autorização iniciada
checkin.authorized          → autorizado (fluxo feliz)
checkin.registered          → registrado no sistema
checkin.published           → disponibilizado ✓

Em caso de falha:

checkin.not-identified      → aluno não encontrado
checkin.rejected            → aluno sem autorização

Diagrama de decisão do check-in¶

Aluno sincronizado?
    NÃO → check-in encerrado com STUDENT_NOT_FOUND
    SIM ↓
Aluno ativo?
    NÃO → check-in encerrado com STUDENT_INACTIVE
    SIM ↓
Autorização válida?
    NÃO → check-in encerrado com motivo específico
    SIM ↓
Check-in PUBLISHED ✓

Resumo de pré-requisitos por operação¶

Operação	Pré-requisito
Auth token	Credenciais válidas (ClientId + ClientSecret)
Student Sync	Token válido
Check-in	Token válido + aluno sincronizado + autorização válida
Consulta	Token válido + ID do check-in
Webhooks	Endpoint HTTPS configurado no onboarding