API

Referência da API

Documentação completa de todos os endpoints da API OctaGym para gestão de academias.

Referência da API

Documentação completa de todos os endpoints disponíveis na API pública v1 do OctaGym.

Base URL

https://dashboard.octagym.ai/api/v1

Endpoints Disponíveis

Alunos (Members)

Cadastrar, listar e gerenciar alunos da academia.

  • GET /api/v1/members — Listar alunos
  • POST /api/v1/members — Cadastrar aluno
  • GET /api/v1/members/:id — Buscar aluno
  • PATCH /api/v1/members/:id — Atualizar aluno
  • GET /api/v1/members/:id/checkins — Histórico de check-ins
  • GET /api/v1/members/:id/measurements — Listar medições
  • POST /api/v1/members/:id/measurements — Registrar medição

Planos

Consultar planos disponíveis na academia.

  • GET /api/v1/plans — Listar planos
  • GET /api/v1/plans/:id — Buscar plano

Mensalidades (Memberships)

Gerenciar mensalidades, congelamentos e cancelamentos.

  • GET /api/v1/memberships — Listar mensalidades
  • POST /api/v1/memberships — Criar mensalidade
  • GET /api/v1/memberships/:id — Buscar mensalidade
  • PATCH /api/v1/memberships/:id — Atualizar mensalidade
  • POST /api/v1/memberships/:id/cancel — Cancelar mensalidade
  • POST /api/v1/memberships/:id/freeze — Congelar mensalidade
  • DELETE /api/v1/memberships/:id/freeze — Descongelar mensalidade

Aulas (Classes)

Consultar grade de aulas e gerenciar reservas.

  • GET /api/v1/classes — Listar aulas
  • GET /api/v1/classes/schedule — Grade de horários
  • POST /api/v1/classes/:id/book — Reservar vaga
  • DELETE /api/v1/classes/:id/book — Cancelar reserva
  • GET /api/v1/class-types — Listar modalidades

Treinos (Workout Programs)

Criar e consultar programas de treino.

  • GET /api/v1/workout-programs — Listar treinos
  • POST /api/v1/workout-programs — Criar treino

Exercícios

Consultar o catálogo de exercícios disponíveis.

  • GET /api/v1/exercises — Listar exercícios

Instrutores (Trainers)

Listar instrutores e consultar perfis.

  • GET /api/v1/trainers — Listar instrutores
  • GET /api/v1/trainers/:id — Buscar instrutor

Métricas

Indicadores da academia: MRR, churn, ocupação.

  • GET /api/v1/gym-metrics — Métricas gerais

Acesso

Monitorar ocupação e controle de acesso.

  • GET /api/v1/access/occupancy — Ocupação atual

Webhooks

Receber notificações de eventos em tempo real.

Eventos: check-in, pagamento, cancelamento, congelamento, novo aluno.

Formato das Respostas

Sucesso

{
  "success": true,
  "data": {
    "id": "uuid-do-recurso",
    "full_name": "João da Silva",
    "status": "active",
    "created_at": "2026-03-22T10:30:00Z"
  }
}

Sucesso com Paginação

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Erro

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Campo 'full_name' é obrigatório"
  }
}

Códigos HTTP

CódigoDescriçãoQuando Ocorre
200OKRequisição bem-sucedida
201CreatedRecurso criado com sucesso
400Bad RequestParâmetros inválidos ou campos obrigatórios ausentes
401UnauthorizedAPI Key ausente ou inválida
403ForbiddenSem permissão para o recurso
404Not FoundRecurso não encontrado
422Unprocessable EntityValidação de negócio falhou (ex: CPF já cadastrado)
429Too Many RequestsLimite de requisições excedido
500Internal Server ErrorErro interno

Códigos de Erro

CódigoDescrição
UNAUTHORIZEDAutenticação falhou
FORBIDDENSem permissão
NOT_FOUNDRecurso não encontrado
VALIDATION_ERRORErro de validação (campo obrigatório, formato inválido, etc.)
DUPLICATE_ENTRYRegistro duplicado (CPF, email)
INTERNAL_ERRORErro interno do servidor
RATE_LIMIT_EXCEEDEDLimite de requisições excedido

Autenticação

Todas as requisições requerem autenticação via header Authorization:

Authorization: Bearer og_live_sua_chave_aqui
Content-Type: application/json

Veja mais em Autenticação.

Paginação

Endpoints que retornam listas suportam paginação via query parameters:

ParâmetroPadrãoMáximoDescrição
page1---Número da página
limit20100Itens por página
page_size20100Alternativa ao limit em alguns endpoints
GET /api/v1/members?page=2&limit=50

Limites de Uso

A API tem um limite de 100 requisições por minuto por API Key.

Exceder o limite resultará em resposta 429 Too Many Requests. Implemente retry com backoff exponencial.

Datas e Horários

  • Datas de filtro: formato ISO 8601 YYYY-MM-DD
  • Timestamps nas respostas: 2026-03-22T10:30:00Z (sempre UTC)

Suporte

Autenticação

Como autenticar suas requisições à API OctaGym usando API Keys.

Alunos (Members)

Gerenciar alunos da academia via API.

On this page

Referência da APIBase URLEndpoints DisponíveisFormato das RespostasSucessoSucesso com PaginaçãoErroCódigos HTTPCódigos de ErroAutenticaçãoPaginaçãoLimites de UsoDatas e HoráriosSuporte