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:
- Consulta de alunos — a Fitmass lê o cadastro e a situação do aluno pela API pública da OctaGym.
- Recebimento das avaliações — a cada medição, a Fitmass envia o evento
MEASURE_CREATEDpor 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.
- Busque
GET /api/v1/members?search=<CPF>(CPF com ou sem máscara). A lista fica emdata; respeitepaginatione não escolha por nome se houver homônimos. - Para cada candidato, consulte
GET /api/v1/members/<id>. O objetodatacontémclient.full_name,client.email,client.phone,client.gender,client.birth_date,statusemembershipscom plano, vigência e status de cada contrato. Guarde oiddo perfil comosourceId. - Com
memberships:read, esse detalhe também informafinancial_status:overduesignifica dívida vencida pela régua da OctaGym,clearsignifica ausência de dívida vencida, eunknownsignifica que não foi possível conferir. Sem esse escopo o campo énull. Nunca trateunknown/nullcomo adimplente, nem um contratoactivecomo prova de pagamento. Situação financeira e vigência são perguntas independentes;clearnão concede plano ou acesso. - Se optar pela lista de contratos separada, use
member_profile_idemGET /api/v1/memberships?member_profile_id=<id>e percorra a paginação.member_idnã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:
| Campo | Valor |
|---|---|
url | a URL do webhook copiada no painel |
events | MEASURE_CREATED |
headers | X-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 sourceId | Casa com |
|---|---|
| UUID | o id do aluno (ou da pessoa) na OctaGym |
| CPF (11 dígitos, com ou sem máscara) | o CPF do cadastro |
| outro texto | a 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 Fitmass | Campo da avaliação | Observação |
|---|---|---|
measure.date | measured_at | convertido para o dia no fuso da Empresa |
measure.weight | weight_kg | |
user.height | height_cm | |
measure.pgc | body_fat_pct | |
measure.leanMass | muscle_mass_kg | massa magra (peso − gordura) |
measure.muscleMass | notes | massa muscular em kg; não é declarada como músculo esquelético |
measure.imc | bmi | recalculado quando há peso e altura |
measure.visceralFatLevel | visceral_fat_level | |
measure.tmb | basal_metabolic_rate_kcal | |
measure.physicalAge | body_age_years | |
device.id | bia_device | "Fitmass BS3-…" |
| água, massa óssea/mineral, proteína, gorduras em kg, composição segmentar, score | notes | texto legível na avaliação |
assessment_methodébioimpedance,sourceéfitmasseexternal_idé omeasure.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.
measureStatusdiferente deVALIDé confirmado com200e 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.