API

Mensalidades (Memberships)

Gerenciar mensalidades e assinaturas dos alunos.

Mensalidades (Memberships)

Endpoints para criar, listar, atualizar, cancelar e congelar mensalidades dos alunos.

Base URL

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

Ciclo de Vida da Mensalidade

┌─────────┐     ┌─────────┐     ┌─────────┐     ┌──────────┐     ┌────────────┐
│  trial   │────>│ active  │────>│ frozen  │────>│ past_due │────>│ cancelled  │
└─────────┘     └─────────┘     └─────────┘     └──────────┘     └────────────┘
     │               │                                │                  ▲
     │               │                                │                  │
     │               └────────────────────────────────┴──────────────────┘
     └───────────────────────────────────────────────────────────────────┘
StatusDescrição
trialPeríodo de teste — plano possui trial_days > 0
activeMensalidade ativa e em dia
frozenMensalidade congelada temporariamente
past_duePagamento atrasado (dentro do período de carência)
cancelledMensalidade cancelada definitivamente

GET /api/v1/memberships — Listar mensalidades

Retorna uma lista paginada de mensalidades.

Query Parameters

ParâmetroTipoPadrãoDescrição
pageinteger1Número da página
page_sizeinteger20Itens por página (máximo 100)
statusstring—Filtrar: active, trial, frozen, cancelled, past_due
plan_idstring—Filtrar por plano (UUID)
member_profile_idstring—Filtrar por aluno (UUID)

Exemplo de Requisição

curl -X GET "https://dashboard.octagym.ai/api/v1/memberships?status=active&page=1&page_size=20" \
  -H "Authorization: Bearer og_live_sua_chave_aqui" \
  -H "Content-Type: application/json"

Exemplo de Resposta

{
  "success": true,
  "data": [
    {
      "id": "mem_uuid_001",
      "status": "active",
      "start_date": "2026-01-15",
      "end_date": "2026-07-15",
      "price_cents": 44990,
      "discount_pct": 0,
      "payment_method": "credit_card",
      "auto_renew": true,
      "created_at": "2026-01-15T10:00:00Z",
      "plan": {
        "id": "plan_uuid_003",
        "name": "Plano Semestral Premium",
        "billing_period": "semiannual"
      },
      "member_profile": {
        "id": "mp_uuid_001",
        "status": "active",
        "client": {
          "id": "cli_uuid_001",
          "full_name": "Ana Costa",
          "email": "ana.costa@email.com"
        }
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 64,
    "pages": 4
  }
}

POST /api/v1/memberships — Criar mensalidade

Cria uma nova mensalidade para um aluno. O end_date e o price_cents são calculados automaticamente a partir do plano, caso não sejam informados.

Body (JSON)

CampoTipoObrigatórioDescrição
member_profile_idstringSimUUID do aluno
plan_idstringSimUUID do plano
start_datestringSimData de início (YYYY-MM-DD)
payment_methodstringNãocredit_card, debit_card, pix, boleto, cash
discount_pctnumberNãoPercentual de desconto (0–100)
promotion_codestringNãoCódigo promocional
auto_renewbooleanNãoRenovação automática (padrão: true)
store_idstringNãoUUID da unidade (filial)

Exemplo de Requisição

curl -X POST "https://dashboard.octagym.ai/api/v1/memberships" \
  -H "Authorization: Bearer og_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "member_profile_id": "mp_uuid_002",
    "plan_id": "plan_uuid_001",
    "start_date": "2026-03-22",
    "payment_method": "pix",
    "auto_renew": true
  }'

Exemplo de Resposta

{
  "success": true,
  "data": {
    "id": "mem_uuid_002",
    "member_profile_id": "mp_uuid_002",
    "plan_id": "plan_uuid_001",
    "status": "trial",
    "start_date": "2026-03-22",
    "end_date": "2026-04-21",
    "price_cents": 9990,
    "discount_pct": 0,
    "payment_method": "pix",
    "auto_renew": true,
    "created_at": "2026-03-22T12:00:00Z"
  }
}

Se o plano possui trial_days > 0, o status inicial será trial. Caso contrário, será active. A criação da mensalidade também atualiza automaticamente o status do aluno.

GET /api/v1/memberships/:id — Buscar mensalidade

Retorna os detalhes completos de uma mensalidade.

Exemplo de Requisição

curl -X GET "https://dashboard.octagym.ai/api/v1/memberships/mem_uuid_001" \
  -H "Authorization: Bearer og_live_sua_chave_aqui" \
  -H "Content-Type: application/json"

Exemplo de Resposta

{
  "success": true,
  "data": {
    "id": "mem_uuid_001",
    "member_profile_id": "mp_uuid_001",
    "plan_id": "plan_uuid_003",
    "status": "active",
    "start_date": "2026-01-15",
    "end_date": "2026-07-15",
    "price_cents": 44990,
    "discount_pct": 0,
    "payment_method": "credit_card",
    "auto_renew": true,
    "freezes_used": 0,
    "freeze_start_date": null,
    "freeze_end_date": null,
    "cancellation_reason": null,
    "cancelled_at": null,
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-15T10:00:00Z",
    "plan": {
      "id": "plan_uuid_003",
      "name": "Plano Semestral Premium",
      "billing_period": "semiannual",
      "price_cents": 44990
    },
    "member_profile": {
      "id": "mp_uuid_001",
      "status": "active",
      "client": {
        "id": "cli_uuid_001",
        "full_name": "Ana Costa"
      }
    }
  }
}

PATCH /api/v1/memberships/:id — Atualizar mensalidade

Atualiza campos específicos de uma mensalidade.

Campos permitidos

CampoTipoDescrição
statusstringactive, trial, frozen, cancelled, past_due
plan_idstringUUID do novo plano
start_datestringNova data de início (YYYY-MM-DD)
end_datestringNova data de fim (YYYY-MM-DD)
price_centsintegerNovo valor em centavos
discount_pctnumberPercentual de desconto (0–100)
payment_methodstringForma de pagamento
auto_renewbooleanRenovação automática

Exemplo de Requisição

curl -X PATCH "https://dashboard.octagym.ai/api/v1/memberships/mem_uuid_001" \
  -H "Authorization: Bearer og_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "discount_pct": 10,
    "price_cents": 40491
  }'

