Relatório de cursos engajados (BETA)

Lista alunos × curso para os Top N cursos com maior média de percentual de conclusão entre matrículas ativas, com métricas por aluno e a média do curso no conjunto ranqueado.

Endpoint

GET URL_BASE/partners/reports/engaged-courses/{developer_token}/{platform_token}

Parâmetros de query

Nome	Tipo	Obrigatório	Descrição
top_courses	integer	Não	Quantidade de cursos no ranking (média de conclusão). Entre 1 e 50. Padrão 10.
limit	integer	Não	Itens por página. Entre 2 e 500. Padrão 500.
cursor	string	Não	Próxima página (next_cursor).

Não há date_from / date_to: o relatório reflete o estado atual das matrículas ativas.

Cabeçalhos HTTP

Cabeçalho	Obrigatório	Observação
Accept	Recomendado	application/json.

Exemplo de requisição

GET /api/partners/reports/engaged-courses/{developer_token}/{platform_token}?top_courses=15&limit=20 HTTP/1.1
Accept: application/json

Resposta (200 OK)

Estrutura de paginação por cursor: data, path, per_page, next_cursor, next_page_url, prev_cursor, prev_page_url. path e next_page_url são URLs absolutas geradas pelo servidor.

Campos de cada item em data

Campo	Descrição
id	Chave composta: user_id + | + course_id (string).
user_id, course_id	UUIDs.
course_name, product_name	Títulos do curso e do pacote.
first_name, last_name, phone, document, email	Dados do aluno.
registration_date	accession_date da assinatura da linha.
course_completion_percent	Percentual de conclusão do curso para o aluno.
course_avg_engagement_score	Média do curso no top (repetida nas linhas do mesmo course_id).

Exemplo de resposta (trecho)

{
  "data": [
    {
      "id": "user-uuid|course-uuid",
      "user_id": "user-uuid",
      "course_id": "course-uuid",
      "course_name": "Nome do curso",
      "product_name": "Nome do produto",
      "first_name": "João",
      "last_name": null,
      "phone": null,
      "document": null,
      "email": "[email protected]",
      "registration_date": "2024-05-07 00:00:00",
      "course_completion_percent": "33.33",
      "course_avg_engagement_score": "28.50"
    }
  ],
  "path": "/api/partners/reports/engaged-courses/…",
  "per_page": 20,
  "next_cursor": "eyJwcm9nLnVzZXJfaWQiOi4uLn0",
  "next_page_url": "/api/partners/reports/engaged-courses/…?cursor=…",
  "prev_cursor": null,
  "prev_page_url": null
}

Na resposta real, path e next_page_url vêm como URL absoluta.

Paginação

1. Primeira página: envie top_courses e limit (ou use os padrões).

2. Páginas seguintes: repita exatamente os mesmos top_courses e limit e envie cursor. Se usar apenas next_page_url, confira se limit e top_courses permanecem na query.

Erros

HTTP	Situação
401	Tokens inválidos ou ausentes.
422	top_courses ou limit fora dos intervalos permitidos.
403	Possível bloqueio quando User-Agent não é enviado.