Esporta JSON di Apple Health alla tua API

Endpoint API è una destinazione di esportazione per chi vuole inviare i dati di Health.md al proprio server, webhook, database, dashboard o sistema di automazione. L'iPhone continua a leggere Apple Health ma, anziché scrivere file, invia tramite POST il JSON all'endpoint configurato.

Scegli il flusso API

Il tuo obiettivo	Inizia qui
Inviare i dati selezionati al tuo server	Segui questa guida. iPhone invia un POST JSON all’URL che configuri.
Interrogare i dati localmente su un Mac	API di query loopback. Mantieni l’API su questo Mac; non esporla alla rete.
Sviluppare un’app iOS per la salute	Documentazione Apple HealthKit per sviluppatori.

Inizia con un giorno

Installa Health.md su iPhone. Esamina l’esempio JSON fittizio prima di configurare il ricevitore.

Promemoria sulla privacy.

Questa destinazione invia intenzionalmente i dati sanitari selezionati all'URL inserito. Usa un endpoint che controlli o consideri attendibile, preferisci HTTPS e limita le metriche a quelle effettivamente necessarie al servizio.

Configurare la destinazione

1. Apri Health.md sull'iPhone.
2. Vai a Esporta.
3. In Destinazione di esportazione, scegli Endpoint API.
4. Inserisci un URL, ad esempio https://api.example.com/healthmd/ingest.
5. Facoltativo: inserisci un token bearer. Health.md lo archivia nel Portachiavi.
6. Tocca Fatto, scegli l'intervallo di date e le metriche, quindi tocca Esporta.

Se inserisci un token semplice, Health.md lo invia come Authorization: Bearer <token>. Se il valore inizia già con Bearer o Basic , Health.md lo invia senza modificarlo.

Struttura del payload

Health.md invia una richiesta POST per ogni azione di esportazione. Il corpo è un involucro healthmd.api_export con versione indipendente, contenente record giornalieri pubblici healthmd.health_data dello schema v8. L'involucro API v1 contiene i record giornalieri; la versione v2 può includere anche sidecar dei provider senza modificare lo schema dei record giornalieri.

records

Oggetti giornalieri completi dello schema v8 conservati per l'intervallo richiesto, inclusi i record completamente vuoti il cui manifesto delle query costituisce un'evidenza.

failed_date_details

Date per le quali si è verificato un errore prima che fosse possibile conservare un documento giornaliero.

daily_record_schema_version

Versione dello schema giornaliero usata in records. Avanza indipendentemente dalla versione dell'involucro API.

Sidecar dei provider

Record esterni facoltativi della versione v2, con schema e regole di identità propri, presenti quando è abilitato un provider connesso.

Consulta l'involucro API v1 completo generato in produzione e l'involucro API v2 con sidecar del provider. Il contratto API e CLI descrive ogni campo, confine di versione e regola di accettazione.

Requisiti dell’endpoint

Metodo

Deve accettare POST.

Tipo di contenuto

Deve accettare application/json.

Esito positivo

Dopo aver accettato il payload in modo sicuro, deve restituire uno stato 2xx.

Errori

Per le richieste rifiutate deve restituire 4xx o 5xx. Quando disponibile, Health.md mostra una breve anteprima della risposta.

Per un'acquisizione affidabile, rendi l'endpoint idempotente per data. L'utente potrebbe ripetere lo stesso intervallo di esportazione dopo aver modificato le metriche o corretto un errore del server.

Suggerimenti

• Esegui una prova con un solo giorno prima di caricare una cronologia estesa.
• Mantieni abilitata l'opzione Dati sanitari senza perdita quando è importante conservare tutte le informazioni della fonte; riduci l'intervallo di date per percorsi densi, documenti clinici, ECG o allegati.
• Convalida il token sul server prima di archiviare qualsiasi payload.
• Usa records[].date come chiave principale di ogni giorno.
• Restituisci un corpo di errore conciso: Health.md ne mostra soltanto una breve anteprima.

Risoluzione dei problemi

Problema	Significato probabile	Soluzione
La destinazione API non è pronta	L’URL è vuoto o non valido	Riapri le impostazioni di Endpoint API e inserisci un URL HTTP(S) valido.
HTTP 401 o 403	Il token manca o è stato rifiutato	Aggiorna il token o le regole di autenticazione del server.
HTTP 404	Il percorso dell’URL è errato	Controlla l’endpoint sul server.
HTTP 413	Il payload è troppo grande	Esporta meno giorni; usa l’output di solo riepilogo esclusivamente se il destinatario non richiede i record sorgente canonici.
Mancano alcune date	Per quelle date non esistono dati HealthKit abilitati	Controlla failed_date_details e la selezione delle metriche.

Contenuti correlati

OrigineEsportazione: scegli la destinazione e l'intervallo di date ed esegui esportazioni manuali. SchemaRiferimento API e CLI: involucri esatti, versioni, comportamento in caso di errore ed esempi generati. OutputPersonalizzazione del formato: JSON, CSV, Markdown, unità e campi.