Spring til hovedindhold
En bestilling af hjemmetestkit sender et gør-det-selv-testkit med posten til en patient. Aniva sender kittet, patienten tager selv prøven derhjemme og sender den tilbage med posten. Dette adskiller sig fra en tid, som er en venøs blodprøvetagning udført af en sundhedsperson på et fysisk teststed.
Endpoints til bestilling af hjemmetestkits kræver scopet home_kit_orders_view (læsning) eller home_kit_orders_manage (skrivning). Aktivér accepterer også det smallere scope home_kit_orders_activate. Hent resultater og Send resultater på e-mail kræver desuden results_view – laboratorieresultater og dokumenter er altid beskyttet af dette scope.

Felter

string
påkrævet
UUID automatisk genereret af Aniva. Brug dette til at opdatere bestillingen, skifte panelet, aktivere den, annullere den og hente resultater.
string
påkrævet
UUID for den profil, denne bestilling af hjemmetestkit tilhører.
string
påkrævet
Aktuel livscyklusstatus. En af pending, dispatched, activated eller cancelled. Se Livscyklus nedenfor. Detaljeret status for laboratorieresultater (in_progress vs. completed) udledes fra Hent resultater.
object
påkrævet
Adressen, som kittet sendes til – én af to former: enten {location_id}, som henviser til et kendt teststed, eller inline-adressefelterne (name, street, city, postal_code, country_code; company_name / house_number / address_line_2 / state / phone / email er valgfrie – samme feltnavne som i locations-API’et). Angiv præcis én af dem – en lokationsreference eller en inline-adresse, ikke begge.
Packstation eller Postfiliale (kun Tyskland): sæt street til Packstation eller Postfiliale, house_number til det trecifrede stationsnummer og address_line_2 til modtagerens DHL Postnummer (6–10 cifre, mellemrum tilladt). Uden Postnummer kan pakken ikke bookes. En Postfach understøttes ikke.
string
påkrævet
ISO 8601-tidsstempel for, hvornår hjemmetestkitordren blev oprettet.
string
ISO 8601-tidsstempel for den seneste opdatering. Null, hvis bestillingen af hjemmetestkit aldrig er blevet opdateret.
object
Det fulde profilobjekt for patienten, indlejret i hvert svar på en bestilling af hjemmetestkit.
object[]
Panelet, der er tilknyttet bestillingen af hjemmetestkit – altid præcis ét element af typen { panel_id, added_at }, fordi et hjemmetestkit svarer 1:1 til et fysisk kitprodukt. Krydstjek panel_id mod Vis paneler.
object[]
Biomarkører, der er tilknyttet bestillingen af hjemmetestkit uden for dens panel. Hvert element er { biomarker_id, added_at }. Krydstjek hvert biomarker_id mod Vis biomarkører med home_kit=true. På en almindelig bestilling er dette tilvalgstests ud over panelet; på et erstatningskit er det dem, laboratoriet analyserer igen.
string
Den bestilling af hjemmetestkit, som denne erstatter, når det er et erstatningskit. null på en almindelig bestilling.
string
Hvorfor erstatningen blev sendt, i én sætning. null på en almindelig bestilling.
string[]
Adresser, der hver får én e-mail, når alle laboratorieresultater er endelige, skrevet med små bogstaver. Altid til stede – tom, når funktionen er slået fra. Angiv det ved Opret eller Opdater. Se E-mails om færdige resultater.
object
Dine egne nøgle/værdi-par, som returneres ordret og aldrig fortolkes af Aniva. Altid til stede ved læsning – {} når du ikke har angivet nogen. Højst 20 nøgler; nøgler skal matche [A-Za-z0-9_-] og må højst være på 40 tegn; værdier er en streng, et tal eller en boolean, hvor strenge må være højst 500 tegn; 16.384 bytes serialiseret i alt. Nøgler, der starter med aniva_, er reserverede. Ved Opdater bliver metadata flettet: nøgler, du udelader, bevares, en nøgle sendt som null slettes, og {} rydder alt. Validering er alt-eller-intet. Indsæt aldrig personlige eller kliniske data i metadata – det behandles ikke som patientdata.
string
Laboratoriets prøvekode. Én kode, tre roller: det, laboratorieresultaterne rapporteres under, det, der er trykt på det fysiske kit, og det, patienten aflæser på æsken som aktiveringskode. Tildeles, når kittet pakkes – null mens bestillingen er pending, undtagen efter at Aniva sender et kit igen (se Livscyklus). Altid skrivebeskyttet. Slå et fysisk kit op for at finde bestillingen med GET /api/v1/home-kit-orders?lab_code=….
string
Tidsstemplet for prøvetagning rapporteret via Aktivér – hvornår patienten faktisk tog sin prøve, angivet i UTC. null indtil kittet er aktiveret. Dette er det prøvetagningstidspunkt, der fremgår af laboratorierapporten.
object[]
Pakkerne, der er knyttet til denne bestilling, med den ældste tilknytning først, hver med { id, added_at } – kittet på vej til patienten og, for kits hvor returstrækningen spores, prøven på vej tilbage til laboratoriet, som vises i det øjeblik etiketterne udskrives. Tom, mens bestillingen er pending, undtagen efter at Aniva sender et kit igen. Hent de fulde pakkedata i ét kald med GET /api/v1/shipments?home_kit_order_id={id} – se Forsendelser.

