Endpoints för beställningar av hemtestkit kräver behörigheten
home_kit_orders_view (läs) eller home_kit_orders_manage
(skriv). Aktivera accepterar även den snävare
behörigheten home_kit_orders_activate. Hämta resultat och
Mejla resultat kräver dessutom results_view — labbresultat
och dokument skyddas alltid av den.Fält
UUID som genereras automatiskt av Aniva. Använd detta för att uppdatera beställningen, byta panel, aktivera den, avbryta
den och hämta resultat.
Aktuell livscykelstatus. Något av
pending, dispatched, activated eller cancelled. Se
Livscykel nedan. Detaljstatus för om labbresultaten är klara (in_progress eller completed)
hämtas från Hämta resultat.Adressen dit kitet ska skickas — i en av två former: antingen
{location_id} som refererar till en känd
testplats, eller de direkt angivna adressfälten (name, street, city, postal_code,
country_code; company_name / house_number / address_line_2 / state / phone / email
är valfria — samma fältnamn som i plats-API:et). Ange exakt ett alternativ — en platsreferens
eller en direkt angiven adress, inte båda.Packstation eller Postfiliale (endast Tyskland): ange
Packstation eller Postfiliale i street,
det tresiffriga stationsnumret i house_number och mottagarens DHL
Postnummer (6–10 siffror, mellanslag tillåtna) i address_line_2. Utan Postnummer kan paketet inte bokas.
Postfach stöds inte.ISO 8601-tidsstämpel för den senaste uppdateringen. Null om beställningen av hemtestkit aldrig har uppdaterats.
Det fullständiga profilobjektet för patienten, inbäddat i varje svar för en beställning av hemtestkit.
Panelen som är kopplad till beställningen av hemtestkit — alltid exakt en post med
{ panel_id, added_at },
eftersom ett hemtestkit motsvarar en fysisk kitprodukt 1:1. Jämför panel_id mot
Lista paneler.Biomarkörer som är kopplade till beställningen av hemtestkit utöver dess panel. Varje post är
{ biomarker_id, added_at }. Jämför varje biomarker_id mot
Lista biomarkörer med home_kit=true. Vid en vanlig beställning är dessa tilläggstester
utöver panelen; för ett ersättningskit är de vad laboratoriet
analyserar på nytt.Den beställning av hemtestkit som denna ersätter, när det är ett ersättningskit.
null vid
en vanlig beställning.Adresser som får ett mejl vardera när alla labbresultat är slutgiltiga, i gemener. Finns alltid med —
tom när funktionen är avstängd. Ange den vid Skapa eller
Uppdatera. Se
Mejl när resultat är klara.
Dina egna nyckel/värde-par som returneras exakt som de skickades och aldrig tolkas av Aniva. Finns alltid med vid
läsning —
{} om du inte har angett några. Högst 20 nycklar; nycklar måste matcha [A-Za-z0-9_-] och vara högst 40
tecken; värden är sträng, tal eller booleskt värde, med strängar på högst 500 tecken; 16 384
byte serialiserat totalt. Nycklar som börjar med aniva_ är reserverade. Vid
Uppdatera slås metadata ihop: nycklar du utelämnar finns kvar, en
nyckel som skickas som null tas bort och {} rensar allt. Valideringen gäller allt eller inget. Lägg aldrig
personuppgifter eller kliniska data i metadata — det behandlas inte som patientdata.Laboratoriets provkod. En kod, tre roller: koden som labbresultat rapporteras under, koden som trycks
på det fysiska kitet och det som patienten läser av från förpackningen som aktiveringskod. Tilldelas när
kitet packas —
null medan beställningen är pending, utom efter att Aniva skickar ett kit på nytt (se
Livscykel). Alltid skrivskyddad. Hitta beställningen för ett kit du har
i handen med GET /api/v1/home-kit-orders?lab_code=….Tidsstämpeln för provtagning som rapporteras via Aktivera — när
patienten faktiskt tog sitt prov, angiven i UTC.
null tills kitet aktiveras.
Detta är den provtagningstid som anges i labbrapporten.Paketen som är kopplade till denna beställning, äldsta kopplingen först, vardera
{ id, added_at } — kitet på
väg till patienten och, för kit där returen spåras, provet på väg tillbaka till
laboratoriet, som dyker upp så snart etiketterna skrivs ut. Tom medan beställningen är
pending, utom efter att Aniva skickar ett kit på nytt. Hämta
alla paketuppgifter i ett anrop med GET /api/v1/shipments?home_kit_order_id={id} — se
Försändelser.Livscykel
Beställningar av hemtestkit har fyra livscykelstatusar:
När Aniva skickar om ett försvunnet kit går beställningen tillbaka till
pending men behåller sin lab_code och sina
tidigare paket i shipments. Det nya kitet får samma kod. En oanvänd returetikett läggs i
den nya lådan. Bara Aniva gör dessa två ändringar; API:et erbjuder dem inte. Varje ändring skickar en
webhook för home_kit_order.pending eller home_kit_order.cancelled.
Statusen för en beställning av hemtestkit är medvetet grovkornig. Leveransen till och från
patienten spåras på beställningens försändelser –
dispatched betyder att kitet
har en etikett och en labbkod, inte att det har börjat röra sig; den utgående försändelsens status visar om
det har gjort det. Hanteringen av labbresultat ligger på inlämningarna. Om labbresultaten är klara (in_progress jämfört med
completed) visas via Hämta resultat – fältet status på
toppnivå är in_progress tills varje inlämning är avslutad, sedan completed – eller fault när
varje inlämning misslyckades utan att rapportera.Spåra paketen
destination är laboratoriet), kopplade via paired_with.
Returpaketet står som pending – med sitt spårningsnummer redan känt – tills patienten postar
det. Ett tarmmikrobiomkit visas som en försändelse: kitet till patienten. Dess returkuvert är
förbetalt och ospårat, så inget bokas för tillbakavägen. booked_by anger vem som bokade
etiketten: "aniva" eller "external". Bara ett "aniva"-paket kan ändras här, och bara dess
notes när etiketten väl är utskriven. Varje paket innehåller transportörens fullständiga status_updates,
inklusive DHL:s detail_code vid omdirigering till ett postkontor.
home_kit_orders på försändelsen listar bara de beställningar som ingår i din åtkomstkontext. Se
Åtkomst.
Lista beställningar av hemtestkit
Hämta alla beställningar av hemtestkit som din API-nyckel har åtkomst till:?profile_id={uuid} för att filtrera på en viss profil, eller ?lab_code={code} för att
koppla ett fysiskt kit i handen tillbaka till dess beställning – det naturliga första steget i ett aktiveringsflöde.
Skapa en beställning av hemtestkit
Begär en beställning av hemtestkit för en patientprofil:profile_id, en delivery_address och ett enda panel_id. Beställningen skapas med statusen pending.
Skicka med en valfri Idempotency-Key-header så att ett nytt försök inte beställer ett andra kit – se Idempotens.
Exakt en panel, eftersom ett hemtestkit motsvarar en fysisk kitprodukt 1:1 – panelen är kitet. Bara paneler som Aniva har konfigurerat som hemtestkit går att beställa; alla andra paneler avvisas med 422. Den krävs när beställningen skapas eftersom beställningen hamnar i packningskön direkt och packningen kan starta omedelbart. Medan beställningen är pending kan du byta panel via Uppdatera.
För att skicka ett nytt kit för ett som inte kunde ge några resultat skickar du replaces_home_kit_order_id i stället för att välja en panel – se Ersättningskit.
Ersättningskit
Ibland kan ett kit inte ge några resultat: patienten kunde inte fylla röret, provet kom fram med för lite material, laboratoriet kunde inte analysera en del av det. Beställ en ersättning för det:replaces_home_kit_order_id.
Beställningen du ersätter rörs inte. Den behåller sin status, sin labbkod och alla resultat som redan har registrerats under den, så en patient som ändå postar det första kitet får ut det laboratoriet kan läsa av från det.
Panelen ärvs. Utelämna panel_id så får ersättningen samma panel som beställningen den ersätter – det är den patienten köpte och den lådan är märkt med. Skicka bara en annan panel vid ersättning av en hel panel; en panel och en delmängd markörer tillsammans avvisas med 422, eftersom en delmängd bara har sin betydelse inom den panel den valdes från. Panelen för en ersättning kan inte heller bytas i efterhand.
Du väljer vad som körs om. Skicka biomarker_ids med de markörer som misslyckades så analyserar laboratoriet bara om dem, och kitet skickas bara med de rör som behövs. Utelämna fältet för att köra om hela panelen – rätt val när inget analyserades alls. Det här kräver inget extra scope: att köra om markörer som patienten redan har betalat för är inget à la carte-val. De markörerna kan inte tas bort i efterhand, eftersom de utgör hela remissen.
Markörer körs om utifrån panelens grupper, inte en och en. Om du anger en markör i en grupp körs
hela den gruppen om, eftersom en laboratoriebeställning som rapporterar mer än vad som beställts inte kan
läggas. En ersättning för en enskild markör kan därför komma tillbaka med fler än ett resultat, och
antalet rör kan vara större än vad markörlistan antyder.
pending eller dispatched returnerar ett andra försök för samma beställning 409 och anger ersättningen. Resultat kommer in under ersättningens egen lab_code, via dess egen Hämta resultat.
En ersättning är inte rätt sätt att hantera ett paket som aldrig kom fram. Meddela Aniva i stället: då handlar det om en ny försändelse av samma beställning under samma labbkod, inte en ny beställning.
Uppdatera en beställning av hemtestkit
Ändra leveransadressen, byt panel, uppdatera din metadata eller ersätt e-postadresserna för klara resultat:panel_id ersätter den kopplade panelen – med exakt en panel per kit är ett byte den enda meningsfulla panelåtgärden, vilket är anledningen till att det inte finns några slutpunkter för att lägga till eller ta bort paneler. Adressen och panelen kan bara ändras medan statusen är pending; metadata kan uppdateras under hela beställningens livstid. results_ready_emails kan uppdateras tills beställningen är cancelled.
Avbryta en beställning av hemtestkit
Avbryt en beställning av hemtestkit som inte längre behövs:cancelled. Den avbrutna beställningen av hemtestkit returneras i svaret.
Bara en beställning med statusen pending kan avbrytas. Från och med dispatched är kitet packat och försett med etikett – det finns ingen automatisk återkallelse – och anropet returnerar 409. Om ett kit som redan har skickats behöver stoppas, kontakta Aniva direkt.
Om du avbryter en pending-beställning vars kit redan har beställts från lagret avbryts det där också, och anropet lyckas bara om lagret godkänner det:
409– kitet var redan packat och försett med etikett, så det kan inte längre återkallas, även om beställningen fortfarande visarpending.502– lagret nekade att avbryta beställningen (felet innehåller deras orsak), eller gick inte att nå. Inget ändrades – beställningen är fortfarande aktiv och kan avbrytas igen.
200 är den enda bekräftelsen på att inget kit är på väg.
Att avbryta en beställning som redan är cancelled returnerar samma 200, oavsett vilken status den avbröts från.
Aktivera en beställning av hemtestkit
När patienten har tagit sitt prov, rapportera det:activated_at – den tidpunkt då patienten faktiskt tog provet, som en UTC-tidpunkt. Det här är den provtagningstid som kommer att stå i labbrapporten, så skicka den verkliga provtagningstidpunkten, inte din hanteringstid. Aktivering är slutgiltig: beställningen övergår till activated och kan inte längre avbrytas eller ändras. Motsvarigheten för hemtestkit till Bekräfta blodprovstagning, utan streckkod – kitets kod sätts på när kitet packas, så du behöver aldrig känna till den. Beställningen måste ha fått sin lab_code vid det laget; en beställning utan kod returnerar 409.
Aktiveringen är också det som lägger laboratoriebeställningen: kitets panel beställs hos laboratoriet under dess lab_code, så att det returnerade provet väntas in och resultat kopplas på i takt med att laboratoriet rapporterar dem. Detta körs efter svaret, och problem på laboratoriesidan hanteras av Aniva i stället för att visas i ditt anrop.
Enskilda biomarkörer
Du kan lägga till enskilda biomarkörer i en beställning av hemtestkit som à la carte-tester, utanför panelen. Det är användbart när du vill ha ett skräddarsytt urval utöver kitet. De tillagda biomarkörerna visas i svaret för beställningen av hemtestkit som enindividual_biomarkers-array (på samma nivå som panels).
Båda slutpunkterna för biomarkörer kräver capability-scopet home_kit_orders_individual_biomarker_selection utöver home_kit_orders_manage – hemtestkit beställs per panel, så enskilda markörer aktiveras per partner. Fråga Aniva om din integration behöver det.
Lägg till biomarkörer (idempotent – biomarkörer som redan är kopplade behålls):
biomarker_ids-array. Använd Lista biomarkörer med home_kit=true för att hitta ID:n för biomarkörer. Biomarkörer kan bara ändras medan kitet är pending (se Livscykel).
Hämta labbresultat
När labbet har bearbetat det returnerade provet hämtar du kliniska och genetiska resultat:planned) tillsammans med mottagna resultat, så att du kan följa vad som fortfarande väntar. Resultaten sparas under beställningens lab_code och kommer in markör för markör allteftersom labbet analyserar dem, så delvisa svar är normalt. Fältet status på toppnivå är in_progress fram till slutrapporten och blir sedan completed (eller fault om alla labbeställningar misslyckades utan att rapportera) – använd det för att avgöra om labbarbetet för hemtestkitbeställningen är klart. En home_kit_order.results.completed-webhook meddelar dig när det sker, så du behöver inte polla. PDF:er med labbrapporter refereras i documents-arrayen – använd GET /api/v1/documents/{id} för att ladda ner dem.