octagym.ai
Usar o OctaGymAPI e integrações
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 e Check-in

Registrar entrada/saída e monitorar ocupação.

  • POST /api/v1/access/validate — Validar entrada (check-in)
  • POST /api/v1/access/checkout — Registrar saída
  • GET /api/v1/access/occupancy — Ocupação atual
  • GET /api/v1/checkins — Check-ins da empresa por período

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

Escopos

Cada chave carrega um conjunto de escopos, e cada endpoint exige um. Sem o escopo, a resposta é 403 INSUFFICIENT_SCOPE — o corpo traz required_scope para você saber qual falta:

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Esta chave não tem o escopo \u201cMensalidades — escrita\u201d.",
    "details": {
      "required_scope": "memberships:write",
      "granted_scopes": ["members:read", "memberships:read"]
    }
  }
}

A lista completa está em Autenticação. O escopo exigido por cada endpoint aparece na página do recurso.

A API pública é uma lista fechada

Só os endpoints documentados aqui aceitam API Key. Qualquer outro caminho sob /api/v1 responde 403 ENDPOINT_NOT_PUBLIC, mesmo que exista no painel.

Limites de Uso

A API tem um limite de 100 requisições por minuto por chave, aplicado de forma distribuída (o limite é o mesmo independentemente de quantos servidores atendem sua requisição).

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

Dados que a API não devolve

A projeção pública é deliberadamente enxuta. Estes campos nunca saem pela API, por mais que existam no painel:

  • Foto do aluno e do instrutor — a imagem fica no dashboard, onde o acesso é nominal.
  • Documentos além do CPF (RG, passaporte) e dados do responsável legal.
  • Dados de saúde: condições médicas, lesões, atestado, PAR-Q, avaliação de dobras cutâneas.
  • Biometria e credenciais faciais.
  • Identificadores de gateway (Stripe, Pagar.me, Vindi) e meios de pagamento salvos.
  • Dados bancários, chave PIX e limite de crédito.
  • Tokens, hashes e anotações internas da equipe.

Se a sua integração precisa de algum desses dados, fale com o suporte — o caminho é um contrato específico, não a API pública.

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çãoEscoposLimites de UsoDados que a API não devolveDatas e HoráriosSuporte