Voltar para o siteAPI & Integrações

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úblico

Retorna 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úblico

Consulta 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 429

Formato 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