Vai al contenuto principale
POST
Richiedi un ordine di kit domiciliare per il profilo di un paziente. Un ordine di kit domiciliare invia un kit di test fai da te per posta — Aniva spedisce il kit all’indirizzo di consegna, il paziente raccoglie da solo un campione a casa e lo rispedisce per posta. Questo è diverso da un appuntamento, che è un prelievo venoso in una sede di test. È richiesto esattamente un pannello. Un kit domiciliare corrisponde 1:1 a un prodotto kit fisico — il pannello è il kit — e l’ordine entra in coda di imballaggio non appena viene creato, quindi la composizione deve essere definitiva fin dall’inizio. Puoi comunque cambiare il pannello tramite Aggiorna ordine kit domiciliare finché l’ordine è pending.

Kit sostitutivi

Quando un kit non può fornire i risultati — il paziente non è riuscito a riempire la provetta, il campione è arrivato con troppo poco materiale, il laboratorio non è riuscito ad analizzarlo — ordina una sostituzione inviando replaces_home_kit_order_id. Una sostituzione è un nuovo ordine con un nuovo codice di laboratorio, anche quando il primo kit non è mai stato attivato: il laboratorio ha bisogno di una nuova richiesta e due campioni con lo stesso codice non possono essere distinti. L’ordine che sostituisci non viene modificato — mantiene il proprio stato, il proprio codice di laboratorio ed eventuali risultati già registrati per quell’ordine. Ne conseguono due cose:
  • Il pannello viene ereditato. Ometti panel_id e la sostituzione riprende il pannello dell’ordine che sostituisce, cioè ciò che il paziente ha acquistato e il marchio riportato sulla scatola.
  • Scegli tu cosa ripetere. Invia biomarker_ids con i marcatori non riusciti e il laboratorio ripete solo quelli, così il kit viene spedito solo con le provette necessarie. Omettilo per ripetere l’intero pannello.
I marcatori vengono ripetuti per gruppi del pannello, non uno per uno. Indicare un marcatore di un gruppo fa ripetere l’intero gruppo, perché non è possibile inviare un ordine di laboratorio che riporti più di quanto richiesto. Una sostituzione per un singolo marcatore può quindi arrivare con più di un risultato e il numero di provette può essere maggiore di quanto suggerisca l’elenco dei marcatori. Può essere in viaggio una sola sostituzione per kit alla volta.
Se hai effettuato l’integrazione prima che questi campi esistessero, Aniva legge anche metadata.original_kit_id e metadata.replacement_reason in fase di creazione e tratta l’ordine come una sostituzione. Questo è l’unico punto in cui i metadati vengono interpretati, esiste solo per supportare quella precedente integrazione e i campi sopra hanno sempre la precedenza. Invia i campi.
Un 201 significa che l’ordine è confermato e verrà passato alla logistica — non devi fare altro perché il kit venga imballato e spedito. Richiede lo scope home_kit_orders_manage. Invia un header opzionale Idempotency-Key per poter ripetere questa creazione in sicurezza — ripetere la stessa chiave restituisce la risposta originale invece di crearne una seconda. Vedi Idempotenza.

Richiesta

Parametri del body

