> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useweve.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API REST

> Alunos e acesso a partir do seu sistema: criar, alterar e remover alunos, e dar, estender e revogar acesso.

A API REST é para o sistema que já tem a lista de quem pode estudar — um checkout próprio, um
CRM, um ERP — e quer que o club acompanhe: criar o aluno, abrir o acesso, tirá-lo no reembolso.

```
https://api.useweve.com/v1
```

## Autenticação

Crie uma chave em **Ajustes › Chaves de API** e mande-a no cabeçalho de toda chamada:

```bash theme={null}
curl https://api.useweve.com/v1/students \
  -H "Authorization: Bearer weve_sk_…"
```

A chave vale para **um club** — o club em que foi criada, e por isso não há id de club no
caminho. Ela age em nome de quem a criou, e a API é de quem **administra** o club: a chave de
quem só faz parte do time responde `403 forbidden`.

| escopo | o que libera |
| - | - |
| `read` | As leituras (`GET`) |
| `write` | Criar, alterar, remover, dar e revogar acesso |

É a mesma chave do [MCP](/essentials/mcp), e ela para de valer nos mesmos casos: revogada, vencida,
com a pessoa fora do time, ou com o club tendo desligado o acesso por chave em
**Ajustes › Integrações**.

## Os objetos

O aluno e a matrícula que a API devolve são **os mesmos** que os
[webhooks de saída](/essentials/webhooks) mandam: guarde um formato só. A matrícula é o direito de
um aluno a uma **entrega** — o que se vende ou se concede, e que abre cursos, repositórios ou
mentorias. [Listar entregas](/api-reference/deliveries/list) dá o `delivery_id` de cada uma.

## Um fluxo comum

<Steps>
  <Step title="Crie o aluno já com acesso">
    ```bash theme={null}
    curl https://api.useweve.com/v1/students \
      -H "Authorization: Bearer $WEVE_KEY" \
      -H "Content-Type: application/json" \
      -d '{"name":"Ana Lima","email":"ana@exemplo.com","delivery_ids":["5a4f2c56-…"]}'
    ```

    A pessoa recebe por e-mail o link para definir a senha. Se o e-mail já é de um aluno do
    club, nada é duplicado: as entregas são abertas na conta que existe, e a resposta é `200`
    em vez de `201`.
  </Step>

  <Step title="Dê acesso a outra entrega depois">
    ```bash theme={null}
    curl https://api.useweve.com/v1/enrollments \
      -H "Authorization: Bearer $WEVE_KEY" \
      -H "Content-Type: application/json" \
      -d '{"student_id":"…","delivery_id":"…","expires_at":"2027-10-01T00:00:00Z"}'
    ```
  </Step>

  <Step title="Revogue no reembolso">
    ```bash theme={null}
    curl -X POST https://api.useweve.com/v1/enrollments/{id}/revoke \
      -H "Authorization: Bearer $WEVE_KEY" \
      -H "Content-Type: application/json" \
      -d '{"reason":"reembolso"}'
    ```

    A matrícula continua existindo, com `status: revoked`: é o histórico do aluno.
  </Step>
</Steps>

<Note>
  Se as vendas vêm de uma plataforma (Hotmart, Kiwify, Eduzz, Guru) ou de um checkout que manda
  webhook, o [webhook de venda](/essentials/generic-webhook) faz tudo isso sozinho — compra dá
  acesso, reembolso tira. A API é para quando quem decide é o seu sistema.
</Note>

## Ausente e nulo

Em `expires_at` e `cohort_id`, não mandar o campo e mandá-lo `null` são coisas diferentes:

| campo | ausente | `null` |
| - | - | - |
| `expires_at` ao dar acesso | O prazo padrão da entrega (ou da turma) | Vitalício |
| `cohort_id` ao dar acesso | A turma que estiver matriculando agora, se houver | Nenhuma turma |

Para mudar o prazo de uma matrícula, `expires_at` é obrigatório — `null` para vitalício.

## Paginação

As listas aceitam `limit` (1 a 100, padrão 25) e `page` (a partir de 1), e trazem `total` — quantos
itens o filtro alcança em todas as páginas:

```json theme={null}
{ "data": [ … ], "total": 312 }
```

## Remoção

[Remover aluno](/api-reference/students/delete) é a remoção da LGPD: nome, e-mail e senha são
apagados, todo acesso ativo é revogado e sai o evento `student.removed`. Não há volta. Depois
dela, o aluno e as matrículas dele respondem `404`.

## Erros e limites

Toda falha segue o [envelope de erros](/essentials/errors). A chave tem teto de **300 chamadas por
minuto**, e as escritas contam também no teto do club — ver [Limites de uso](/essentials/rate-limits).