Livscyklus

Bestillinger af hjemmetestkits har fire livscyklustilstande:
Når Aniva genfremsender et bortkommet kit, går ordren tilbage til pending, men beholder sin lab_code og sine tidligere pakker i shipments. Det nye kit har den samme kode. En ubrugt returlabel lægges i den nye kasse. Kun Aniva foretager disse to ændringer; API’et tilbyder dem ikke. Hver ændring sender en webhook for home_kit_order.pending eller home_kit_order.cancelled.
Statusoversigten for ordrer på hjemmetestkits er bevidst overordnet. Leveringsforløbet til og fra patienten spores på ordrens forsendelser – dispatched betyder, at kittet har en label og en laboratoriekode, ikke at det er sendt afsted; den udgående forsendelses status viser, om det er. Behandlingen af laboratorieresultater ligger på indsendelser. Færdiggørelsen af laboratorieresultater (in_progress vs. completed) vises via Hent resultater – det overordnede status-felt er in_progress, indtil hver indsendelse er afsluttet, derefter completed – eller fault, hvis alle indsendelser fejlede uden at rapportere.

Sporing af pakkerne

Hvad der kommer tilbage, afhænger af kittet. Et blodkit kommer som to forsendelser, når Aniva har pakket det: pakken fra Aniva til patienten og den fra patienten til laboratoriet (dens destination er laboratoriet), koblet sammen via paired_with. Returpakken står som pending – med sit sporingsnummer allerede kendt – indtil patienten sender den. Et tarmmikrobiomkit kommer som én forsendelse: kittet til patienten. Dets returkuvert er forudbetalt og uden sporing, så der bestilles intet til returforsendelsen. booked_by angiver, hvem der bestilte labelen: "aniva" eller "external". Kun en "aniva"-pakke kan ændres her, og kun dens notes, når labelen først er udskrevet. Hver pakke indeholder fragtfirmaets fulde status_updates, herunder DHL’s detail_code for omdirigering til et posthus. home_kit_orders på forsendelsen viser kun de ordrer, der er inden for din adgangskontekst. Se Adgang.
Sammensætningen af en ordre på et hjemmetestkit kan kun ændres, mens den er pending. Når ordren er dispatched (eller senere – activated/cancelled), returnerer panelskift og /biomarkers-endpoints 409 Conflict: Det fysiske kit pakkes ud fra det valgte panel, så dets indhold er låst i det øjeblik, det sendes til patienten. Hvis du har brug for at ændre prøverne på en ordre, der allerede er låst, så kontakt Aniva direkte – det er som regel stadig muligt, og vi laver ændringen for dig for at holde kittets indhold konsistent. Hvis kittet allerede er brugt og ikke kunne levere sine resultater, skal du i stedet bestille et erstatningskit.

Liste over ordrer på hjemmetestkits

Hent alle ordrer på hjemmetestkits, som din API-nøgle har adgang til:
Send eventuelt ?profile_id={uuid} for at filtrere efter en bestemt profil, eller ?lab_code={code} for at koble et fysisk kit i hånden tilbage til dets ordre – det naturlige første skridt i et aktiveringsflow.

Oprettelse af ordre på hjemmetestkit

