Integrações

Fitmass (bioimpedância)

Consulte alunos da OctaGym na balança Fitmass e receba cada avaliação de bioimpedância na ficha do aluno.

Fitmass (bioimpedância)

A integração com a balança Fitmass tem duas direções, independentes:

  1. Consulta de alunos — a Fitmass lê o cadastro e a situação do aluno pela API pública da OctaGym.
  2. Recebimento das avaliações — a cada medição, a Fitmass envia o evento MEASURE_CREATED por webhook, e a OctaGym grava a avaliação na ficha do aluno (Alunos → ficha → Avaliações) como bioimpedância.

Nos dois casos quem configura o lado da Fitmass é a equipe dela: a academia só repassa as credenciais geradas no painel da OctaGym.

1. Consulta de alunos

Crie uma chave de API

No painel, em Configurações → Integrações → Fitmass, clique em Criar chave de consulta. O proprietário da Empresa gera a chave com os escopos Alunos — leitura (members:read) e Mensalidades — leitura (memberships:read).

Envie a chave ao seu contato na Fitmass

A Fitmass consulta o aluno por nome ou CPF em GET /api/v1/members?search=, e a situação do plano em GET /api/v1/memberships?member_profile_id=. Veja Alunos e Mensalidades.

O id que a Fitmass guarda

O campo id devolvido em GET /api/v1/members é o identificador do aluno na OctaGym. Se a Fitmass o guardar como sourceId do usuário, cada avaliação chega já vinculada ao aluno certo.

Consulta técnica para a Fitmass

Autentique cada chamada com Authorization: Bearer <chave> na origem https://app.octagym.ai.

  1. Busque GET /api/v1/members?search=<CPF> (CPF com ou sem máscara). A lista fica em data; respeite pagination e não escolha por nome se houver homônimos.
  2. Para cada candidato, consulte GET /api/v1/members/<id>. O objeto data contém client.full_name, client.email, client.phone, client.gender, client.birth_date, status e memberships com plano, vigência e status de cada contrato. Guarde o id do perfil como sourceId.
  3. Com memberships:read, esse detalhe também informa financial_status: overdue significa dívida vencida pela régua da OctaGym, clear significa ausência de dívida vencida, e unknown significa que não foi possível conferir. Sem esse escopo o campo é null. Nunca trate unknown/null como adimplente, nem um contrato active como prova de pagamento. Situação financeira e vigência são perguntas independentes; clear não concede plano ou acesso.
  4. Se optar pela lista de contratos separada, use member_profile_id em GET /api/v1/memberships?member_profile_id=<id> e percorra a paginação. member_id não é filtro reconhecido.

Foto não é exposta pela API pública. Altura é opcional no guia da Fitmass; quando disponível, pode ser obtida da avaliação mais recente em GET /api/v1/members/<id>/measurements (height_cm). Não envie valores inventados para campos ausentes. A Fitmass não precisa de escopo de escrita.

A chave de consulta expira em 90 dias por padrão. A validade pode ser escolhida na criação; acompanhe último uso e revogue em Chaves de API. O segredo do recebimento é independente da chave de consulta.

2. Recebimento das avaliações

Crie o endpoint no painel

Em Configurações → Integrações → Fitmass, clique em Configurar recebimento e depois em Gerar URL e segredo e copie a URL do webhook e o segredo (ele só é mostrado nessa hora).

Peça o cadastro do webhook à Fitmass

Envie ao seu contato na Fitmass:

CampoValor
urla URL do webhook copiada no painel
eventsMEASURE_CREATED
headersX-Webhook-Secret: <segredo copiado no painel>

Confira a primeira avaliação

Faça uma medição na balança. Ela aparece na ficha do aluno em Avaliações, com o método "Bioimpedância · Fitmass" e o equipamento. Os logs de entrega ficam no próprio endpoint, no painel.

Como o aluno é reconhecido

A OctaGym lê data.user.sourceId da entrega, nesta ordem:

Forma do sourceIdCasa com
UUIDo id do aluno (ou da pessoa) na OctaGym
CPF (11 dígitos, com ou sem máscara)o CPF do cadastro
outro textoa matrícula do sistema anterior, em Empresas migradas

Nunca por nome. Identificador que corresponde a mais de um cadastro é recusado: a Fitmass deve enviar o UUID da OctaGym. Entrega cujo aluno não é encontrado responde 422 e fica registrada nos logs do endpoint com o identificador recebido — nada é criado.

O que é gravado

Campo da FitmassCampo da avaliaçãoObservação
measure.datemeasured_atconvertido para o dia no fuso da Empresa
measure.weightweight_kg
user.heightheight_cm
measure.pgcbody_fat_pct
measure.leanMassmuscle_mass_kgmassa magra (peso − gordura)
measure.muscleMassnotesmassa muscular em kg; não é declarada como músculo esquelético
measure.imcbmirecalculado quando há peso e altura
measure.visceralFatLevelvisceral_fat_level
measure.tmbbasal_metabolic_rate_kcal
measure.physicalAgebody_age_years
device.idbia_device"Fitmass BS3-…"
água, massa óssea/mineral, proteína, gorduras em kg, composição segmentar, scorenotestexto legível na avaliação
  • assessment_method é bioimpedance, source é fitmass e external_id é o measure.id — a mesma medição entregue duas vezes não duplica.
  • Valor fora da faixa fisiológica (por exemplo idade corporal 0) é descartado sozinho; o resto da avaliação entra, e o campo descartado fica anotado na observação.
  • Data ausente ou inválida é recusada; a data da entrega nunca substitui a data da avaliação.
  • measureStatus diferente de VALID é confirmado com 200 e não é gravado.

Resposta ao webhook

A OctaGym responde 200 quando gravou (ou já tinha gravado), 422 quando a mesma entrega falharia de novo (aluno não encontrado, evento diferente de MEASURE_CREATED, payload sem medição) e 5xx quando vale reenviar. Cada entrega é deduplicada por X-Fitmass-Delivery.

Nesta página