# Evolua ERP API — Documentação da API Pública & Integrações

> Documentação oficial da API REST v1, políticas de versionamento, cabeçalhos padrão de rate limit (IETF RateLimit), formato RFC 9457 de erros e servidor MCP do **Evolua ERP** (`https://www.evoluaerp.com.br`).

## Visão geral e descoberta para agentes

- **Especificação OpenAPI 3.1.0:** https://www.evoluaerp.com.br/openapi.json
- **Catálogo de APIs (RFC 9727):** https://www.evoluaerp.com.br/.well-known/api-catalog
- **Agent Skills Index (v0.2.0):** https://www.evoluaerp.com.br/.well-known/agent-skills/index.json
- **Servidor MCP (Streamable HTTP):** https://www.evoluaerp.com.br/mcp (Server Card em https://www.evoluaerp.com.br/mcp/server-card e https://www.evoluaerp.com.br/.well-known/ai-catalog.json)
- **Negociação Markdown:** envie `Accept: text/markdown` nesta página ou acesse `https://www.evoluaerp.com.br/docs.md`

## Autenticação

As APIs públicas de leitura (`GET /api/v1/planos` e `GET /api/v1/horarios-disponiveis`) e as ferramentas somente leitura do servidor MCP são **públicas e não exigem API Key nem token OAuth** (`security: []`). Operações de escrita ou dados privados de contas administrativas exigem fluxo específico de agendamento ou autenticação no aplicativo.

## Endpoints Públicos (v1)

### 1. Catálogo Público de Planos — `GET /api/v1/planos`

Retorna em JSON os planos vigentes do Evolua ERP (`essencial`, `profissional`, `evolua`), valores em BRL (mensal e equivalente anual), limites operacionais, lista de recursos e módulos adicionais opcionais. Não exige parâmetros obrigatórios.

- **Query parameter opcional:** `plano=essencial|profissional|evolua`
- **Rate limit:** 120 requisições por minuto por IP (`policy="public-planos"`)

```bash
curl -s "https://www.evoluaerp.com.br/api/v1/planos" \
  -H "Accept: application/json" \
  -H "X-API-Version: 1"
```

### 2. Consulta de Horários Disponíveis — `GET /api/v1/horarios-disponiveis`

Calcula em tempo real os horários livres (`HH:mm`) e vagas simultâneas restantes para um estabelecimento cadastrado na plataforma (`/empresa/<slug>`).

- **Query parameters obrigatórios:**
  - `estabelecimento_id` (UUID): identificador do estabelecimento
  - `data` (`YYYY-MM-DD`): data desejada
  - `duracao_total` (inteiro >= 1): duração total em minutos
- **Query parameter opcional:** `profissional_id` (UUID)
- **Rate limit:** 50 requisições por minuto por IP (`policy="public-horarios"`)

```bash
curl -s "https://www.evoluaerp.com.br/api/v1/horarios-disponiveis?estabelecimento_id=00000000-0000-0000-0000-000000000000&data=2026-11-15&duracao_total=60" \
  -H "X-API-Version: 1"
```

Resposta `200 OK`:

```json
{
  "horarios": ["09:00", "09:30", "10:00"],
  "vagasPorHorario": {
    "09:00": 2,
    "09:30": 1,
    "10:00": 2
  }
}
```

## Política de Versionamento e Depreciação (#versioning-and-deprecation)

- **Versionamento por URL e header:** endpoints REST estáveis usam o prefixo de versão principal `/api/v1/`. Também aceitam negociação opcional via header `X-API-Version: 1` (ou `2026-11-01`).
- **Mudanças incompatíveis (breaking changes):** nunca alteram contratos `/api/v1` existentes; novas versões incompatíveis são publicadas em um novo prefixo (`/api/v2/`). Campos aditivos opcionais podem ser incluídos mantendo compatibilidade reversa.
- **Sinalização de depreciação (RFC 9745):** rotas ou aliases legados em transição emitem cabeçalhos `Deprecation` (timestamp RFC 9745), `Sunset` (quando houver data de desligamento), `Link: <sucessor>; rel="successor-version"` e `Link: <https://www.evoluaerp.com.br/docs#versioning-and-deprecation>; rel="deprecation"; type="text/html"`.
- **Prazo mínimo de transição:** garantimos no mínimo **90 dias** de aviso prévio antes da remoção definitiva de qualquer endpoint depreciado. O alias legado `/api/horarios-disponiveis` já emite cabeçalhos RFC 9745 apontando para `/api/v1/horarios-disponiveis`.

## Limites de Taxa (Rate Limit Headers) (#rate-limits)

Todas as respostas da API REST pública (incluindo `200`, `400`, `405`, `429` e `500`) incluem cabeçalhos padronizados IETF para controle automático de throttling por agentes:

- `RateLimit-Policy`: política ativa (`"public-planos";q=120;w=60` ou `"public-horarios";q=50;w=60`)
- `RateLimit`: cota restante e janela em segundos (`"public-planos";r=119;t=60`)
- `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`: formas escalares compatíveis (em delta-segundos)
- `Retry-After`: segundos exatos para aguardar em respostas HTTP `429 Too Many Requests`

## Formato Padrão de Erros (RFC 9457) (#error-format)

Erros da API utilizam `Content-Type: application/problem+json; charset=utf-8` com `type`, `title`, `status`, `code`, `detail` e `error`.

## Servidor MCP (Model Context Protocol) (#mcp)

Conecte clientes MCP Streamable HTTP (versão `2025-11-25`) diretamente em `https://www.evoluaerp.com.br/mcp` via `POST` JSON-RPC 2.0 (sem autenticação). Ferramentas expostas: `evolua_list_plans`, `evolua_check_available_slots` e `evolua_get_api_docs`. Guia completo em [https://www.evoluaerp.com.br/docs/mcp](https://www.evoluaerp.com.br/docs/mcp) e manifestos em `https://www.evoluaerp.com.br/server.json`, `https://www.evoluaerp.com.br/mcp/server-card` e `https://www.evoluaerp.com.br/.well-known/ai-catalog.json`.

## Linha de Comando Oficial (CLI no npm) (#cli)

Instale ou execute diretamente com `npx evolua-erp planos`, `npx evolua-erp horarios` e `npx evolua-erp mcp --json`. Veja o guia completo em [https://www.evoluaerp.com.br/docs/cli](https://www.evoluaerp.com.br/docs/cli) e o pacote em [https://www.npmjs.com/package/evolua-erp](https://www.npmjs.com/package/evolua-erp).