Opret en ordre på et hjemmetestkit til en patientprofil:
Send profile_id, en delivery_address og et enkelt panel_id. Ordren oprettes med statussen pending. Send en valgfri Idempotency-Key-header, så et nyt forsøg ikke bestiller et ekstra kit – se Idempotens. Præcis ét panel, fordi et hjemmetestkit svarer 1:1 til et fysisk kitprodukt – panelet er kittet. Kun paneler, som Aniva har konfigureret som hjemmetestkits, kan bestilles; alle andre paneler afvises med 422. Det er påkrævet ved oprettelsen, fordi ordren kommer i pakkekøen med det samme, og pakningen kan gå i gang straks. Mens ordren er pending, kan du skifte panelet via Opdater. For at sende et nyt kit i stedet for et, der ikke kunne levere sine resultater, skal du sende replaces_home_kit_order_id i stedet for at vælge et panel – se Erstatningskits.

Erstatningskits

Nogle gange kan et kit ikke levere sine resultater: Patienten kunne ikke fylde røret, prøven ankom med for lidt materiale, eller laboratoriet kunne ikke analysere en del af den. Bestil en erstatning til det:
En erstatning er en ny ordre med en ny laboratoriekode, også selvom det første kit aldrig blev aktiveret: Laboratoriet har brug for en ny rekvisition, og to prøver med samme kode kan ikke skelnes fra hinanden. Begge ordrer forbliver læsbare og er koblet sammen via replaces_home_kit_order_id. Ordren, du erstatter, røres ikke. Den beholder sin status, sin laboratoriekode og eventuelle resultater, der allerede er registreret under den, så en patient, der alligevel sender det første kit ind, får det, som laboratoriet kan aflæse fra det. Panelet arves. Udelad panel_id, så får erstatningen panelet fra den ordre, den erstatter – det er det, patienten har købt, og sådan kassen er brandet. Send kun et andet panel ved erstatning af et helt panel; et panel og et deludvalg af markører sammen afvises med 422, fordi et deludvalg kun giver mening under det panel, det blev valgt fra. Panelet på en erstatning kan heller ikke skiftes bagefter. Du vælger, hvad der analyseres igen. Send biomarker_ids med de markører, der fejlede, så analyserer laboratoriet kun dem igen, og kittet sendes kun med de rør, der skal bruges til dem. Udelad feltet for at analysere hele panelet igen – det rigtige valg, når intet blev analyseret. Det kræver intet ekstra scope: At analysere markører igen, som patienten allerede har betalt for, er ikke et à la carte-valg. Disse markører kan ikke fjernes bagefter, fordi de udgør hele rekvisitionen.
Markører analyseres igen som panelets grupper, ikke én ad gangen. Angiver du én markør i en gruppe, analyseres hele gruppen igen, fordi der ikke kan afgives en laboratoriebestilling, der rapporterer mere, end der blev bedt om. En erstatning for en enkelt markør kan derfor komme tilbage med mere end ét resultat, og antallet af rør kan være større, end markørlisten antyder.
Der må kun være én erstatning pr. kit på vej ad gangen – mens en erstatning er pending eller dispatched, returnerer endnu en oprettelse for den samme ordre 409 med henvisning til den. Resultater kommer ind under erstatningens egen lab_code via dens egen Hent resultater. En erstatning er ikke måden at håndtere en pakke på, der aldrig nåede frem. Giv Aniva besked i stedet: Det er en genfremsendelse af den samme ordre under den samme laboratoriekode, ikke en ny ordre.

Opdatering af ordre på hjemmetestkit

Skift leveringsadressen, udskift panelet, opdater dine metadata, eller erstat e-mailadresserne til besked om resultater:
Medtag kun de felter, du vil ændre. panel_id erstatter det tilknyttede panel – med præcis ét panel pr. kit er et skift den eneste meningsfulde panelhandling, hvilket er grunden til, at der ikke findes endpoints til at tilføje eller fjerne paneler. Adressen og panelet kan kun ændres, mens ordren er pending; metadata kan opdateres i hele ordrens levetid. results_ready_emails kan opdateres, indtil ordren er cancelled.

Annullering af ordre på hjemmetestkit

