Il flusso API
L’integrazione consiste essenzialmente in quattro passaggi:
1. POST /v1/orders → Creare ordine (panel, destinatario, profilo di branding)
2. Attivazione → L'utente finale attiva il kit (link/QR dal Suo sistema)
3. Webhook: status_changed → Notifica push ad ogni cambio di stato
4. GET /v1/orders/{id}/report → Recuperare il referto (JSON o FHIR R4)
Creare l’ordine
POST /v1/orders
Authorization: Bearer <token>
Content-Type: application/json
{
"panel": "longevity-basic",
"recipient": { ... },
"branding_profile": "partner-xyz",
"callback_url": "https://yourapp.example/webhook"
}
Risposta: Order-ID, ETA stimata fino all’arrivo del campione.
Monitorare lo stato
I passaggi di stato tipicamente avvengono così: created → shipped → delivered → sample_received → analyzed → report_ready. Tramite webhook viene informato in tempo reale di ogni transizione – nessun polling.
Recuperare il risultato
Non appena report_ready è stato attivato, recupera il referto:
GET /v1/orders/{id}/report?format=fhir
→ Bundle FHIR R4 con DiagnosticReport + Observations per ogni parametro. In alternativa format=json per un formato semplificato interno a Probatix.
Dati di risultato standardizzati
La standardizzazione è qui la leva principale. Chi lavora in health app, piattaforme di telemedicina o piattaforme assistenziali, dovrebbe distinguere due livelli nel formato dei dati del referto:
- Struttura – come sono organizzati i campi di un referto.
- Codifica – come viene nominato univocamente un singolo parametro.
Probatix fornisce entrambi secondo standard internazionali:
FHIR R4 è il formato HL7 per i dati clinici. Un referto arriva come bundle, in cui trova in modo strutturato:
- DiagnosticReport — il referto riassuntivo (stato, data di analisi, conclusione).
- Observation per ogni parametro — valore, unità, intervallo di riferimento, codice LOINC, flag (high/low/critical).
- Patient / Practitioner — metadati referenziali.
I codici LOINC identificano univocamente ogni parametro. Esempio: «Glucosio nel siero o plasma» riceve il codice LOINC 2345-7 – in tutto il mondo. Indipendentemente dal sistema che lavora sul lato ricevente: questo codice viene compreso. Vale per il colesterolo (2093-3), HbA1c (4548-4) e migliaia di altri parametri.
Vantaggio per Lei: se trasmette referti a un sistema terzo (cassa malati, EHR, server FHIR), risparmia la mappatura dei parametri. L’acquisizione del referto funziona «out of the box». Questa è la differenza tra un PDF che qualcuno deve mappare e un oggetto dati che può connettersi automaticamente.
Webhook al posto del polling
Invece di chiedere regolarmente lo stato, La contattiamo noi – sul Suo URL webhook, con payload firmato. Questo riduce il carico e mantiene la Sua app sincronizzata in tempo reale. Nota: l’interfaccia webhook è attualmente in beta release; specifica, procedura di firma e logica di retry vengono messe direttamente a disposizione dei partner del programma beta. Il polling tramite API REST è sempre possibile in parallelo.
Workflow flessibile
L’API non è l’unico modello d’integrazione. Può combinare:
- Solo API — la Sua app orchestra l’intero flusso.
- Partner Portal — operatività quotidiana nell’UI; API solo per i dati del referto.
- Integrazione nel webshop — ordinazione del kit tramite moduli pronti nel Suo shop.
Anche l’indirizzamento del referto è configurabile:
- Referto alla Sua app — Lo mostra nel Suo UI.
- Referto all’utente finale — tramite il portale paziente Probatix (white-label).
- Referto alla telemedicina/medico convenzionato — consegna diretta al sistema dello studio (soprattutto per modelli secondo §116b/117).
Time-to-Result
Per la maggior parte dei test il risultato è disponibile entro 48 ore dall’arrivo del campione in laboratorio. Cosa influenza la finestra:
- Specificità del parametro (alcuni metodi richiedono tempi di incubazione).
- Numero di parametri (dimensione del panel).
- Routing del laboratorio (carico dei laboratori collegati).
I webhook di stato La tengono aggiornata su ogni passaggio.
Sforzo di integrazione
Realisticamente:
- Caso d’uso minimo (creare ordine + polling dello stato + recupero del referto PDF): pochi giorni di tempo di sviluppo.
- Integrazione FHIR profonda (mappatura in server FHIR proprio, logica dei parametri nell’UI): 1-3 settimane.
- Integrazione di programma completa (UI, flusso app, indirizzamento del referto, reporting): 4-8 settimane con fase di test e di compliance.
Se non ha un team di sviluppo: il Partner Portal copre tutti i workflow — può iniziare subito e aggiungere l’integrazione API in seguito.