Exemplo de Resposta

{
  "success": true,
  "data": {
    "id": "mem_uuid_001",
    "status": "active",
    "price_cents": 40491,
    "discount_pct": 10,
    "updated_at": "2026-03-22T15:00:00Z"
  }
}

POST /api/v1/memberships/:id/cancel — Cancelar mensalidade

Cancela uma mensalidade. Opcionalmente, o cancelamento pode ser imediato ou ao final do período vigente.

Body (JSON)

CampoTipoPadrãoDescrição
effective_immediatelybooleantrueCancelar imediatamente ou ao fim do período?
reasonstring—Motivo do cancelamento

Exemplo de Requisição

curl -X POST "https://dashboard.octagym.ai/api/v1/memberships/mem_uuid_001/cancel" \
  -H "Authorization: Bearer og_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "effective_immediately": false,
    "reason": "Mudança de cidade"
  }'

Exemplo de Resposta

{
  "success": true,
  "data": {
    "id": "mem_uuid_001",
    "status": "cancelled",
    "cancellation_reason": "Mudança de cidade",
    "cancelled_at": "2026-03-22T16:00:00Z",
    "effective_date": "2026-07-15",
    "member_status_updated": true
  }
}

O cancelamento também encerra qualquer assinatura externa vinculada (gateway de pagamento) e registra o evento no histórico da mensalidade. O status do aluno é atualizado automaticamente.

POST /api/v1/memberships/:id/freeze — Congelar mensalidade

Congela temporariamente uma mensalidade. O período de congelamento não conta como tempo de vigência.

Body (JSON)

CampoTipoObrigatórioDescrição
freeze_end_datestringSimData de fim do congelamento (YYYY-MM-DD)
reasonstringNãoMotivo do congelamento

Exemplo de Requisição

curl -X POST "https://dashboard.octagym.ai/api/v1/memberships/mem_uuid_001/freeze" \
  -H "Authorization: Bearer og_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "freeze_end_date": "2026-04-15",
    "reason": "Viagem a trabalho"
  }'

Exemplo de Resposta

{
  "success": true,
  "data": {
    "id": "mem_uuid_001",
    "status": "frozen",
    "freeze_start_date": "2026-03-22",
    "freeze_end_date": "2026-04-15",
    "freezes_used": 1,
    "member_status_updated": true
  }
}

O congelamento é validado contra o limite do plano (max_freezes_per_year). Se o limite for excedido, a requisição retornará 422 Unprocessable Entity. O status do aluno é atualizado para frozen.

DELETE /api/v1/memberships/:id/freeze — Descongelar mensalidade

Descongela uma mensalidade antes da data prevista, reativando-a imediatamente.

Exemplo de Requisição

curl -X DELETE "https://dashboard.octagym.ai/api/v1/memberships/mem_uuid_001/freeze" \
  -H "Authorization: Bearer og_live_sua_chave_aqui" \
  -H "Content-Type: application/json"

Exemplo de Resposta

{
  "success": true,
  "data": {
    "id": "mem_uuid_001",
    "status": "active",
    "freeze_start_date": null,
    "freeze_end_date": null,
    "member_status_updated": true
  }
}

Ao descongelar, o status da mensalidade volta para active e o status do aluno também é atualizado automaticamente.

Planos

Consultar planos da academia via API.

Aulas (Classes)

Consultar aulas, horários e gerenciar reservas.

On this page

Mensalidades (Memberships)Base URLCiclo de Vida da MensalidadeGET /api/v1/memberships — Listar mensalidadesQuery ParametersExemplo de RequisiçãoExemplo de RespostaPOST /api/v1/memberships — Criar mensalidadeBody (JSON)Exemplo de RequisiçãoExemplo de RespostaGET /api/v1/memberships/:id — Buscar mensalidadeExemplo de RequisiçãoExemplo de RespostaPATCH /api/v1/memberships/:id — Atualizar mensalidadeCampos permitidosExemplo de RequisiçãoExemplo de RespostaPOST /api/v1/memberships/:id/cancel — Cancelar mensalidadeBody (JSON)Exemplo de RequisiçãoExemplo de RespostaPOST /api/v1/memberships/:id/freeze — Congelar mensalidadeBody (JSON)Exemplo de RequisiçãoExemplo de RespostaDELETE /api/v1/memberships/:id/freeze — Descongelar mensalidadeExemplo de RequisiçãoExemplo de Resposta