Como integrar o Terra (agregador de dados de saúde) (2026)

O motivo de usar um agregador, e o que você deve guardar: uma integração, muitos fornecedores, entregues em um só destino. Você nunca escreve parsing específico de fornecedor. Para ver onde o Terra fica entre os agregadores, veja APIs agregadoras de dados de saúde e a comparação direta Terra vs Vital; a visão geral da API do Terra reúne como obter acesso e todas as páginas deste site que tratam do Terra. Este guia também é um passo da trilha de leitura para suportar todos os wearables por um único agregador, que põe as páginas desse trabalho na ordem em que você vai precisar delas.

Todo endpoint, campo e limite abaixo vem da documentação, da especificação OpenAPI e da página de preços do Terra, como as lemos em 17 de outubro de 2026.

O que mudou nesta revisão#

• O endpoint do widget. O Terra relançou o widget de conexão. As novas sessões são criadas em POST https://access.tryterra.co/api/widget/session. O antigo /v2/auth/generateWidgetSession, que uma versão anterior deste guia usava, "keeps working today, with deprecation planned for 3 November 2026" [continua funcionando hoje, com descontinuação prevista para 3 de novembro de 2026], e "Accounts created after 3 September 2026 cannot use it at all." [Contas criadas depois de 3 de setembro de 2026 não podem usá-lo de forma alguma.]
• Quais fornecedores exigem as suas próprias credenciais. Uma versão anterior listava Garmin, Whoop, Strava e Oura. A documentação atual do Terra cita WHOOP, Dexcom, Huawei, Strava e Virtuagym; a tabela de integrações dele também marca Garmin e Samsung como Required [obrigatório] e lista o Oura como Managed [gerenciado]. O passo 2 traz os detalhes.
• Os preços agora estão publicados por completo em tryterra.co/pricing; os números estão nas pegadinhas, abaixo.

O que você vai precisar#

• Uma conta no Terra com um plano; o painel dá a você um dev-id e uma x-api-key. O Terra mantém credenciais separadas para testes, staging e produção, e os ambientes de testes e de staging são limitados a 50 usuários cada.
• Um destino configurado no painel do Terra: uma URL de webhook, ou um banco de dados, bucket de armazenamento em nuvem ou fila em que o Terra escreve.
• Um backend para chamar a API do Terra. A documentação do Terra é direta: "Never share your x-api-key publicly or embed it directly in client-side code (e.g., mobile apps, frontend JavaScript)." [Nunca compartilhe a sua x-api-key publicamente nem a embuta diretamente em código do lado do cliente (por exemplo, apps móveis, JavaScript de frontend).]
• Para WHOOP, Dexcom, Strava e os outros fornecedores do passo 2, o seu próprio app de desenvolvedor naquele fornecedor.
• A superfície da API: a especificação OpenAPI do Terra descreve "The Terra API (v2 surface, served at access.tryterra.co/api/v2)" [a API do Terra (superfície v2, servida em access.tryterra.co/api/v2)].

Passo 1: obtenha as credenciais e configure um destino#

Crie a sua conta e copie o dev-id e a x-api-key da página API Keys do painel. Toda chamada à API envia os dois como headers:

dev-id: YOUR_DEV_ID
x-api-key: YOUR_API_KEY

Depois escolha para onde os dados vão. Um webhook é o destino mais simples; o Terra também pode entregar em "SQL databases (Postgres and MySQL), Supabase, cloud storage (S3, GCS and Azure Blob), queueing services (SQS and Kafka), MongoDB and Firestore" [bancos SQL (Postgres e MySQL), Supabase, armazenamento em nuvem (S3, GCS e Azure Blob), serviços de fila (SQS e Kafka), MongoDB e Firestore]. Como tudo converge para um só destino, você constrói e testa um único receptor, e não um por wearable.

Passo 2: registre as suas próprias credenciais nos fornecedores que exigem#

