API

A API permite que um sistema externo (ERP, CRM, automação, planilha integrada) consulte e altere dados da sua plataforma sem passar pelo painel: listar alunos, ver acessos e progresso, editar cadastros, aplicar tags, listar cursos e aulas e liberar acessos por uma entrega.

#Endereço da API

Todas as rotas ficam abaixo de:

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

Use o endereço que seus alunos acessam: o subdomínio (ex.: https://escola.asalahub.com/api/v1) ou o seu domínio próprio, se já estiver configurado.

#Criar uma chave de API

1. No painel, acesse Configurações › Chaves de API.
2. Clique em Criar chave.
3. Preencha o Nome (obrigatório, ex.: "ERP da empresa") e, se quiser, a Finalidade (ex.: "Sincroniza alunos com o ERP").
4. Em Validade, escolha quando a chave expira: Nunca, 30 dias, 90 dias, 1 ano ou uma data específica.
5. Clique em Criar chave.

A chave aparece uma única vez, começando com ash_. Copie e guarde num lugar seguro: depois de sair da tela, só os últimos 4 caracteres ficam visíveis. Se perder a chave, revogue e crie outra.

#Acompanhar e revogar chaves

A lista em Configurações › Chaves de API mostra, para cada chave, o nome, a finalidade, o Último uso, a data de criação, a expiração e o status (Ativa, Expirada ou Revogada). Use o filtro Status para ver só as ativas ou só as revogadas.

Para desligar uma chave, clique em Revogar. As integrações que usam essa chave param na mesma hora.

#Autenticação

Envie a chave em todas as requisições, no cabeçalho Authorization:

Authorization: ash_sua_chave_aqui

O prefixo Bearer também é aceito (Authorization: Bearer ash_...).

Exemplo completo:

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

Nas rotas POST, o corpo pode ir em JSON (Content-Type: application/json) ou como formulário (application/x-www-form-urlencoded).

#Formato das respostas

Toda resposta vem no mesmo envelope JSON.

Sucesso:

{
  "success": true,
  "code": 200,
  "data": { },
  "profiler": {
    "start": 1789737057.123,
    "finish": 1789737057.131,
    "process": 0.008
  }
}

Erro:

{
  "success": false,
  "code": 409,
  "msg": "Usuário não encontrado.",
  "profiler": {
    "start": 1789737057.123,
    "finish": 1789737057.125,
    "process": 0.002
  }
}

O campo profiler traz o horário de início e fim do processamento (em segundos, formato Unix) e quanto tempo levou.

#Códigos de resposta

#Datas

As datas dos objetos vêm em ISO-8601 no horário de Brasília, por exemplo 2026-10-15T10:42:07-03:00.

#Limite de requisições

Cada chave pode fazer até 2 requisições por segundo e 120 por minuto. Acima disso a API responde 429 com a mensagem "Limite de requisições excedido". Só as requisições atendidas contam para o limite.

#Paginação

As listas grandes (alunos, alunos por tag, produtos) são paginadas por cursor. A resposta traz um objeto paginator:

"paginator": {
  "perPage": 150,
  "next_page_url": "https://escola.asalahub.com/api/v1/usuario?cursor=eyJpZCI6MTUw...",
  "prev_page_url": null
}

Para buscar a próxima página, chame a URL de next_page_url (com a mesma chave). Quando ela vier null, você chegou ao fim.

#Login automático do aluno

Os objetos de aluno trazem o campo login_auto: um link no formato https://<sua-plataforma>/auth/login?crstk=<token> que abre a área do aluno já logado, sem pedir senha. É útil para colocar em e-mails, mensagens de WhatsApp ou botões de outros sistemas.

#Recursos disponíveis

• Usuário: listar, buscar, editar e excluir alunos; acessos, progresso e tags.
• Tag: listar as tags da plataforma.
• Produto: listar os cursos e ver um curso.
• Aula: listar as aulas de um curso, na ordem.
• Entrega: liberar ou retirar acesso enviando uma venda para uma entrega Customizada.

#API legada (token de postback)

A aba API legada, em Configurações › Chaves de API, mostra o Token de postback da plataforma. Ele não é uma chave da API v1: serve só para autorizar vendas enviadas ao postback da entrega Customizada (campo token do corpo). Veja Entrega Customizada.

Se você gerar um novo token em Gerar novo token, as integrações que usam o anterior param até serem atualizadas.