string
obbligatorio
UUID del profilo paziente per cui creare l’ordine di kit domiciliare.
string
obbligatorio
UUID del pannello a catalogo da ordinare. Esattamente uno — un kit domiciliare corrisponde 1:1 a un prodotto kit fisico, quindi il pannello è il kit. Gli ID dei pannelli sono forniti da Aniva per il tuo account partner; vedi Elenca pannelli. Facoltativo per una sostituzione, dove per impostazione predefinita viene usato il pannello dell’ordine che sostituisci.
string
UUID dell’ordine di kit domiciliare che questo sostituisce. Inviarlo rende questo ordine un kit sostitutivo — vedi Kit sostitutivi sopra. L’ordine deve appartenere allo stesso profilo e non deve avere già una sostituzione in viaggio.
string
Il motivo per cui è necessaria la sostituzione, in una frase (ad esempio Zu wenig Material, HbA1c nicht auswertbar). Obbligatorio quando invii replaces_home_kit_order_id, altrimenti ignorato. Al massimo 500 caratteri.
integer[]
In una sostituzione, i marcatori che il laboratorio ripete — di solito quelli che il primo kit non ha potuto fornire. Ognuno deve far parte di ciò che richiedeva l’ordine che sostituisci; verifica con Elenca biomarcatori con home_kit=true. Omettilo per ripetere l’intero pannello. Accettato solo insieme a replaces_home_kit_order_id e non insieme a un panel_id diverso. Non richiede alcuno scope aggiuntivo: ripetere marcatori che il paziente ha già pagato non è una selezione à la carte.
object
Le tue coppie chiave/valore, restituite invariate a ogni lettura e mai interpretate da Aniva. Usalo per inserire il tuo riferimento d’ordine così da poterlo correlare senza salvare i nostri ID. Al massimo 20 chiavi; le chiavi rispettano [A-Za-z0-9_-] e hanno al massimo 40 caratteri; i valori sono stringhe, numeri o booleani, con stringhe di al massimo 500 caratteri; 16.384 byte serializzati in totale. Le chiavi che iniziano con aniva_ sono riservate. Non inserire mai dati personali o clinici in metadata — non viene trattato come dato del paziente.
string[]
Fino a 5 indirizzi che ricevono ciascuno un’email quando tutti i risultati di laboratorio sono definitivi. L’email rimanda alla pagina dei risultati nel pannello di amministrazione Aniva. La tua chiave richiede l’accesso results_view per il paziente, altrimenti 403. Omettilo per usare gli indirizzi predefiniti impostati per il gruppo del paziente. Una lista vuota disattiva le email. Vedi Email di risultati pronti.
object
obbligatorio
L’indirizzo a cui spedire il kit — in uno di due formati: { location_id }, che fa riferimento a una sede di test nota, oppure i campi dell’indirizzo inline (name, street, city, postal_code, country_code; company_name / house_number / address_line_2 / state / phone / email facoltativi — lo stesso vocabolario dell’API delle sedi). Fornisci esattamente uno dei due — un riferimento a una sede o un indirizzo inline, non entrambi.
Packstation o Postfiliale (solo Germania): imposta street su Packstation o Postfiliale, house_number sul numero a tre cifre della stazione e address_line_2 sul DHL Postnummer del destinatario (6–10 cifre, spazi consentiti). Senza il Postnummer, il pacco non può essere prenotato. Una Postfach non è supportata.

Risposta

In caso di successo, l’API restituisce 201 Created con il nuovo ordine di kit domiciliare.
string
obbligatorio
Identificatore univoco dell’ordine di kit domiciliare (UUID).
string
obbligatorio
UUID del profilo a cui appartiene questo ordine di kit domiciliare.
string
obbligatorio
Stato attuale dell’ordine di kit domiciliare. Uno tra pending, dispatched, activated o cancelled. Un ordine appena creato inizia in pending.
object
obbligatorio
L’indirizzo a cui spedire il kit — in uno di due formati: { location_id } che fa riferimento a una sede di test nota, oppure i campi dell’indirizzo inline (name, street, city, postal_code, country_code; company_name / house_number / address_line_2 / state / phone / email opzionali — lo stesso vocabolario dell’API delle sedi). Fornisci esattamente uno dei due — un riferimento a una sede o un indirizzo inline, non entrambi.
object
obbligatorio
Le coppie chiave/valore che hai fornito. Sempre presente — {} se non ne hai impostata nessuna.
string
L’ordine di kit domiciliare che questo sostituisce. null per un ordine normale.
string
Il motivo che hai fornito. null per un ordine normale.
string[]
obbligatorio
Indirizzi che ricevono ciascuno un’email quando tutti i risultati di laboratorio sono definitivi, in minuscolo. Vuoto se disattivato. Vedi Email di risultati pronti.
string
Codice campione di laboratorio con cui vengono refertati i risultati — stampato sul kit fisico e letto dal paziente sulla scatola come codice di attivazione. null finché il kit non viene imballato. Di sola lettura.
string
obbligatorio
Timestamp della raccolta comunicato tramite Attiva. null finché il kit non viene attivato.
string
obbligatorio
Timestamp ISO 8601 della creazione dell’ordine di kit domiciliare.
string
Timestamp ISO 8601 dell’ultimo aggiornamento. Può essere null.
object
obbligatorio
Il profilo del paziente associato a questo ordine di kit domiciliare.
HomeKitOrderPanel[]
obbligatorio
Il pannello associato a questo ordine di kit domiciliare — quello fornito come panel_id, registrato con l’ora di creazione dell’ordine. Sempre esattamente uno. Consulta i dettagli del pannello (nome, biomarcatori) tramite Elenca pannelli.
HomeKitOrderIndividualBiomarker[]
obbligatorio
Biomarcatori aggiunti al di fuori del pannello. Vuoto in una creazione normale — gli ordini di kit domiciliare vengono ordinati per pannello e modificare questo elenco in seguito richiede lo scope di funzionalità home_kit_orders_individual_biomarker_selection. In una sostituzione contiene i biomarker_ids che hai inviato, ovvero quelli che il laboratorio ripete.
HomeKitOrderShipmentLink[]
obbligatorio
Pacchi collegati a questo ordine di kit domiciliare, a partire dal collegamento più vecchio. Sempre vuoto alla creazione — leggi i pacchi completi con Elenca spedizioni e ?home_kit_order_id=.

Risposte di errore