A documentação do Terra diz que ele "manages API Keys of data sources, meaning you can connect users without having to apply for each API Key" [gerencia as chaves de API das fontes de dados, o que significa que você pode conectar usuários sem precisar pedir cada chave de API], mas "Some providers require special processes before being able to start using them" [alguns fornecedores exigem processos especiais antes de poderem ser usados]: WHOOP, Dexcom, Huawei, Strava e Virtuagym.

• WHOOP e Dexcom. Cada um "requires every company to connect users through its own app" [exige que toda empresa conecte os usuários pelo seu próprio app] no portal de desenvolvedor dele, com a URL de redirecionamento (e, no WHOOP, a URL do webhook) "on a domain that belongs to you" [em um domínio que pertence a você]. No painel, abra Connections, escolha o fornecedor e siga a configuração; ela configura o domínio personalizado e mostra as URLs para colar no seu app, e então você pede acesso de produção ao fornecedor.
• Strava. Crie um aplicativo em strava.com/settings/api e depois informe o client ID e o secret dele na configuração do Strava no painel.
• Garmin e Samsung. A tabela de integrações suportadas do Terra marca as duas como Required para credenciais de integração, enquanto o FAQ da página inicial diz que "Garmin data flows through Terra today" [os dados da Garmin passam pelo Terra hoje] por meio da integração de parceiro que o Terra mantém há tempos. Confira a página Connections da sua conta antes de prometer suporte à Garmin. Para a rota direta do Samsung Health, o Terra diz para se candidatar pelo portal de parcerias da Samsung e desenvolver na rota do Health Connect enquanto espera.

Planeje como se um fornecedor que exige configuração especial não pudesse ser conectado até que essa configuração termine. Isso é tempo de painel e de papelada, não de código, então comece por aí.

Passo 3: crie uma sessão de widget a partir do seu backend#

Para conectar um usuário, o seu backend cria uma sessão de widget hospedada e manda o usuário para a URL que ela devolve. Passe o seu próprio reference_id (o seu ID interno de usuário) para poder associar o usuário do Terra ao seu.

curl --request POST "https://access.tryterra.co/api/widget/session" \
  --header "dev-id: YOUR_DEV_ID" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "reference_id": "user-1234",
    "providers": "GARMIN,FITBIT,OURA,WHOOP,STRAVA",
    "auth_success_redirect_url": "https://yourapp.com/success",
    "auth_failure_redirect_url": "https://yourapp.com/failure"
  }'

Todo campo do corpo é opcional. providers é uma lista separada por vírgulas "of providers to show, in the order given" [dos fornecedores a mostrar, na ordem dada]; se você o omitir, o widget mostra as fontes ativadas no seu painel. Uma chamada bem-sucedida devolve HTTP 201 com a url do widget, válida por expires_in segundos, que o Terra documenta como 24 horas. Crie uma sessão nova a cada tentativa de conexão em vez de guardar URLs. Não existe mais o campo language: "The widget follows the end user's browser language automatically." [O widget segue automaticamente o idioma do navegador do usuário final.]

Migrando do endpoint legado? Ele ficava em POST https://api.tryterra.co/v2/auth/generateWidgetSession, devolvia sessões válidas por 900 segundos e aceitava language, "providers": "multi-auth" e "providers": "ALL"; o novo endpoint usa multi_auth: true e um providers omitido no lugar disso. De resto, o formato da resposta (session_id, url, status, expires_in) não mudou.

Passo 4: leve o usuário ao widget e trate o evento auth#

Abra a url em uma nova aba ou em um navegador dentro do app. A documentação do Terra diz: "Do not use WebView or iFrame for the authentication flow" [não use WebView nem iFrame no fluxo de autenticação], porque o usuário não consegue ver em qual domínio está digitando a senha, e os fornecedores podem bloquear isso. O usuário escolhe um fornecedor e faz login com o login do próprio fornecedor; depois ele cai na sua URL de sucesso "with their Terra user_id and your reference_id as query parameters" [com o user_id dele no Terra e o seu reference_id como parâmetros de query].

