# Usuário

> Rotas da API para listar, buscar, editar e excluir alunos, consultar acessos e progresso e aplicar tags.

As rotas de usuário trabalham com os alunos da sua plataforma. Todas exigem o cabeçalho `Authorization` com uma chave de API e seguem o envelope de resposta descrito em [API](/configuracoes/api).

Base: `https://<sua-plataforma>/api/v1`

## Como identificar o aluno

Onde a rota pede um identificador de aluno (`{ident}` no caminho ou `usuario_id` no corpo), você pode usar qualquer um destes:

| Valor | Exemplo |
|---|---|
| ID do aluno na plataforma | `1234` |
| E-mail | `maria@email.com` |
| CPF ou CNPJ (com ou sem pontuação) | `242.863.810-64` ou `24286381064` |

No caminho da URL, codifique caracteres especiais (por exemplo, `@` vira `%40`).

## O objeto usuário

Várias rotas devolvem o aluno neste formato:

```json
{
  "id": 1234,
  "nome": "Maria Silva",
  "email": "maria@email.com",
  "doc": "242.863.810-64",
  "celular": "+5521999990000",
  "login_auto": "https://escola.asalahub.com/auth/login?crstk=Xy7...",
  "gratis": false,
  "criado_em": "2026-09-18T10:10:57-03:00",
  "ultimo_acesso_em": "2026-10-14T19:02:11-03:00"
}
```

