# API

> Como criar uma chave de API, autenticar as requisições e entender as respostas da API v1 da sua plataforma.

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.

:::aviso Exige conhecimento técnico
Usar a API envolve programação ou uma ferramenta de automação que faça requisições HTTP. Se você não tem alguém técnico na equipe, prefira as integrações prontas das [Entregas](/entregas/entregas-e-integracoes).
:::

## 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.

:::aviso Toda chave tem acesso total
O campo **Finalidade** é só um rótulo para você lembrar para que serve a chave. Ele **não limita** nada: qualquer chave ativa pode ler, editar e excluir alunos, mexer em tags e liberar acessos por entrega. Por isso:

- crie uma chave separada para cada sistema, para poder revogar uma sem afetar as outras;
- nunca coloque a chave em código que roda no navegador, em formulários públicos ou em repositórios abertos;
- prefira chaves com validade quando a integração for temporária.
:::

### 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:

```bash
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:

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

Erro:

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

| Código | Significado |
|---|---|
| 200 | Sucesso |
| 403 | Cabeçalho `Authorization` não enviado |
| 405 | Chave inválida, revogada ou expirada |
| 409 | Erro de regra de negócio (ex.: aluno ou produto não encontrado, campo obrigatório faltando) |
| 404 | Rota inexistente na API v1 |
| 429 | Limite de requisições excedido |
| 500 | Erro inesperado no servidor |

### 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.

:::perigo Planeje as automações com o limite em mente
Em rotinas que percorrem muitos alunos, espere pelo menos meio segundo entre as chamadas e trate o código `429` aguardando alguns segundos antes de tentar de novo.
:::

## Paginação

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

```json
"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.

:::aviso Trate o link como uma senha
O link é pessoal e continua válido depois de usado. Quem tiver o link entra na conta daquele aluno. Não publique nem compartilhe em locais abertos. O login automático nunca funciona para administradores.
:::

## Recursos disponíveis

- [Usuário](/configuracoes/api-usuario): listar, buscar, editar e excluir alunos; acessos, progresso e tags.
- [Tag](/configuracoes/api-tag): listar as tags da plataforma.
- [Produto](/configuracoes/api-produto): listar os cursos e ver um curso.
- [Aula](/configuracoes/api-aula): listar as aulas de um curso, na ordem.
- [Entrega](/configuracoes/api-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](/entregas/custom).

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

:::dica Receber avisos em vez de consultar
Se o seu sistema precisa saber quando um aluno é criado ou ganha acesso, em vez de consultar a API de tempos em tempos use os [Webhooks](/configuracoes/webhooks): a plataforma avisa o seu sistema no momento em que o evento acontece.
:::