API: Como obter informações de progresso e conclusão de missões

A API do Learning Rocks permite obter algumas informações sobre a status de um usuário em missões.

Clicando aqui você pode acessar a collection completa de Missões.

Informações que podem ser obtidas:

• Data de matrícula;
• Percentual de conclusão;
• Status de cada passo da missão, informando se foi ou não concluído;
• Data de finalização da missão;
• ID da matrícula;
• Nota de cada passo da missão, caso possua avaliação;
• Nota final da missão, caso possua avaliações;
• Informações de configuração, como critério de conclusão dos passos, se eles emitem ou não certificados, se existe possibilidade de retentativas em exames e etc.

Além disso, para facilitar a obtenção dos dados, é possível utilizar como critério de busca:

• O usuário: listando o status de todas as missões que o usuário se matriculou/concluiu;
• A missão: listando todos os usuários que concluíram/estão realizando a missão;
• O período: listando todas as matrículas/conclusões do período informado.

Busca por usuário

Para listar a relação de missões do usuário, é necessário enviar o comando GET para a URL: https://mission.learningrocks.io/enrollments/by_user/user_id? enrollment_status=COMPLETED. O campo “users_id” deve ser substituído pelo id do usuário, e o campo “COMPLETED” é um parâmetro ajustável, e pode ser trocado por “IN_PROGRESS”, conforme explicado abaixo.

Parâmetros

• Enrollment_status: É um parâmetro obrigatório na busca, e pode ser “COMPLETED” ou “IN_PROGRESS”. Se enviado “COMPLETED”, serão listadas missões que o usuário já concluiu. Se enviado “IN_PROGRESS”, serão listadas missões que o usuário ainda está realizando.

• Limit: Parâmetro opcional, informando o número máximo de resultados a ser recebido. O máximo é 100;
• Offset: Parâmetro opcional, informando o id da última matrícula a ser recebida.

Exemplo de URL com todos os parâmetros: https://mission.learningrocks.io/enrollments/by_user/123456?limit=10&offset=114_1wgyflf7n3qjsBNzmSTT_570031&enrollment_status=COMPLETED.

Exemplo de request e response:

Busca por missão

Para buscar informações por missão, é necessário enviar o comando GET para a URL: https://mission.learningrocks.io/enrollments/by_mission/mission_id?enrollment_status=COMPLETED. O campo “mission_id” deve ser substituído pelo id da missão buscada, e o campo “COMPLETED” é um parâmetro ajustável, e pode ser trocado por “IN_PROGRESS”, conforme explicado abaixo.

Parâmetros

• Enrollment_status: é um parâmetro obrigatório na busca, e pode ser “COMPLETED” ou “IN_PROGRESS”. Se enviado “COMPLETED”, serão listados os usuários que já concluíram a missão. Se enviado “IN_PROGRESS”, serão listados usuários que ainda estão realizando a missão.

• Limit: parâmetro opcional, informando o número máximo de resultados a ser recebido. O máximo é 100;
• Offset: parâmetro opcional, informando o ID da última matrícula a ser recebida.

Exemplo de request e response:

Busca por período

Permite buscar o histórico das matrículas dos usuários por:

• Período: Informando data de início e término da pesquisa;
• Tipo: Se o período deve considerar:
  • Matrículas que ocorreram no intervalo.
  • Finalizações de missões que ocorreram no intervalo.
  • Data de expiração do período de realização da missão.

Para isso, é necessário enviar o comando GET para a URL: https://mission.learningrocks.io/enrollments/by_period?start_date=542948400000&end_date=3698708400000&type=CREATED_AT&enrollment_status=COMPLETED. Os campos grifados se referem aos parâmetros obrigatórios da busca, conforme explicado abaixo.

Parâmetros obrigatórios

• Start_date: Início do período de busca, deve ser preenchido como “epoch” em milissegundos;
• End_date: Fim do período de busca, deve ser preenchido como “epoch” em milissegundos. O período de término deve necessariamente ser maior que o período de início;
• Type: Tipo de buscam podendo ser CREATED_AT (busca irá considerar as matrículas que ocorreram no intervalo), COMPLETED_AT (busca irá considerar conclusões que ocorreram no intervalo) ou MISSION_DUE_DATE (busca irá considerar missões expiradas no intervalo).
• Enrollment_status: Pode ser “COMPLETED” ou “IN_PROGRESS”. Se enviado “COMPLETED”, serão listados os usuários que já concluíram a missão. Se enviado “IN_PROGRESS”, serão listados usuários que ainda estão realizando a missão.

Parâmetros opcionais

• Limit: Máximo de resultados a ser recebido. O máximo é 100;
• Offset: ID da última matrícula a ser recebida.

Exemplo de request e response:

Importante

• A API irá retornar apenas informações de usuários que já estão matriculados na missão. Se o usuário estiver no público-alvo, mas não matriculado, ele não será listado;
• Para atender muitas requisições simultâneas, garantindo que o desempenho não seja comprometido, recomendamos que as requisições sejam sempre feitas de forma paginada;
• Para enviar as requisições, é necessário saber o id da missão. Essa informação deve ser obtida através dos relatórios da plataforma.