Ordini di kit domiciliari
Attiva ordine di kit domiciliare
Comunica quando il paziente ha raccolto il campione
POST
/
api
/
v1
/
home-kit-orders
/
{id}
/
activate
curl --request POST \
--url https://anivahealth.com/api/v1/home-kit-orders/d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a/activate \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"activated_at": "2026-08-28T07:30:00Z"
}'
{
"id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
"profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
"status": "activated",
"lab_code": "7642200101",
"activated_at": "2026-08-28T07:30:00Z",
"delivery_address": {
"name": "Maria Schmidt",
"company_name": "c/o Weber",
"address_line_2": null,
"street": "Friedrichstraße",
"house_number": "123",
"postal_code": "10117",
"city": "Berlin",
"country_code": "DE",
"phone": "+4930123456789",
"email": "maria.schmidt@example.com"
},
"created_at": "2026-08-20T09:45:00Z",
"updated_at": "2026-08-28T07:31:12Z",
"profile": {
"id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
"handle": null,
"first_name": "Maria",
"last_name": "Schmidt",
"email": "maria.schmidt@example.com",
"phone": "+4930123456789",
"sex": 2,
"date_of_birth": "1985-03-22",
"height": 168,
"weight": 65,
"language": "de",
"transactional_emails_enabled": true,
"created_at": "2026-08-20T09:14:32Z",
"updated_at": null
},
"panels": [
{
"panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
"added_at": "2026-08-20T09:45:00Z"
}
],
"individual_biomarkers": [],
"metadata": { "your_order_ref": "ORD-10482" },
"replaces_home_kit_order_id": null,
"replacement_reason": null,
"results_ready_emails": [],
"shipments": [
{ "id": "K2608211FQ7", "added_at": "2026-08-21T08:00:00Z" },
{ "id": "K260821P3XD", "added_at": "2026-08-21T08:00:00Z" }
]
}
{
"error": "Home kit order is already activated"
}
Segnala che il paziente ha raccolto il campione. È l’equivalente per il kit domiciliare di
Conferma prelievo di sangue, senza codice a barre, perché il
codice del kit viene applicato al momento del confezionamento. Passi solo il timestamp della
raccolta.
Il timestamp ha rilevanza clinica: è l’orario di raccolta che comparirà sul referto di laboratorio.
Invia il momento effettivo in cui il paziente ha raccolto il campione, non il momento in cui il tuo
sistema l’ha elaborato.
Inviare di nuovo lo stesso
activated_at restituisce 200 con l’ordine attivato; un valore diverso restituisce 409. Vedi Idempotenza.
L’attivazione porta l’ordine allo stato activated, uno stato finale. Un ordine attivato non può
più essere annullato e la sua composizione e l’indirizzo di consegna vengono bloccati. L’attivazione
è accettata finché l’ordine è pending o dispatched, purché abbia un lab_code: il paziente può
avere in mano il kit prima che i nostri sistemi lo segnino come spedito, e l’orario reale di
raccolta prevale sempre sui nostri registri. Un ordine senza lab_code restituisce 409: senza il
codice, il campione non può essere associato al paziente in laboratorio.
L’attivazione invia anche l’ordine di laboratorio per il pannello del kit con il lab_code
dell’ordine, così il laboratorio attende il campione e i risultati possono essere associati appena
vengono comunicati. Questo avviene in modo asincrono dopo la risposta: un problema del laboratorio
non fa mai fallire la tua richiesta. Da questo momento in poi,
Ottieni risultati mostra i marker come planned finché il
laboratorio non li comunica. Un webhook home_kit_order.results.updated ti
avvisa quando cambiano.
Se il campione arriva in laboratorio prima che tu attivi il kit, lo attiva Aniva. activated_at è
la mattina del primo evento di tracciamento del pacco di ritorno, oppure la mattina in cui il
campione è arrivato in laboratorio se non c’è tracciamento. Una chiamata successiva con un
activated_at diverso restituisce quindi 409.
Richiede lo scope home_kit_orders_manage oppure lo scope più ristretto home_kit_orders_activate.
Richiesta
Parametri di percorso
Parametri del body
Quando il paziente ha raccolto il campione, come istante UTC (ISO 8601 con suffisso
Z, ad es.
2026-08-28T07:30:00Z). Non deve essere nel futuro né oltre 30 giorni nel passato.Risposta
In caso di successo, l’API restituisce200 OK con l’ordine di kit domiciliare aggiornato — status è activated e
activated_at contiene il timestamp che hai inviato.
Risposte di errore
| Stato | Descrizione |
|---|---|
400 | Errore di validazione — activated_at non valido, un timestamp futuro o più vecchio di 30 giorni. |
403 | Accesso negato — la tua chiave API non ha accesso a questa operazione oppure l’ordine di kit domiciliare è fuori dal tuo ambito di permessi. |
404 | Ordine di kit domiciliare non trovato. |
409 | Conflitto — già attivato con un orario di raccolta diverso, annullato o ancora senza lab_code. |
500 | Errore interno del server. |
curl --request POST \
--url https://anivahealth.com/api/v1/home-kit-orders/d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a/activate \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"activated_at": "2026-08-28T07:30:00Z"
}'
{
"id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
"profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
"status": "activated",
"lab_code": "7642200101",
"activated_at": "2026-08-28T07:30:00Z",
"delivery_address": {
"name": "Maria Schmidt",
"company_name": "c/o Weber",
"address_line_2": null,
"street": "Friedrichstraße",
"house_number": "123",
"postal_code": "10117",
"city": "Berlin",
"country_code": "DE",
"phone": "+4930123456789",
"email": "maria.schmidt@example.com"
},
"created_at": "2026-08-20T09:45:00Z",
"updated_at": "2026-08-28T07:31:12Z",
"profile": {
"id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
"handle": null,
"first_name": "Maria",
"last_name": "Schmidt",
"email": "maria.schmidt@example.com",
"phone": "+4930123456789",
"sex": 2,
"date_of_birth": "1985-03-22",
"height": 168,
"weight": 65,
"language": "de",
"transactional_emails_enabled": true,
"created_at": "2026-08-20T09:14:32Z",
"updated_at": null
},
"panels": [
{
"panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
"added_at": "2026-08-20T09:45:00Z"
}
],
"individual_biomarkers": [],
"metadata": { "your_order_ref": "ORD-10482" },
"replaces_home_kit_order_id": null,
"replacement_reason": null,
"results_ready_emails": [],
"shipments": [
{ "id": "K2608211FQ7", "added_at": "2026-08-21T08:00:00Z" },
{ "id": "K260821P3XD", "added_at": "2026-08-21T08:00:00Z" }
]
}
{
"error": "Home kit order is already activated"
}
⌘I
curl --request POST \
--url https://anivahealth.com/api/v1/home-kit-orders/d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a/activate \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"activated_at": "2026-08-28T07:30:00Z"
}'
{
"id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
"profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
"status": "activated",
"lab_code": "7642200101",
"activated_at": "2026-08-28T07:30:00Z",
"delivery_address": {
"name": "Maria Schmidt",
"company_name": "c/o Weber",
"address_line_2": null,
"street": "Friedrichstraße",
"house_number": "123",
"postal_code": "10117",
"city": "Berlin",
"country_code": "DE",
"phone": "+4930123456789",
"email": "maria.schmidt@example.com"
},
"created_at": "2026-08-20T09:45:00Z",
"updated_at": "2026-08-28T07:31:12Z",
"profile": {
"id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
"handle": null,
"first_name": "Maria",
"last_name": "Schmidt",
"email": "maria.schmidt@example.com",
"phone": "+4930123456789",
"sex": 2,
"date_of_birth": "1985-03-22",
"height": 168,
"weight": 65,
"language": "de",
"transactional_emails_enabled": true,
"created_at": "2026-08-20T09:14:32Z",
"updated_at": null
},
"panels": [
{
"panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
"added_at": "2026-08-20T09:45:00Z"
}
],
"individual_biomarkers": [],
"metadata": { "your_order_ref": "ORD-10482" },
"replaces_home_kit_order_id": null,
"replacement_reason": null,
"results_ready_emails": [],
"shipments": [
{ "id": "K2608211FQ7", "added_at": "2026-08-21T08:00:00Z" },
{ "id": "K260821P3XD", "added_at": "2026-08-21T08:00:00Z" }
]
}
{
"error": "Home kit order is already activated"
}