Hoppa till huvudinnehåll
En beställning av hemtestkit skickar ett testkit för egenprovtagning hemma med posten till en patient. Aniva skickar kitet, patienten tar själv provet hemma och postar tillbaka det. Detta skiljer sig från en bokning, som är en venös blodprovstagning som utförs på en fysisk testplats av vårdpersonal.
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

string
obligatorisk
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.
string
obligatorisk
UUID för profilen som denna beställning av hemtestkit tillhör.
string
obligatorisk
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.
object
obligatorisk
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.
string
obligatorisk
ISO 8601-tidsstämpel för när beställningen av hemtestkit skapades.
string
ISO 8601-tidsstämpel för den senaste uppdateringen. Null om beställningen av hemtestkit aldrig har uppdaterats.
object
Det fullständiga profilobjektet för patienten, inbäddat i varje svar för en beställning av hemtestkit.
object[]
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.
object[]
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.
string
Den beställning av hemtestkit som denna ersätter, när det är ett ersättningskit. null vid en vanlig beställning.
string
Varför ersättningen skickades, i en mening. null vid en vanlig beställning.
string[]
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.
object
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.
string
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=….
string
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.
object[]
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

Vad som returneras beror på kitet. Ett blodkit visas som två försändelser när Aniva har packat det: paketet från Aniva till patienten och paketet från patienten till laboratoriet (dess 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.
Sammansättningen för en beställning av hemtestkit kan bara ändras medan den är pending. När beställningen väl är dispatched (eller senare – activated/cancelled) returnerar panelbyten och /biomarkers-slutpunkterna 409 Conflict: det fysiska kitet packas utifrån den valda panelen, så innehållet låses i samma ögonblick som det skickas till patienten. Om du behöver ändra testerna i en beställning som redan är låst, kontakta Aniva direkt – det går oftast fortfarande att lösa, och vi gör ändringen åt dig så att kitets innehåll stämmer överens. Om kitet redan har använts och inte kunde ge några resultat, beställ ett ersättningskit i stället.

Lista beställningar av hemtestkit

Hämta alla beställningar av hemtestkit som din API-nyckel har åtkomst till:
Du kan valfritt skicka ?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:
Skicka med 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:
En ersättning är en ny beställning med en ny labbkod, även när det första kitet aldrig aktiverades: laboratoriet behöver en ny remiss, och två prover under samma kod går inte att skilja åt. Båda beställningarna förblir läsbara, kopplade via 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.
Bara en ersättning per kit får vara på väg åt gången – medan en ersättning är 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:
Ta bara med de fält du vill ändra. 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:
Detta sätter statusen för beställningen av hemtestkit till 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 visar pending.
  • 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.
Om ett anrop för att avbryta returnerar ett fel lämnas beställningen exakt som den var, så 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:
Skicka med 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 en individual_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):
Ta bort biomarkörer (idempotent – ett ID som inte är kopplat ignoreras):
Båda slutpunkterna tar en 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:
Svaret innehåller planerade tester (status 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.

Exempel på beställning av hemtestkit