| Campo | Descrição |
|---|---|
| `id` | ID do aluno |
| `nome`, `email`, `doc`, `celular` | Dados do cadastro (`doc` e `celular` podem vir `null`) |
| `login_auto` | Link de login automático do aluno (veja [Login automático](/configuracoes/api#login-automatico-do-aluno)) |
| `gratis` | `true` se o aluno se cadastrou pelo cadastro gratuito |
| `criado_em` | Data do cadastro |
| `ultimo_acesso_em` | Último login (`null` se nunca entrou) |

---

## Listar alunos

```
GET /usuario
```

Lista todos os alunos da plataforma, do mais antigo para o mais novo, **150 por página**.

| Parâmetro | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `cursor` | query | Não | Cursor da próxima página (já vem pronto em `next_page_url`) |

```bash
curl https://escola.asalahub.com/api/v1/usuario \
  -H "Authorization: ash_sua_chave_aqui"
```

```json
{
  "success": true,
  "code": 200,
  "data": {
    "paginator": {
      "perPage": 150,
      "next_page_url": "https://escola.asalahub.com/api/v1/usuario?cursor=eyJpZCI6MTUw...",
      "prev_page_url": null
    },
    "usuario": [
      {
        "id": 1234,
        "nome": "Maria Silva",
        "email": "maria@email.com",
        "doc": null,
        "celular": null,
        "login_auto": "https://escola.asalahub.com/auth/login?crstk=Xy7...",
        "gratis": false,
        "criado_em": "2026-09-18T10:10:57-03:00",
        "ultimo_acesso_em": null
      }
    ]
  },
  "profiler": { "start": 1789737057.12, "finish": 1789737057.15, "process": 0.03 }
}
```

## Buscar um aluno

```
GET /usuario/{ident}
```

| Parâmetro | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `ident` | caminho | Sim | ID, e-mail ou CPF/CNPJ do aluno |

```bash
curl https://escola.asalahub.com/api/v1/usuario/maria%40email.com \
  -H "Authorization: ash_sua_chave_aqui"
```

```json
{
  "success": true,
  "code": 200,
  "data": {
    "usuario": {
      "id": 1234,
      "nome": "Maria Silva",
      "email": "maria@email.com",
      "doc": "242.863.810-64",
      "celular": "+5521999990000",
      "login_auto": "https://escola.asalahub.com/auth/login?crstk=Xy7...",
      "gratis": false,
      "criado_em": "2026-09-18T10:10:57-03:00",
      "ultimo_acesso_em": "2026-10-14T19:02:11-03:00"
    }
  },
  "profiler": { "start": 1789737057.12, "finish": 1789737057.13, "process": 0.01 }
}
```

Se o aluno não existir, a resposta é `409` com a mensagem "Usuário não encontrado.".

## Listar os acessos de um aluno

```
GET /usuario/acesso/{ident}
```

Mostra todos os cursos a que o aluno tem ou já teve acesso, com o prazo de cada um.

| Parâmetro | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `ident` | caminho | Sim | ID, e-mail ou CPF/CNPJ do aluno |

```bash
curl https://escola.asalahub.com/api/v1/usuario/acesso/1234 \
  -H "Authorization: ash_sua_chave_aqui"
```

```json
{
  "success": true,
  "code": 200,
  "data": {
    "usuario": { "id": 1234, "nome": "Maria Silva", "email": "maria@email.com", "...": "..." },
    "acesso": [
      {
        "produto": { "id": 12, "ordem": 1, "nome": "Atendimento que Encanta", "oferta_url": null },
        "duracao": "12",
        "duracao_tipo": "months",
        "comecou_em": "2026-09-18T10:11:02-03:00",
        "encerra_em": "2027-09-18T10:11:02-03:00",
        "encerrado": false
      },
      {
        "produto": { "id": 15, "ordem": 2, "nome": "Comercial que Vende", "oferta_url": "https://loja.exemplo.com/comercial" },
        "duracao": null,
        "duracao_tipo": "vitalicio",
        "comecou_em": "2026-10-01T08:00:00-03:00",
        "encerra_em": null,
        "encerrado": false
      }
    ]
  },
  "profiler": { "start": 1789737057.12, "finish": 1789737057.13, "process": 0.01 }
}
```

| Campo | Descrição |
|---|---|
| `produto` | Curso do acesso (`oferta_url` é o link de oferta configurado no curso, se houver) |
| `duracao` + `duracao_tipo` | Prazo do acesso: `years`, `months` ou `days`; `vitalicio` (com `duracao` nula) quando não expira |
| `comecou_em` / `encerra_em` | Início e fim do acesso (`encerra_em` nulo = vitalício) |
| `encerrado` | `true` se o acesso foi retirado (reembolso, cancelamento, à mão) ou já venceu |

## Ver o progresso de um aluno em um curso

```
GET /usuario/progresso_por_produto/{ident}/{produto}
```

| Parâmetro | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `ident` | caminho | Sim | ID, e-mail ou CPF/CNPJ do aluno |
| `produto` | caminho | Sim | ID do curso (veja [Produto](/configuracoes/api-produto)) |

```bash
curl https://escola.asalahub.com/api/v1/usuario/progresso_por_produto/1234/12 \
  -H "Authorization: ash_sua_chave_aqui"
```

```json
{
  "success": true,
  "code": 200,
  "data": {
    "progresso": {
      "total": "33.3%",
      "assistidas": 2,
      "completas": 1,
      "aulas": [
        {
          "item_id": 501,
          "count": 3,
          "acesso_em": "2026-10-14 22:02:11",
          "aula": { "id": 501, "ordem": 1, "nome": "Boas-vindas" }
        },
        {
          "item_id": 502,
          "count": 1,
          "acesso_em": "2026-10-14 22:15:40",
          "aula": { "id": 502, "ordem": 2, "nome": "O cliente no centro" }
        }
      ]
    }
  },
  "profiler": { "start": 1789737057.12, "finish": 1789737057.14, "process": 0.02 }
}
```

| Campo | Descrição |
|---|---|
| `total` | Percentual de aulas publicadas concluídas pelo aluno |
| `assistidas` | Quantas aulas o aluno abriu ou concluiu |
| `completas` | Quantas aulas o aluno concluiu |
| `aulas[].count` | Quantas vezes o aluno abriu a aula |
| `aulas[].acesso_em` | Último acesso à aula, no formato `AAAA-MM-DD HH:MM:SS` (horário UTC) |
| `aulas[].aula.ordem` | Posição da aula no curso, considerando só as aulas publicadas |

## Listar alunos de uma tag

```
GET /usuario/lista_por_tag/{tag}
```

Lista os alunos que têm a tag, **150 por página**.

| Parâmetro | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `tag` | caminho | Sim | ID da tag (veja [Tag](/configuracoes/api-tag)) |
| `cursor` | query | Não | Cursor da próxima página |

```bash
curl https://escola.asalahub.com/api/v1/usuario/lista_por_tag/7 \
  -H "Authorization: ash_sua_chave_aqui"
```

```json
{
  "success": true,
  "code": 200,
  "data": {
    "paginator": { "perPage": 150, "next_page_url": null, "prev_page_url": null },
    "usuario": [
      { "id": 1234, "nome": "Maria Silva", "email": "maria@email.com", "...": "..." }
    ]
  },
  "profiler": { "start": 1789737057.12, "finish": 1789737057.13, "process": 0.01 }
}
```

## Adicionar uma tag ao aluno

```
POST /usuario/adicionar_tag
```

| Parâmetro | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `usuario_id` | corpo | Sim | ID, e-mail ou CPF/CNPJ do aluno |
| `tag_id` | corpo | Sim | ID da tag |

Se o aluno já tiver a tag, nada muda e a resposta é de sucesso.

```bash
curl -X POST https://escola.asalahub.com/api/v1/usuario/adicionar_tag \
  -H "Authorization: ash_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{"usuario_id": "maria@email.com", "tag_id": 7}'
```

```json
{
  "success": true,
  "code": 200,
  "data": { "usuario_id": 1234, "tag_id": 7, "id": 3812 },
  "profiler": { "start": 1789737057.12, "finish": 1789737057.13, "process": 0.01 }
}
```

`id` é o identificador do vínculo entre o aluno e a tag.

## Remover uma tag do aluno

```
POST /usuario/remover_tag
```

| Parâmetro | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `usuario_id` | corpo | Sim | ID, e-mail ou CPF/CNPJ do aluno |
| `tag_id` | corpo | Sim | ID da tag |

```bash
curl -X POST https://escola.asalahub.com/api/v1/usuario/remover_tag \
  -H "Authorization: ash_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{"usuario_id": 1234, "tag_id": 7}'
```

A resposta de sucesso não traz o campo `data`:

```json
{
  "success": true,
  "code": 200,
  "profiler": { "start": 1789737057.12, "finish": 1789737057.13, "process": 0.01 }
}
```

## Editar um aluno

```
POST /usuario/update/{ident}
```

Altera só os campos enviados; os demais ficam como estão.

| Parâmetro | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `ident` | caminho | Sim | ID, e-mail ou CPF/CNPJ do aluno |
| `nome` | corpo | Não | Novo nome (vazio é ignorado) |
| `email` | corpo | Não | Novo e-mail; precisa ser válido e não pode pertencer a outro aluno |
| `doc` | corpo | Não | CPF ou CNPJ (é formatado automaticamente); vazio apaga |
| `celular` | corpo | Não | Celular; vazio apaga |

```bash
curl -X POST https://escola.asalahub.com/api/v1/usuario/update/1234 \
  -H "Authorization: ash_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{"nome": "Maria Souza Silva", "celular": "+5521988887777"}'
```

```json
{
  "success": true,
  "code": 200,
  "data": {
    "usuario": {
      "id": 1234,
      "nome": "Maria Souza Silva",
      "email": "maria@email.com",
      "doc": "242.863.810-64",
      "celular": "+5521988887777",
      "login_auto": "https://escola.asalahub.com/auth/login?crstk=Xy7...",
      "gratis": false,
      "criado_em": "2026-09-18T10:10:57-03:00",
      "ultimo_acesso_em": "2026-10-14T19:02:11-03:00"
    }
  },
  "profiler": { "start": 1789737057.12, "finish": 1789737057.14, "process": 0.02 }
}
```

Erros possíveis (`409`): "Usuário não encontrado.", "E-mail inválido." e "Já existe um usuário com este e-mail.".

## Excluir um aluno

```
DELETE /usuario/{ident}
```

Remove o aluno da plataforma e encerra as sessões abertas dele (ele é desconectado na hora).

| Parâmetro | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `ident` | caminho | Sim | ID, e-mail ou CPF/CNPJ do aluno |

```bash
curl -X DELETE https://escola.asalahub.com/api/v1/usuario/1234 \
  -H "Authorization: ash_sua_chave_aqui"
```

```json
{
  "success": true,
  "code": 200,
  "data": {},
  "profiler": { "start": 1789737057.12, "finish": 1789737057.13, "process": 0.01 }
}
```

:::info
Administradores não podem ser excluídos pela API (a resposta é `409`). Se o aluno excluído voltar a comprar pelo mesmo e-mail, o cadastro dele é reativado.
:::