Annuller en ordre på et hjemmetestkit, der ikke længere er brug for:
Dette sætter ordrens status til cancelled. Den annullerede ordre på hjemmetestkittet returneres i svaret. Kun en ordre med statussen pending kan annulleres. Fra dispatched og frem er kittet pakket og mærket – der findes ingen automatisk tilbagekaldelse – og kaldet returnerer 409. Hvis et kit, der allerede er afsendt, skal stoppes, skal du kontakte Aniva direkte. Annullering af en pending-ordre, hvis kit allerede er bestilt hos pakkeriet, annullerer det også der, og kaldet lykkes kun, hvis pakkeriet godkender det:
  • 409 – kittet var allerede pakket og mærket, så det kan ikke længere tilbagekaldes, selvom ordren stadig står som pending.
  • 502 – pakkeriet afviste annulleringen (fejlen indeholder deres begrundelse) eller kunne ikke nås. Intet blev ændret – ordren er stadig aktiv og kan annulleres igen.
En annullering, der returnerer en fejl, efterlader ordren præcis som den var, så en 200 er den eneste bekræftelse på, at der ikke kommer noget kit. Annullering af en ordre, der allerede er cancelled, returnerer den samme 200, uanset hvilken status den blev annulleret fra.

Aktivering af ordre på hjemmetestkit

Når patienten har taget sin prøve, indberetter du det:
Send activated_at – det tidspunkt, hvor patienten faktisk tog prøven, som et UTC-tidspunkt. Det er det prøvetagningstidspunkt, laboratorierapporten vil vise, så send det faktiske tidspunkt for prøvetagningen, ikke dit behandlingstidspunkt. Aktivering er en sluttilstand: Ordren skifter til activated og kan ikke længere annulleres eller ændres. Det svarer til Bekræft blodprøvetagning for hjemmetestkits, bare uden stregkode – kittets kode påføres, når kittet pakkes, så du behøver aldrig kende den. Ordren skal have sin lab_code på dette tidspunkt; en ordre uden returnerer 409. Aktiveringen er også det, der afgiver laboratoriebestillingen: Kittets panel bestilles hos laboratoriet under dets lab_code, så den returnerede prøve er ventet, og resultaterne tilknyttes, efterhånden som laboratoriet rapporterer dem. Dette kører efter svaret, og eventuelle problemer hos laboratoriet håndteres af Aniva i stedet for at blive vist på din forespørgsel.

Individuelle biomarkører

Du kan tilføje enkelte biomarkører til en ordre på et hjemmetestkit som à la carte-prøver uden for panelet. Det er nyttigt, når du ønsker et skræddersyet udvalg oven i kittet. De tilføjede biomarkører vises i svaret for ordren på hjemmetestkittet som et individual_biomarkers-array (på samme niveau som panels). Begge biomarkør-endpoints kræver capability-scopet home_kit_orders_individual_biomarker_selection ud over home_kit_orders_manage — hjemmetestkits bestilles pr. panel, så à la carte-markører aktiveres pr. partner. Spørg Aniva, hvis din integration har brug for det. Tilføj biomarkører (idempotent – allerede tilknyttede biomarkører beholdes):
Fjern biomarkører (idempotent — et ID, der ikke er tilknyttet, ignoreres):
Begge endpoints tager et biomarker_ids-array. Brug Vis biomarkører med home_kit=true for at finde biomarkør-ID’er. Biomarkører kan kun ændres, mens kittet er pending (se Livscyklus).

Hent laboratorieresultater

Når laboratoriet har behandlet den returnerede prøve, kan du hente kliniske og genetiske resultater:
Svaret indeholder planlagte tests (status planned) sammen med modtagne resultater, så du kan følge med i, hvad der stadig afventer. Resultater registreres under ordrens lab_code og kommer ind markør for markør, efterhånden som laboratoriet analyserer dem, så delvise payloads er normalt. Topniveaufeltet status er in_progress indtil den endelige rapport, derefter completed (eller fault, hvis alle laboratorieordrer fejlede uden at rapportere) — brug det til at afgøre, om laboratoriearbejdet for hjemmetestkitordren er færdigt. En home_kit_order.results.completed-webhook giver dig besked, når det sker, så du ikke behøver at polle. Laboratorierapporter som PDF er refereret i documents-arrayet — brug GET /api/v1/documents/{id} til at downloade dem.

Eksempel på hjemmetestkitordre