Fairpace

Desenvolvedores

Guia da API do Fairpace

Para ligar o seu app aos treinos verificados dos atletas, com a autorização de cada um.

Pedir acesso à API

Começo rápido

A API do Fairpace deixa o seu app ler, com a autorização de cada atleta, o perfil e os treinos verificados. É só leitura: o app nunca grava, edita ou apaga treinos.

  1. Entre na Minha conta com a sua conta do Fairpace e peça acesso na aba API.
  2. Com o pedido aprovado, gere o segredo em Meus apps e copie o client_id e o segredo. O segredo aparece uma vez só.
  3. Autorize o app com a sua própria conta e faça a primeira leitura. O app começa em modo de teste, com até 10 atletas.

Endereço-base de todas as chamadas:

https://fairpace.run/api/v1

Autorizar o atleta

O app manda o atleta para a página de autorização do Fairpace. O atleta entra, vê o que o app vai poder ler e autoriza. O app nunca vê a senha.

GET https://fairpace.run/api/v1/oauth/authorize
  ?client_id=SEU_CLIENT_ID
  &redirect_uri=https://seuapp.com/fairpace/volta
  &response_type=code
  &scope=read,activity:read
  &state=VALOR_ALEATORIO
  &code_challenge=DESAFIO
  &code_challenge_method=S256

O PKCE é obrigatório: gere um code_verifier aleatório, de 43 a 128 caracteres, e mande code_challenge = base64url(SHA-256(verifier)), sem o "=" do fim. O redirect_uri tem de ser igual, letra por letra, ao cadastrado.

Depois de autorizar, o navegador volta para redirect_uri?code=fpc_...&scope=...&state=.... Confira o state. O código vale 10 minutos e uma vez só. Se o atleta cancelar, volta com error=access_denied.

PermissãoO que o app lê
readNome, @usuário e cidade do atleta
activity:readOs treinos verificados que não são "só eu"
health:readBatimentos, calorias e esforço dentro dos treinos

Tokens

Troque o código pelos tokens, sempre no corpo do pedido (formulário ou JSON). Segredo, código ou renovação no endereço são recusados.

POST https://fairpace.run/api/v1/oauth/token

grant_type=authorization_code
&client_id=SEU_CLIENT_ID
&client_secret=SEU_SEGREDO
&code=fpc_...
&redirect_uri=https://seuapp.com/fairpace/volta
&code_verifier=VERIFIER
{
  "token_type": "Bearer",
  "access_token": "fpa_...",
  "expires_in": 3600,
  "expires_at": 1790960000,
  "refresh_token": "fpr_...",
  "refresh_expires_in": 7776000,
  "scope": "read activity:read",
  "athlete": {"id": 7786525441263953, "username": "ana.corre", "city": "Belém"}
}

O acesso vale 1 hora e a renovação, 90 dias. Renove antes de expires_at com grant_type=refresh_token. A renovação troca a cada uso: guarde sempre a nova. A anterior ainda vale por 2 minutos; depois disso, apresentar a velha derruba a conexão.

Toda chamada leva o cabeçalho Authorization: Bearer fpa_....

O que dá para ler

RotaPermissãoO quê
GET /athletereadO atleta, sem e-mail
GET /athlete/activitiesactivity:readOs treinos, do mais novo ao mais antigo; after, before (segundos UTC), page e per_page (até 200)
GET /activities/{id}activity:readO detalhe de um treino, com parciais e melhores marcas
POST /oauth/deauthorizequalquerO app desliga a conexão do atleta

Campos principais do treino: id, name, sport, start_date, distance, moving_time, elapsed_time, total_elevation_gain, average_speed, map.summary_polyline, verified, city. Distâncias em metros e tempos em segundos. sport é run, ride, walk, trail ou gym (academia, sem percurso). city traz o código do IBGE do município de partida.

