Ellie Care · Developers

Quickstart

Pedí un token y hacé tu primer llamado contra el sandbox. Clientes de prueba: ellie_sandbox_br (LATAM) y ellie_sandbox_us (US), secret sandbox.

bash · sandbox

# base del sandbox (datos sintéticos)
BASE=https://ec-edge-403466748464.southamerica-east1.run.app

# 1) token OAuth2 (el empresa_id + zona van dentro del 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) tu primer llamado — sin parámetro de empresa (sale del 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"

¿Preferís explorar? Abrí la referencia interactiva (try-it contra el sandbox).

Autenticación

OAuth 2.0 client-credentials (app-a-app). Registrás una app → client_id + client_secret. El token es de vida corta y lleva tu empresa_id, tu zone y tus scopes.

Scope	Permite
`read:patients`	Listar y leer tus pacientes
`read:devices`	Dispositivos, config y capacidades
`read:vitals`	Telemetría (vitales, actigrafía)
`read:alerts`	Historial de alertas
`telecheckup:read`	Leer telechequeos
`telecheckup:request`	Solicitar un telechequeo
`subscribe:events`	Webhooks y polling de eventos

Tenencia y zonas

Tu empresa_id sale del token — nunca lo mandás por query ni body, y por eso solo ves a tus propios pacientes. Cada empresa tiene una zona de residencia y sus datos de salud no salen de su región.

🇧🇷 LATAM

Datos en southamerica-east1 (LGPD/ANPD). Empresas de AR/BR/UY/PE.

🇺🇸 US

Datos en us-central1 (HIPAA/BAA). No se mezclan con LATAM.

Todos los recursos de paciente quedan scopeados a tu empresa: pedir un patient_id de otro tenant devuelve 404.

Eventos (webhooks)

Registrás tu URL vos mismo (self-serve) y Ellie te empuja los eventos crudos (señales, no alertas pre-juzgadas) como CloudEvents. Cada entrega viene firmada con HMAC en X-Ellie-Signature: verificá SIEMPRE la firma. Alternativa sin endpoint: polling GET /v1/events (omití since la primera vez; después pasás ?since=<next_cursor>).

Las alertas de vida (caída, SOS) hoy se entregan por el canal legacy de ec-be y migran a este contrato más adelante — por eso no están en esta lista todavía. El historial de alertas evaluadas está en GET /v1/alerts.

Evento	Tier	Qué es
`clinical.event`	Clínico	Señal clínica: sleep_hint_start/end, FC ↑/↓ baseline, SpO2 bajo, temp. piel (campo `kind`)
`device.status`	Normal	Estado operativo: puesto/no puesto (worn/not_worn), cargando, batería baja, conectividad, offline (`state`)
`telecheckup.completed / .failed / .deferred`	Ciclo	Ciclo de vida de un telechequeo

bash · registrar tu webhook (self-serve)

# 1) registrás tu URL → te devuelve el secret UNA sola vez (guardalo)
curl -s -X POST $BASE/v1/subscriptions -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://tu-endpoint/hooks","event_types":["clinical.event","device.status"]}'
# → 201 { "id":"sub_…", "secret":"whsec_…", "status":"active", … }

# 2) probás la entrega firmada de punta a punta (colon literal, no lo URL-encodees)
curl -s -X POST "$BASE/v1/subscriptions/sub_…:test" -H "Authorization: Bearer $TOKEN"
# → 202 { "status":"delivered", "response_status":200 }

node · verificar la firma

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

Gestionás tus suscripciones con GET /v1/subscriptions y DELETE /v1/subscriptions/{id}. ¿Primer caso guiado paso a paso? Ver el runbook del primer caso.

Datos de salud: telemetría, telechequeos y FHIR

La telemetría y los telechequeos se sirven en dos formas: REST crudo o FHIR R4 estándar. El edge esconde de dónde salen (AWS/GCP).

Telemetría — GET /v1/vitals?patient_id=&type=heart_rate&since=. Tipos: heart_rate, spo2, skin_temperature (temp), ibi, eda, motion (=actigrafía ENMO), steps, calories, battery, ppg/ppg_ir/ppg_red, accel_raw. Sueño: la serie motion/ENMO trae meta.mode=sleep_hint + los eventos clinical.event sleep_hint_start/end. Alto volumen → cursor + since.
Telechequeos físicos — pruebas guiadas (gait, sit_to_stand, balance, respiratory + spot vitals). GET /v1/patients/{id}/telecheckups; se solicitan con POST /v1/telecheckups:request. Siempre reportan estado (done/failed/deferred).
FHIR — GET /fhir/Observation?patient=&code=8867-4 (LOINC). Devuelve un Bundle R4. Telechequeo emocional (ansiedad/depresión) como QuestionnaireResponse.

PHI clínico: los telechequeos son datos de salud sensibles. En producción exigen scope clínico + consentimiento por zona. En sandbox todo es sintético.

Errores y paginación

Los errores llegan en RFC 9457 (application/problem+json), parseables. La paginación es siempre por cursor (next_cursor), nunca offset.

application/problem+json

{ "type": "https://api.ellie.care/errors/insufficient-scope",
  "title": "Falta el scope read:vitals", "status": 403,
  "detail": "Tu token no incluye read:vitals." }

Entornos: sandbox ec-edge-…run.app (sintético, sin PHI) → producción api.ellie.care (mismo contrato, solo cambiás host y credenciales). Versionado por /v1.

Conectá tu sistema a Ellie Care