Usuário

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

Nesta página

Como identificar o aluno
O objeto usuário
Listar alunos
Buscar um aluno
Listar os acessos de um aluno
Ver o progresso de um aluno em um curso
Listar alunos de uma tag
Adicionar uma tag ao aluno
Remover uma tag do aluno
Editar um aluno
Excluir um aluno

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.

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:

{
  "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)
`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`)

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

{
  "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

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

{
  "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

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

{
  "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)

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

{
  "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)
`cursor`	query	Não	Cursor da próxima página

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

{
  "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.

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}'

{
  "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

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:

{
  "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

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"}'

{
  "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

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

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

Informação

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.

Esta página ajudou?

Usuário

#Como identificar o aluno

#O objeto usuário

#Listar alunos

#Buscar um aluno

#Listar os acessos de um aluno

#Ver o progresso de um aluno em um curso

#Listar alunos de uma tag

#Adicionar uma tag ao aluno

#Remover uma tag do aluno

#Editar um aluno

#Excluir um aluno

Artigos relacionados