{
  "id": 6922034537060998,
  "name": "Corrida da manhã",
  "sport": "run",
  "start_date": "2026-10-09T09:12:00Z",
  "distance": 10020.4,
  "moving_time": 3121,
  "verified": true,
  "city": {"ibge": "1501402", "name": "Belém", "uf": "PA"}
}

Nunca saem: o e-mail, a senha, o perfil de saúde, o treino "só eu" e o treino sem selo. Quando o atleta esconde o começo e o fim, o percurso vem sem um trecho de cada ponta.

Avisos de treino novo

Ligue os avisos em Meus apps, com um endereço https do seu app. O segredo da assinatura aparece uma vez só. A cada treino novo, alterado ou apagado que o app pode ler, chega um POST:

POST https://seuapp.com/fairpace/avisos
X-Fairpace-Event: 3f2b6c1e-...
X-Fairpace-Signature: t=1790960000,v1=<hex>

{"object_type": "activity", "object_id": 6922034537060998,
 "aspect_type": "create", "owner_id": 7786525441263953,
 "event_time": 1790960000, "event_id": "3f2b6c1e-...", "updates": {}}

Confira a assinatura antes de usar o aviso:

const [t, v1] = cabecalho.split(',').map(p => p.split('=')[1]);
const esperado = crypto.createHmac('sha256', segredo)
  .update(`${t}.${corpoBruto}`).digest('hex');
const valido = crypto.timingSafeEqual(Buffer.from(v1, 'hex'), Buffer.from(esperado, 'hex'))
  && Math.abs(Date.now() / 1000 - Number(t)) <= 300;
  • Responda 2xx em até 5 segundos e processe depois. Sem resposta, o Fairpace tenta de novo em 1 min, 5 min, 30 min, 2 h, 12 h, 24 h.
  • O mesmo event_id pode chegar mais de uma vez: ignore o repetido.
  • O aviso não leva dados do treino: leia pela API.
  • Quando o atleta desliga o app ou exclui a conta, chega um aviso com object_type: "athlete". Apague tudo o que guardou daquele atleta.

Erros e limites

{"error": {"code": "token_expirado", "message": "..."}}
CódigoStatusO que fazer
token_expirado401Renovar o acesso
sessao_invalida401O atleta desligou: autorizar de novo
escopo_insuficiente403Pedir a permissão ao atleta
teto_de_atletas403O app chegou ao número de atletas liberado
app_desligado403Falar com a equipe
limite_de_chamadas429Esperar o tempo de retry_after_s
LimiteEm testeEm produção
Por atleta1.200 por hora1.200 por hora
App inteiro, a cada 15 min1001.000
App inteiro, por dia1.00020.000, ampliável a pedido

Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset: quanto o app pode, quanto falta e em quantos segundos o contador zera. Use os avisos de treino em vez de consultar a lista a toda hora.

Modo de teste e produção

  • Em teste, o app funciona igual, com até 10 atletas (você incluído) e limites menores.
  • Para abrir a todos, peça a produção em Meus apps. A equipe confere o app funcionando, a página de privacidade do seu app e como os dados aparecem.
  • App em teste sem nenhuma chamada por 60 dias é desligado. Para voltar, faça um pedido novo.

Regras de uso

  • Não vender nem repassar os dados dos atletas.
  • Guardar só o que o app usa e apagar tudo quando o atleta desligar ou excluir a conta.
  • Não usar a localização para outro fim que não o mostrado ao atleta.
  • Não se passar pelo Fairpace e indicar que os treinos vêm do Fairpace.
  • Guardar o segredo só no servidor do app, nunca no app do celular ou no navegador.

O texto completo está nos termos de uso da API, aceitos no pedido. O app que descumprir é desligado pela equipe.

Mudanças na API

Campo novo pode entrar a qualquer momento: o seu app deve ignorar o que não conhece. Mudança que quebra app só entra numa versão nova do endereço (/api/v2), com aviso de 90 dias antes de a anterior sair.

DataVersãoO que mudou
10/2026v1Primeira versão pública

Dúvidas sobre a API: contato@fairpace.run