O sinal que vale é o evento auth que o Terra envia ao seu destino, com o user_id do Terra, o seu reference_id e o provider. Guarde esse user_id associado à sua conta: ele é a chave de toda requisição posterior e a chave de roteamento de todo payload. Se um usuário reconecta o mesmo fornecedor sob o mesmo reference_id, o Terra "will delete the previous user record for that account and yield a new user_id" [apaga o registro de usuário anterior daquela conta e gera um novo user_id], e "Terra sends a user_reauth event containing both the old and new user_id" [o Terra envia um evento user_reauth com o user_id antigo e o novo], então trate esse evento ou os dados novos vão parar de bater com os seus registros.

Passo 5: receba os dados normalizados no seu destino#

A partir daí, o Terra envia eventos de dados normalizados conforme o fornecedor sincroniza. A referência de eventos dele lista os tipos de evento de dados como activity, athlete, body, daily, hormone, menstruation, nutrition e sleep, ao lado de eventos de ciclo de vida como auth, deauth, user_reauth e access_revoked. Cada payload indica o usuário e o fornecedor; o array data tem o mesmo formato, venha do wearable que vier. Um exemplo resumido:

{
  "type": "activity",
  "user": {
    "user_id": "4735eac4-31a2-47ef-8b11-51e98d84c680",
    "reference_id": "user-1234",
    "provider": "GARMIN"
  },
  "data": [ { "metadata": {} } ]
}

Roteie por type e user.user_id. Como o esquema é idêntico entre fornecedores, você escreve um handler para activity, um para sleep e assim por diante, nunca um parser para a Garmin e outro para o WHOOP. A orientação do Terra para eventos daily e body é sobrescrever o dia guardado com o payload mais recente, porque eles chegam várias vezes por dia, como totais parciais.

Passo 6: verifique a assinatura do webhook#

"Every webhook sent by Terra includes an HMAC-based signature header" [todo webhook enviado pelo Terra inclui um header de assinatura baseado em HMAC], terra-signature, no formato t=<timestamp>,v1=<signature>. O Terra assina com HMAC-SHA256: o payload assinado é o timestamp, um . e depois "The actual JSON payload (that is, the request body)" [o payload JSON propriamente dito (ou seja, o corpo da requisição)], e a chave é o signing secret do seu endpoint. O Terra "requires the raw, unaltered body of the request to perform signature verification" [exige o corpo bruto e inalterado da requisição para verificar a assinatura], então leia o corpo bruto antes de qualquer parse de JSON. Ignore todo esquema que não seja v1 e compare em tempo constante.

const crypto = require("crypto");

function verifyTerraSignature(rawBody, header, secret) {
  // header example: "t=1723808700,v1=a5ee9dba..."
  let timestamp = null;
  const signatures = [];
  for (const part of header.split(",")) {
    const [key, value] = part.split("=", 2); // hex values never contain "="
    if (key === "t") timestamp = value;
    else if (key === "v1") signatures.push(value); // ignore other schemes
  }
  if (!timestamp || signatures.length === 0) return false;
  const expected = Buffer.from(
    crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex")
  );
  return signatures.some((sig) => {
    const provided = Buffer.from(sig);
    // timingSafeEqual throws on a length mismatch, so check length first
    return provided.length === expected.length && crypto.timingSafeEqual(provided, expected);
  });
}

Confira também o timestamp contra a sua própria tolerância, como a documentação do Terra sugere, para rejeitar replays. O Terra recomenda as bibliotecas oficiais dele em vez de uma checagem manual; a documentação de webhooks mostra versões com os SDKs para Python, JavaScript e Java.

