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 à APIComeç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.
- Entre na Minha conta com a sua conta do Fairpace e peça acesso na aba API.
- Com o pedido aprovado, gere o segredo em Meus apps e copie o
client_ide o segredo. O segredo aparece uma vez só. - 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/v1Autorizar 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=S256O 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ão | O que o app lê |
|---|---|
read | Nome, @usuário e cidade do atleta |
activity:read | Os treinos verificados que não são "só eu" |
health:read | Batimentos, 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
| Rota | Permissão | O quê |
|---|---|---|
GET /athlete | read | O atleta, sem e-mail |
GET /athlete/activities | activity:read | Os treinos, do mais novo ao mais antigo; after, before (segundos UTC), page e per_page (até 200) |
GET /activities/{id} | activity:read | O detalhe de um treino, com parciais e melhores marcas |
POST /oauth/deauthorize | qualquer | O 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_idpode 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ódigo | Status | O que fazer |
|---|---|---|
token_expirado | 401 | Renovar o acesso |
sessao_invalida | 401 | O atleta desligou: autorizar de novo |
escopo_insuficiente | 403 | Pedir a permissão ao atleta |
teto_de_atletas | 403 | O app chegou ao número de atletas liberado |
app_desligado | 403 | Falar com a equipe |
limite_de_chamadas | 429 | Esperar o tempo de retry_after_s |
| Limite | Em teste | Em produção |
|---|---|---|
| Por atleta | 1.200 por hora | 1.200 por hora |
| App inteiro, a cada 15 min | 100 | 1.000 |
| App inteiro, por dia | 1.000 | 20.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.
| Data | Versão | O que mudou |
|---|---|---|
| 10/2026 | v1 | Primeira versão pública |
Dúvidas sobre a API: contato@fairpace.run