> For the complete documentation index, see [llms.txt](https://emusys.gitbook.io/emusys/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://emusys.gitbook.io/emusys/api-emusys/introducao-a-api-emusys.md).
# Introdução à API Emusys
Bem vindo à API Emusys!\
Ela permite integrar sistemas externos com o ambiente de gestão da sua escola de música.\
Com ela, você pode criar e atualizar leads, buscar cursos, consultar disponibilidade de aulas experimentais, e muito mais — tudo de forma **simples e padronizada**, seguindo o estilo **REST**.
**🧱 Versão**
* **Versão atual:** v1.4.1
***
**🌐 Estrutura da API**
Todas as chamadas seguem o mesmo formato base de URL:
```
https://api.emusys.com.br/v1/
```
Exemplo de endpoint completo:
```
https://api.emusys.com.br/v1/leads/
```
> ⚠️ Os endpoints estão disponíveis apenas via **HTTPS** (conexões seguras).
**🔑 Autenticação**
Toda requisição precisa incluir o **Token da Escola** no **Header** da chamada HTTP.\
Esse token identifica qual escola está realizando a operação.
**Exemplo:**
```http
token: 3kyg15QNWzeDlnwBhqoflmSlH3L0xt
```
Sem esse token, o servidor retornará um erro de autenticação.
> O token de cada escola pode ser encontrado no painel administrativo do Emusys.
***
**🧭 Convenções da API**
| Aspecto | Padrão |
| -------------------- | ---------------------------------------------------------- |
| **Protocolo** | HTTPS |
| **Formato de dados** | JSON |
| **Charset** | UTF-8 |
| **Métodos** | `GET`, `POST`, `PATCH` |
| **Autenticação** | Header `token` |
| **Retornos** | Sempre em JSON, com o campo `status` indicando o resultado |
***
**🚦 Rate Limit**
A API da Emusys possui um **rate limit de 60 requisições por minuto por endereço IP**, aplicado de forma **rolling** — ou seja, o limite é calculado dinamicamente considerando os últimos 60 segundos, e não por blocos fixos de tempo.\
\
Caso o limite seja excedido, novas requisições poderão ser temporariamente rejeitadas com o código de status **429 (Too Many Requests)**. Essa limitação existe para garantir a estabilidade e o desempenho da plataforma para todos os usuários.
**📬 Estrutura das Respostas**
Toda resposta da API segue um formato consistente:
**✅ Sucesso**
```json
{
"status": "ok",
"lead_id": 123
}
```
**❌ Erro**
```json
{
"status": "Erro",
"msg": "Lead não encontrado"
}
```
O campo `status` **sempre estará presente**, e indica se a operação foi bem-sucedida.\
Em caso de erro, o campo `msg` traz uma breve descrição do problema.
***
**⚙️ Como ativar**
Para começar a usar a API Emusys, acesse o menu:\
**Administração → Funcionalidades do Sistema → API Emusys**
Lá você verá todos os detalhes da integração e o botão **"Ativar API"**.\
👉 Basta clicar para habilitar — simples assim!
💰 **Custo:** a API tem um valor de **R$ 79/mês**, mas você pode **testar gratuitamente por 15 dias** antes de qualquer cobrança. Durante esse período de teste, tudo funciona normalmente. E se decidir não continuar, é só **desativar a API** quando quiser, sem burocracia.
***
**👩💻 Acesso para desenvolvedores ou empresas parceiras**
Se a sua escola estiver trabalhando com um **desenvolvedor parceiro** ou uma **empresa de integração** (por exemplo, fornecedores de agentes de IA, CRM, automações, etc.), é possível criar um **usuário dedicado** apenas para eles.
Esse usuário terá acesso **somente à área de integrações**, onde poderá:
* Consultar o **histórico de chamadas da API**;
* Criar e editar **webhooks**;
* Gerar e visualizar o **API Key**;
* Acessar a **documentação oficial**;
* Entrar em contato com o **suporte técnico** da Emusys.
Assim, o parceiro técnico tem tudo o que precisa — e nada além disso 😉
Para criar esse usuário, basta seguir o passo a passo de criação de usuários normal do sistema e na parte de permissões selecionar apenas a permissão de Integrador API
**🤝 Suporte**
Caso tenha dúvidas, sugestões ou encontre algum comportamento inesperado, entre em contato com o **suporte técnico da Emusys** através do email
