Endpoint 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.

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

Apri Health.md sull'iPhone.
Vai a Esporta.
In Destinazione di esportazione, scegli Endpoint API.
Inserisci un URL, ad esempio https://api.example.com/healthmd/ingest.
Facoltativo: inserisci un token bearer. Health.md lo archivia nel Portachiavi.
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.