# Relatório de cursos engajados (BETA)

### Endpoint

<mark style="color:red;">`GET`</mark> `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

```http
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)

```json
{
  "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": "joao@exemplo.com",
      "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.     |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.themembers.dev.br/relatorios/relatorio-de-cursos-engajados-beta.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.