Responda rápido: "Terra waits 8 seconds for your server to respond before considering the request timed out." [O Terra espera 8 segundos pela resposta do seu servidor antes de considerar que a requisição expirou.] Entregas que falham são repetidas "up to 10 times with exponential backoff" [até 10 vezes com backoff exponencial], ao longo de cerca de oito horas, e então "the event is dropped. There is no notification when this happens" [o evento é descartado. Não há notificação quando isso acontece], então devolva 200 na hora, processe de forma assíncrona e monitore o seu endpoint.

Passo 7: puxe os dados históricos via REST (opcional)#

Os webhooks entregam dados novos conforme chegam. Para o backfill na primeira conexão, chame os endpoints por tipo, como /activity (que "Returns completed workout sessions" [devolve sessões de treino concluídas]), /sleep, /daily, /body, /nutrition, /menstruation e /athlete, usando o user_id do Terra como chave.

curl --get "https://access.tryterra.co/api/v2/activity" \
  --header "dev-id: YOUR_DEV_ID" \
  --header "x-api-key: YOUR_API_KEY" \
  --data-urlencode "user_id=USER_ID" \
  --data-urlencode "start_date=2026-10-01" \
  --data-urlencode "end_date=2026-10-08" \
  --data-urlencode "to_webhook=false" \
  --data-urlencode "with_samples=true"

Quatro detalhes do guia de dados históricos do Terra pegam as pessoas desprevenidas:

• user_id e start_date são obrigatórios, e end_date "is exclusive on these endpoints" [é exclusivo nesses endpoints], então passe o dia seguinte ao último dia que você quer.
• to_webhook "will always be defaulted to true if not provided" [sempre terá true como padrão se não for informado], o que manda os dados para o seu destino em vez da resposta; defina-o como false para uma resposta síncrona.
• "For time ranges longer than 28 days, Terra will default to sending the data asynchronously" [para intervalos de tempo maiores que 28 dias, o Terra envia os dados de forma assíncrona por padrão], em partes de no máximo 10MB.
• with_samples precisa ser true para receber dados granulares.

Pegadinhas e notas de produção#

• Comece cedo os cadastros nos fornecedores. WHOOP e Dexcom exigem o seu próprio app nos portais deles e um domínio seu, e o acesso de produção é decisão do fornecedor, não do Terra.
• Nunca exponha a chave de API. Crie sessões de widget e puxe dados só a partir do seu backend; chamar a API de um navegador também falha por CORS.
• Verifique as assinaturas desde o primeiro dia e responda em até 8 segundos, ou os eventos começam a ser reenviados e, no fim, descartados.
• Limites de requisições (rate limits). A visão geral do Terra diz que ele "has no rate limits of its own" [não tem limites de requisições próprios], mas a referência de rate limits diz que ele "applies rate limits on data-read endpoints" [aplica limites de requisições nos endpoints de leitura de dados]: nenhuma requisição pode cobrir mais de cinco anos, e as requisições de um usuário não podem somar mais de 6.000 dias pedidos em uma hora. Divida os backfills de acordo.
• O preço é baseado em créditos, então faça a conta. Em 17 de outubro de 2026, as assinaturas "start from $399 per month billed annually, or $499 per month billed monthly" [começam em US$ 399 por mês com cobrança anual, ou US$ 499 por mês com cobrança mensal], incluindo 100.000 créditos por mês. Cada fonte de dados conectada custa 200 créditos por mês, os primeiros 400 eventos por fonte são gratuitos, e créditos extras começam em US$ 0,005. Pela nossa conta, 100.000 créditos cobrem 500 fontes conectadas antes dos eventos. Reconfira tryterra.co/pricing antes de fazer o orçamento.
• Agregador, não mágica. O Terra elimina o código OAuth e o parsing por fornecedor; ele não elimina a aprovação do app em cada fornecedor quando o fornecedor a exige. Essa troca, um pouco de papelada no painel em troca de uma base de código única para muitos wearables, é o que você está comprando.