Evolua ERP API — Documentação da API Pública
Superfície programática REST v1, especificação OpenAPI 3.1.0, catálogo RFC 9727, cabeçalhos padrão IETF RateLimit e servidor MCP Streamable HTTP para desenvolvedores e agentes de IA.
Autenticação e Escopo de Acesso
Os endpoints públicos de leitura da versão /api/v1 (GET /api/v1/planos e GET /api/v1/horarios-disponiveis) e as ferramentas de consulta do servidor MCP não exigem API Key nem autenticação OAuth (security: []).
Operações administrativas e dados privados de estabelecimentos permanecem isolados e protegidos por autenticação de sessão com Row Level Security (RLS) no aplicativo principal.
Endpoints Públicos REST (v1)
GET /api/v1/planos
120 req / 60s · PúblicoRetorna em JSON o catálogo atualizado de planos de assinatura do Evolua ERP (essencial, profissional, evolua), preços em BRL (mensal e equivalente anual), limites e módulos opcionais de automação. Aceita parâmetro opcional ?plano=.
curl -s "https://www.evoluaerp.com.br/api/v1/planos" \
-H "Accept: application/json" \
-H "X-API-Version: 1"{
"apiVersion": "1",
"product": "Evolua ERP",
"currency": "BRL",
"trialDays": 7,
"requiresCreditCard": false,
"plans": [
{
"id": "essencial",
"name": "Essencial",
"monthlyPrice": 79.99,
"yearlyMonthlyEquivalent": 66.65
}
]
}GET /api/v1/horarios-disponiveis
50 req / 60s · PúblicoConsulta horários livres (HH:mm) e vagas simultâneas disponíveis para agendamento online em um estabelecimento cadastrado. Exige os parâmetros estabelecimento_id (UUID), data (YYYY-MM-DD) e duracao_total (minutos), com filtro opcional profissional_id (UUID).
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"{
"horarios": ["09:00", "09:30", "10:00"],
"vagasPorHorario": {
"09:00": 2,
"09:30": 1,
"10:00": 2
}
}Política de Versionamento e Depreciação (RFC 9745)
Estratégia por URL + Header: Todas as rotas REST públicas estáveis utilizam o prefixo de versão principal /api/v1/ e também aceitam o cabeçalho opcional X-API-Version: 1 (ou 2026-11-01). Alterações incompatíveis (breaking changes) exigem um novo prefixo principal (/api/v2/).
Sinalização de Depreciação: Rotas antigas ou aliases de compatibilidade anunciam depreciação por meio dos cabeçalhos padronizados RFC 9745 (Deprecation e Sunset quando programado), acompanhados de Link: rel="successor-version" e Link: rel="deprecation" apontando para esta seção.
Janela mínima de aviso: Todo recurso depreciado mantém suporte ativo por no mínimo 90 dias antes de eventual desativação. O alias legado /api/horarios-disponiveis permanece operacional por compatibilidade e emite cabeçalhos RFC 9745 indicando /api/v1/horarios-disponiveis como sucessor.
Limites de Requisição e Cabeçalhos IETF RateLimit
Todas as respostas da API (200, 400, 405, 429 e 500) incluem cabeçalhos padrão para que agentes controlem a cadência em tempo real:
RateLimit-Policy: "public-planos";q=120;w=60
RateLimit: "public-planos";r=119;t=60
RateLimit-Limit: 120
RateLimit-Remaining: 119
RateLimit-Reset: 60
Retry-After: 42 # incluído em respostas HTTP 429Formato Estruturado de Erros (RFC 9457)
Respostas de erro utilizam application/problem+json com código estável, mensagem descritiva (detail e error) e status HTTP explícito (400, 405, 429, 500):
{
"type": "https://www.evoluaerp.com.br/docs#error-format",
"title": "Missing required query parameters",
"status": 400,
"code": "missing_required_parameters",
"detail": "Parâmetros obrigatórios: estabelecimento_id, data, duracao_total",
"error": "Parâmetros obrigatórios: estabelecimento_id, data, duracao_total"
}Servidor MCP (Model Context Protocol)
Clientes compatíveis com MCP Streamable HTTP podem se conectar sem autenticação em POST https://www.evoluaerp.com.br/mcp para listar e invocar ferramentas somente leitura:
evolua_list_plans— Lista os planos vigentes, limites e módulos adicionais em BRL.evolua_check_available_slots— Consulta horários disponíveis reais de um estabelecimento.evolua_get_api_docs— Retorna o resumo atualizado da documentação e políticas da API.
Descoberta MCP: /mcp/server-card · /server.json · /.well-known/ai-catalog.json · /openapi.json · /.well-known/api-catalog · /.well-known/agent-skills/index.json