Rotas de Aprendizagem no POK
Uma Rota de Aprendizagem no POK Proof of Knowledge é um percurso formativo estruturado no qual uma pessoa conquista etapas (crachás ou certificados) e recebe automaticamente uma credencial final ao cumprir os requisitos da rota. Você monta a rota com grupos de etapas obrigatórias e opcionais, emite as etapas aos destinatários, e o POK acompanha o progresso e concede a credencial final por você.
O que é uma Rota de Aprendizagem?
Uma Rota de Aprendizagem permite definir a sequência de etapas que uma pessoa precisa concluir para ganhar uma credencial final. As rotas são flexíveis: cada grupo pode combinar etapas obrigatórias com etapas opcionais, e você pode definir um número mínimo de etapas opcionais a concluir.
Exemplo
Um curso de Administração de Empresas organizado por semestres:
- Semestre 1: todos os cursos são obrigatórios
- Semestre 2: 4 cursos obrigatórios, mais pelo menos 1 de 3 eletivos
- Semestre 3: apenas cursos eletivos, mas é preciso concluir pelo menos 2 de 5
- Semestre 4: cursos eletivos sem requisito mínimo
Criar uma Rota de Aprendizagem
Passo 1: Abrir a seção Rotas
- Acesse seu painel do POK pelo seletor de região.
- Abra a seção Rotas
- Clique em Nova Rota
Passo 2: Criar grupos e etapas
Depois de confirmar o nome, você chega à tela de criação, onde organiza sua rota em grupos. Cada grupo contém dois subgrupos: etapas obrigatórias e etapas opcionais.
Conceitos principais desta tela:
- Grupos: contêineres que organizam suas etapas (por exemplo, Semestre 1, Semestre 2)
- Etapas obrigatórias: precisam ser concluídas para obter a credencial final
- Etapas opcionais: o destinatário escolhe quais concluir, com ou sem requisito mínimo
- Nome do grupo: o primeiro grupo aparece sem nome por padrão. A partir do segundo, os grupos são nomeados automaticamente como "Grupo A", "Grupo B", e assim por diante. Você pode renomeá-los quando quiser
Criar etapas obrigatórias
-
No grupo atual, clique em + Adicionar em "Obrigatórias"
-
Uma caixa de diálogo se abre para você inserir o nome da etapa
-
Insira o nome (por exemplo, "Introdução à Economia")
-
Confirme
A etapa aparece na lista de obrigatórias. Repita o processo para adicionar todas as etapas obrigatórias do grupo.
Criar etapas opcionais
- No mesmo grupo, clique em + Adicionar em "Opcionais"
- Insira o nome da etapa
- Confirme
Se um grupo tem etapas opcionais, você pode definir um requisito mínimo:
- Depois de adicionar 2 ou mais etapas opcionais, aparece um campo para você escolher o número mínimo exigido
- Selecione quantas dessas etapas opcionais precisam ser concluídas (por exemplo, 2 de 5)
- Se deixar o valor em 0, as etapas são simplesmente opcionais e a pessoa pode obter a credencial final sem concluir nenhuma
Ações por etapa
Para cada etapa você pode:
- Editar: alterar o nome
- Eliminar: remover a etapa da rota
- Mover: trocar uma etapa entre obrigatória e opcional
Adicionar mais grupos
- Clique em + Adicionar grupo
- Um novo grupo (Grupo A, Grupo B, e assim por diante) é criado, e você pode renomeá-lo
- Repita o processo de adicionar etapas obrigatórias e opcionais
Requisitos para continuar
Para avançar à próxima tela, a rota precisa ter no mínimo 2 etapas obrigatórias ou exigidas no total. Por exemplo:
- 2 etapas obrigatórias no mesmo grupo
- 1 etapa obrigatória mais 1 opcional exigida
- 1 etapa obrigatória no Grupo A mais 1 etapa obrigatória no Grupo B
Quando cumprir esse requisito, clique em Continuar.
Importante: depois de salvar a rota, você não poderá eliminar etapas ou grupos, nem mover etapas entre obrigatórias e opcionais. Revise bem sua estrutura antes de continuar.
Passo 3: Configurar a credencial final
Nesta tela você define a credencial que será concedida automaticamente quando todos os requisitos forem atendidos.
- Tipo de credencial: escolha entre Certificado ou Crachá
- Tipo de design: selecione uma opção:
- Apenas certificado
- Apenas crachá
- Template: escolha um design criado previamente na seção "Visualização"
- Página personalizada: (opcional) atribua uma página de credencial para a visualização do destinatário
Dados da credencial
Preencha os campos exigidos pelo template selecionado:
- Título da credencial
- Instituição
- Atributos dinâmicos (se aplicável)
Escolher como a credencial final é emitida
Logo abaixo dos dados da credencial há um botão de alternância, Completar parâmetros via API, que define quem preenche os atributos dinâmicos da credencial final. Você escolhe isso ao criar a rota e pode alterar depois na configuração da credencial final.
Alternância desligada (opção padrão): o POK emite automaticamente. Assim que a pessoa cumpre os requisitos da rota, o POK emite a credencial final com os valores que você digitou nos campos de atributos dinâmicos. Nada mais é necessário do seu lado.
Alternância ligada: seus sistemas completam via API. Serve quando os atributos dinâmicos da credencial final contêm valores que só os seus sistemas conhecem, como uma nota final ou uma classificação na turma:
- A credencial final fica em espera, sem ser emitida, até você chamar o endpoint para completar a credencial final com o email do destinatário e os valores dos atributos dinâmicos
- Os campos de atributos dinâmicos desta tela ficam desabilitados, porque seus valores passam a chegar nessa chamada
O webhook de rota de aprendizagem concluída não tem relação com essa alternância. Ele notifica todas as conclusões de rota, nos dois modos, e não informa se a rota está esperando algo do seu lado. Isso é a própria rota que diz: você a configurou e também pode consultar via API, onde o endpoint para listar rotas e o de detalhe devolvem um campo completeParamsViaApi por rota.
Usar a credencial final como etapa de outra rota
Se esta credencial final também deve funcionar como etapa dentro de outra rota:
- Marque a caixa "Faz parte de outra rota de aprendizagem"
- Novos menus suspensos aparecem:
- Se a rota de destino tem apenas 1 grupo: selecione a etapa diretamente
- Se a rota de destino tem vários grupos: escolha primeiro o grupo e depois a etapa
Configuração de emails
- Idioma do email: escolha o idioma em que os emails da credencial serão enviados
Salvar a rota
Clique em Salvar rota. A rota está pronta para uso.
Emitir as etapas da Rota de Aprendizagem
Depois de criar a rota, você emite as etapas individualmente aos destinatários.
-
Vá para a seção Emitir (você pode emitir de forma manual ou em massa)
-
Selecione os destinatários e o tipo de emissão
-
Na seção "Rotas de aprendizagem", marque a caixa "Faz parte de uma rota de aprendizagem"
-
Novos campos aparecem:
- Rota de aprendizagem: selecione a rota criada
- Se a rota tem apenas 1 grupo: escolha diretamente a Etapa
- Se a rota tem vários grupos: selecione primeiro o Grupo e depois a Etapa
-
Para incluir mais etapas da mesma rota ou de outras, clique em + Adicionar etapa
-
Complete o restante da configuração da emissão (design, dados do destinatário, etc.)
-
Prossiga com a emissão
Progresso automático
Quando uma pessoa recebe uma etapa:
- O POK registra automaticamente qual etapa ela concluiu
- Se ela concluiu todas as etapas obrigatórias mais os requisitos mínimos de opcionais, recebe automaticamente a credencial final, a menos que a rota esteja configurada para completar seus parâmetros via API, caso em que a credencial aguarda a sua chamada
- Se ainda faltam etapas, o progresso é atualizado para que ela veja o que falta
Editar uma rota salva
Depois que a rota é salva, a edição é limitada para proteger a integridade dos seus dados.
O que você pode editar:
- Todos os dados da credencial final
O que você não pode fazer:
- Eliminar etapas
- Eliminar grupos
- Mover etapas entre obrigatórias e opcionais
- Editar uma etapa que seja a credencial final de outra rota
Se precisar de mudanças mais amplas, entre em contato com a equipe do POK.
Métricas e análise de Rotas de Aprendizagem
Na seção Rotas você pode monitorar o desempenho das suas rotas.
Métricas principais por rota:
- Participantes totais: quantas pessoas iniciaram a rota
- Completaram a rota: quantas obtiveram a credencial final
- Ver etapas: abre uma caixa de diálogo com o detalhamento por etapa
- Retenção: porcentagem de destinatários que concluíram a rota
Detalhamento por etapa
Clique em Ver etapas para ver os detalhes.
- Se a rota tem apenas 1 grupo: todas as etapas são exibidas com a quantidade de credenciais concedidas
- Se a rota tem vários grupos: cada grupo aparece como um menu suspenso que mostra:
- O total de etapas concedidas naquele grupo
- Ao expandir, o detalhe de cada etapa dentro do grupo
Com essas métricas você pode identificar quais etapas têm melhor desempenho, ver onde as pessoas travam, medir a eficiência do seu design formativo e avaliar retenção e engajamento.
Visualização do destinatário: progresso na rota
Quando uma pessoa recebe uma etapa que pertence a uma rota, ela vê um acordeão de progresso na sua credencial.
Informações gerais
- Nome da rota
- Total de etapas exigidas (etapas obrigatórias mais as opcionais exigidas)
Estrutura por grupo
- Se a rota tem vários grupos, o título de cada grupo é exibido com dois subgrupos: "Obrigatórias" e "Opcionais"
- Se a rota tem apenas 1 grupo, o título do grupo não é exibido
Subgrupo de obrigatórias
Cada etapa obrigatória é listada:
- Se já foi concluída, aparece como conquistada
- Se não, aparece como etapa pendente
Subgrupo de opcionais com requisito mínimo
O subgrupo é rotulado como "Opcionais - Exigidas X/Y", onde:
- X é a quantidade mínima exigida
- Y é a quantidade total de etapas opcionais disponíveis
Por exemplo, "Opcionais - Exigidas 2/5" significa que a pessoa precisa concluir pelo menos 2 das 5 etapas opcionais. Se ainda não concluiu nenhuma, é exibida apenas a quantidade exigida para conquistar, com o rótulo "Etapa não conquistada".
Subgrupo de opcionais sem requisito mínimo
Se não há requisito mínimo, o subgrupo só aparece quando a pessoa já conquistou pelo menos uma etapa opcional dele.
Progresso rumo à credencial final
O acordeão mostra com clareza as etapas já concluídas e exatamente quantas faltam. Quando todos os requisitos são atendidos, a credencial final é concedida automaticamente.
Rotas de Aprendizagem via API
O POK oferece uma API pública para automatizar fluxos de trabalho com rotas.
Emitir etapas via API
Primeiro, obtenha os identificadores necessários:
- ID da Rota de Aprendizagem
- ID da Etapa
Use o endpoint para listar rotas de aprendizagem.
A resposta inclui as rotas de aprendizagem existentes, todas as etapas associadas a cada rota (incluindo o grupo e o tipo: obrigatória ou opcional) e os identificadores para usar nas emissões.
Em seguida, emita uma etapa atribuída a uma rota de aprendizagem seguindo a documentação oficial do endpoint para emitir credenciais.
Inclua na solicitação:
- ID da rota
- ID da etapa
- Dados do destinatário
- Dados da credencial
Monitorar o progresso via API
Para verificar de forma programática o progresso de uma pessoa em uma rota, use o endpoint para consultar o progresso.
A resposta informa:
- Se a rota foi concluída ou não
- Quais etapas já foram obtidas
- O status atual de progresso da pessoa
Completar a credencial final via API
O webhook de rota de aprendizagem concluída chega sempre que alguém conclui uma rota, qualquer que seja a configuração dessa rota, então o evento por si só não diz se há algo a fazer. Isso se decide olhando a rota: o endpoint de detalhe da rota e o endpoint para listar rotas devolvem um campo completeParamsViaApi por rota.
Com o campo em false, a conclusão é informativa e a credencial final já foi emitida. Com o campo em true, a credencial fica sem ser emitida até você responder com o endpoint para completar a credencial final.
Inclua na solicitação:
- O email do destinatário
- O valor de cada atributo dinâmico que o template da credencial final espera
O POK valida os parâmetros contra o template antes de retomar a emissão. A emissão é assíncrona: a resposta devolve o id da credencial e seu estado atual, então consulte o detalhe da credencial para saber o resultado.
Respostas que você pode receber
- 200: o id da credencial e seu estado atual. A emissão continua em segundo plano
- 400: os parâmetros não coincidem com os que o template da credencial final espera. O corpo da resposta indica o campo com problema e o motivo
- 404: ou o id da rota não pertence à sua organização, ou aquele destinatário não tem nenhuma credencial final em espera. Uma chamada bem-sucedida libera a espera, então uma segunda chamada para um destinatário que você já completou cai aqui, assim como uma rota que não reserva sua credencial final para a API
- 409: já existe uma credencial final para aquela rota e aquele destinatário. O POK identifica a emissão por rota mais email do destinatário e recusa uma segunda. É assim que aparecem duas chamadas simultâneas, e também a repetição de uma chamada que chegou a criar a credencial. Consulte o estado da credencial antes de chamar de novo, em vez de repetir o POST
Tanto um 404 como um 409 significam que não resta nada a enviar do seu lado. Para saber qual credencial a rota acabou concedendo, use o endpoint de progresso: uma rota concluída devolve seu achievedCredential com o id que você pode acompanhar.
Ver as emissões de uma Rota de Aprendizagem
Na seção Listagens você pode monitorar toda a atividade das suas rotas.
Os listados incluem filtros em cascata:
- Nome da rota: filtre por uma rota específica
- Grupo (Módulo): escolha o grupo dentro da rota
- Etapa: selecione a etapa específica do grupo
Com esses filtros você pode ver todas as credenciais emitidas dentro de uma rota, acompanhar o progresso de cada pessoa pelas etapas e identificar quais etapas já foram concedidas.
Tem dúvidas?
Se você tiver alguma dúvida ou problema, escreva para contacto@pok.tech.
Saiba mais
Veja como as rotas de aprendizagem ajudam a estruturar programas de credenciais com várias etapas em a página da funcionalidade de rotas de aprendizagem.