Conecte seu sistema à Ellie Care

01O que é a Ellie Care?

02Os protagonistas

Seis atores. Entender quem é quem é metade do modelo mental — o resto da API se encaixa sozinho.

03Como funciona

O ciclo da teleassistência em quatro passos; a API te conecta no passo 4. Por baixo, uma única porta (api.ellie.care) te autentica, te isola por empresa e zona, e te entrega apenas o que é seu.

04O relógio: o que ele mede

O relógio faz três coisas: mede vitais contínuos enquanto é usado, executa medições sob demanda, e detecta eventos de segurança.

Vitais contínuos — enquanto o relógio está no pulso

Sinais do dispositivo — técnicos, não clínicos

Chegam pelo canal device.status e em GET /devices/{id}. Servem para adesão e operação.

Telecheckups — medições guiadas, sob demanda

O seu sistema (ou um operador) solicita uma medição; o relógio orienta o paciente, coleta a amostra e devolve um resultado com status done/failed/deferred.

Segurança de vida

05Sinal vs. alerta

A distinção que evita mal-entendidos: a Ellie te envia sinais brutos, não veredictos clínicos.

Por isso o contrato separa eventos clínicos (clinical.event), estado do dispositivo (device.status) e alertas (vida). A Ellie evita pré-julgar: entrega o sinal para que o seu sistema aplique a própria lógica clínica.

06O que você pode fazer com a API

Tudo restrito à sua empresa (vem do token) e aos seus pacientes. Em linguagem de negócio:

07Primeiros passos e Quickstart

Do zero ao seu primeiro dado, sem dados reais. O mapa, e depois o código.

# base do sandbox (dados sintéticos)
BASE=https://api-sandbox.ellie.care

# 1) token OAuth2 (o empresa_id + zona vão dentro do token)
TOKEN=$(curl -s -X POST $BASE/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=ellie_sandbox_br -d client_secret=sandbox \
  -d scope="read:patients read:vitals telecheckup:read" \
  | jq -r .access_token)

# 2) sua primeira chamada — sem parâmetro de empresa (vem do token)
curl -s $BASE/v1/patients -H "Authorization: Bearer $TOKEN"
curl -s "$BASE/v1/vitals?patient_id=pat_test_001&type=heart_rate" -H "Authorization: Bearer $TOKEN"

Prefere explorar sem escrever código? Abra a referência interativa (try-it contra o sandbox).

08Autenticação

OAuth 2.0 client-credentials (app-a-app). Você registra uma app → client_id + client_secret. O token é de vida curta e carrega o seu empresa_id, a sua zone e os seus scopes.

09Dados de saúde: endpoints

A telemetria e os telecheckups são servidos de duas formas: REST bruto ou FHIR R4 padrão. O edge abstrai de onde eles vêm.

• Telemetria — GET /v1/vitals?patient_id=&type=heart_rate&since=. Tipos: heart_rate, spo2, skin_temperature, ibi, eda, motion (actigrafia ENMO), steps, calories, ppg/ppg_ir/ppg_red, accel_raw. Alto volume → cursor + since.
• Frequência cardíaca agregada por minuto — GET /v1/patients/{id}/vitals/heart-rate?start=&end=. Mediana, máx, mín e quantidade de amostras por minuto. Janela ≤ 30 dias por consulta; para mais, pagine.
• Sessões de sono — GET /v1/patients/{id}/sleep-sessions. Janela de sono com sinais médios (HR, EDA, HRV, temperatura, actigrafia). Roadmap
• Telecheckups — GET /v1/patients/{id}/telecheckups; são solicitados com POST /v1/telecheckups:request. Sempre reportam status (done/failed/deferred).
• FHIR — GET /v1/fhir/Observation?patient=&code=8867-4 (LOINC). Devolve um Bundle R4. Telecheckup emocional como QuestionnaireResponse.

10Eventos (webhooks)

Você mesmo registra a sua URL (self-serve) e a Ellie te envia os eventos brutos (sinais, não alertas pré-julgados) como CloudEvents. Cada entrega vem assinada com HMAC em X-Ellie-Signature: verifique SEMPRE a assinatura. Alternativa sem endpoint: polling GET /v1/events (omita since na primeira vez; depois ?since=<next_cursor>).

# 1) registra sua URL → devolve o secret UMA única vez (guarde-o)
curl -s -X POST $BASE/v1/subscriptions -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://seu-endpoint/hooks","event_types":["clinical.event","device.status"]}'
# → 201 { "id":"sub_…", "secret":"whsec_…", "status":"active", … }

# 2) testa a entrega assinada de ponta a ponta (dois-pontos literal, não faça URL-encode)
curl -s -X POST "$BASE/v1/subscriptions/sub_…:test" -H "Authorization: Bearer $TOKEN"
# → 202 { "status":"delivered", "response_status":200 }

const mac = crypto.createHmac("sha256", WEBHOOK_SECRET).update(rawBody).digest("hex");
if (`sha256=${mac}` !== req.header("X-Ellie-Signature")) return res.status(401).end();

Você gerencia suas assinaturas com GET /v1/subscriptions e DELETE /v1/subscriptions/{id}.

11Tenência, zonas e privacidade

Seu empresa_id vem do token — você nunca o envia por query nem body, e por isso só vê os seus próprios pacientes. Cada empresa tem uma zona de residência e os seus dados de saúde não saem da sua região.

• Um mesmo host (api.ellie.care) te roteia para a sua região conforme o token.
• Pedir um patient_id de outro tenant devolve 404. Você só vê o que é seu.
• O sandbox usa dados 100% sintéticos (zero PHI real).

12Casos de uso reais

O que as empresas constroem sobre a Ellie. Cada um combina alguns poucos endpoints.

13Sandbox → Produção

É a mesma API. Passar para prod não é reprogramar: você troca 2 valores (host + credenciais).

14Erros e paginação

Os erros chegam em RFC 9457 (application/problem+json), parseáveis. A paginação é sempre por cursor (next_cursor), nunca offset.

{ "type": "https://api.ellie.care/errors/insufficient-scope",
  "title": "Falta o scope read:vitals", "status": 403,
  "detail": "Seu token não inclui read:vitals." }

15Perguntas frequentes

16Glossário

Pronto para o detalhe endpoint por endpoint? Abra a referência interativa e teste contra o sandbox.