Hopp til hovedinnhold
En bestilling av hjemmetestsett sender et testsett for egenprøvetaking i posten til en pasient. Aniva sender settet, pasienten tar prøven selv hjemme og sender den tilbake i posten. Dette skiller seg fra en time, som er en venøs blodprøvetaking utført på et fysisk teststed av helsepersonell.
Endepunkter for bestilling av hjemmetestsett krever tilgangsomfanget home_kit_orders_view (lesing) eller home_kit_orders_manage (skriving). Aktiver godtar også det snevrere tilgangsomfanget home_kit_orders_activate. Hent resultater og Send resultater på e-post krever i tillegg results_view — labresultater og dokumenter er alltid beskyttet av det.

Felter

string
påkrevd
UUID automatisk generert av Aniva. Bruk denne for å oppdatere bestillingen, bytte panel, aktivere den, kansellere den og hente resultater.
string
påkrevd
UUID-en til profilen denne bestillingen av hjemmetestsett tilhører.
string
påkrevd
Gjeldende livssyklusstatus. En av pending, dispatched, activated eller cancelled. Se Livssyklus nedenfor. Detaljert ferdigstillelsesstatus for labresultater (in_progress kontra completed) utledes fra Hent resultater.
object
påkrevd
Adressen settet skal sendes til — ett av to formater: enten {location_id} som refererer til et kjent teststed, eller de direkte adressefeltene (name, street, city, postal_code, country_code; company_name / house_number / address_line_2 / state / phone / email er valgfrie — samme feltnavn som i locations-API-et). Oppgi nøyaktig én — en stedsreferanse eller en direkte adresse, ikke begge.
Packstation eller Postfiliale (kun Tyskland): sett street til Packstation eller Postfiliale, house_number til det tresifrede stasjonsnummeret, og address_line_2 til mottakerens DHL Postnummer (6–10 sifre, mellomrom er tillatt). Uten Postnummer kan ikke pakken bestilles. Postfach støttes ikke.
string
påkrevd
ISO 8601-tidsstempel for når bestillingen av hjemmetestsett ble opprettet.
string
ISO 8601-tidsstempel for den siste oppdateringen. Null hvis bestillingen av hjemmetestsett aldri har blitt oppdatert.
object
Det fullstendige profilobjektet for pasienten, innebygd i hvert svar for bestilling av hjemmetestsett.
object[]
Panelet knyttet til bestillingen av hjemmetestsett — alltid nøyaktig én oppføring med { panel_id, added_at }, fordi et hjemmetestsett tilsvarer 1:1 et fysisk testsettprodukt. Kryssreferer panel_id mot List opp paneler.
object[]
Biomarkører knyttet til bestillingen av hjemmetestsett utenom panelet. Hver oppføring er { biomarker_id, added_at }. Kryssreferer hver biomarker_id mot List opp biomarkører med home_kit=true. På en vanlig bestilling er dette enkelttester i tillegg til panelet; på et erstatningssett er de det laboratoriet analyserer på nytt.
string
Bestillingen av hjemmetestsett som denne erstatter, når det er et erstatningssett. null på en vanlig bestilling.
string
Hvorfor erstatningen ble sendt, i én setning. null på en vanlig bestilling.
string[]
Adresser som hver får én e-post når alle labresultater er endelige, i små bokstaver. Alltid til stede — tom når den er av. Angi den ved Opprett eller Oppdater. Se E-poster når resultater er klare.
object
Dine egne nøkkel/verdi-par, returnert uendret og aldri tolket av Aniva. Alltid til stede ved lesing — {} når du ikke angir noen. Maksimalt 20 nøkler; nøkler må matche [A-Za-z0-9_-] og være på maksimalt 40 tegn; verdier er en streng, et tall eller en boolsk verdi, med strenger på maksimalt 500 tegn; 16 384 byte serialisert totalt. Nøkler som begynner med aniva_ er reservert. Ved Oppdater blir metadata slått sammen: nøkler du utelater beholdes, en nøkkel sendt som null slettes, og {} tømmer alt. Valideringen er alt-eller-ingenting. Legg aldri inn personopplysninger eller kliniske data i metadata — det behandles ikke som pasientdata.
string
Laboratoriets prøvekode. Én kode, tre roller: koden labresultater rapporteres under, det som står trykt på det fysiske settet, og det pasienten leser av esken som aktiveringskode. Tildeles når settet pakkes — null mens bestillingen er pending, unntatt etter at Aniva sender et sett på nytt (se Livssyklus). Alltid skrivebeskyttet. Finn bestillingen til et sett du har for hånd med GET /api/v1/home-kit-orders?lab_code=….
string
Tidspunktet for prøvetaking rapportert via Aktiver — når pasienten faktisk tok prøven, som et UTC-tidspunkt. null frem til settet aktiveres. Dette er prøvetakingstidspunktet som står i labrapporten.
object[]
Pakkene knyttet til denne bestillingen, eldste tilknytning først, hver med { id, added_at } — settet på vei til pasienten og, for sett der returforsendelsen spores, prøven på vei tilbake til laboratoriet, som dukker opp i det øyeblikket etikettene skrives ut. Tom mens bestillingen er pending, unntatt etter at Aniva sender et sett på nytt. Les alle pakkene i ett kall med GET /api/v1/shipments?home_kit_order_id={id} — se Forsendelser.

Livssyklus

Bestillinger av hjemmetestsett har fire livssyklustilstander:
Når Aniva sender et tapt sett på nytt, går bestillingen tilbake til pending, men beholder sin lab_code og sine tidligere pakker i shipments. Det nye settet har den samme koden. En ubrukt returetikett legges i den nye esken. Bare Aniva gjør disse to endringene; API-et tilbyr dem ikke. Hver endring sender en home_kit_order.pending- eller home_kit_order.cancelled-webhook.
Statusene for bestilling av hjemmetestsett er med vilje overordnede. Leveringsstatus til og fra pasienten spores på bestillingens forsendelser – dispatched betyr at settet har en etikett og en labkode, ikke at det har beveget seg; det viser status på den utgående forsendelsen. Behandlingen av laboratorieresultatene ligger på innsendingene. Ferdigstillelsen av laboratorieresultatene (in_progress vs. completed) eksponeres via Hent resultater – status-feltet på øverste nivå er in_progress til alle innsendinger er avsluttet, deretter completed – eller fault når alle innsendinger feilet uten å rapportere.

Spore pakkene

Hva som returneres, avhenger av settet. Et blodprøvesett kommer som to forsendelser når Aniva har pakket det: pakken fra Aniva til pasienten, og pakken fra pasienten til laboratoriet (destination er laboratoriet), koblet sammen via paired_with. Returpakken står som pending – med sporingsnummeret allerede klart – til pasienten sender den. Et tarmmikrobiomsett kommer som én forsendelse: settet til pasienten. Returkonvolutten er forhåndsbetalt og uten sporing, så ingenting bestilles for returen. booked_by viser hvem som bestilte etiketten: "aniva" eller "external". Bare en "aniva"-pakke kan endres her, og bare notes-feltet etter at etiketten er skrevet ut. Hver pakke inneholder transportørens fullstendige status_updates, inkludert DHLs detail_code ved omdirigering til et postkontor. home_kit_orders på forsendelsen viser bare bestillingene i din tilgangskontekst. Se Tilgang.
Sammensetningen i en bestilling av hjemmetestsett kan bare endres mens den er pending. Når bestillingen er dispatched (eller senere – activated/cancelled), returnerer bytte av panel og /biomarkers-endepunktene 409 Conflict: det fysiske settet pakkes ut fra det valgte panelet, så innholdet er låst i det øyeblikket det sendes til pasienten. Hvis du likevel må endre testene på en bestilling som allerede er låst, ta kontakt med Aniva direkte – det er vanligvis fortsatt mulig, og vi gjør endringen for deg slik at innholdet i settet stemmer. Hvis settet allerede er brukt og ikke kunne gi resultater, bestill et erstatningssett i stedet.

Liste opp bestillinger av hjemmetestsett

Hent alle bestillinger av hjemmetestsett som API-nøkkelen din har tilgang til:
Du kan valgfritt sende ?profile_id={uuid} for å filtrere på en bestemt profil, eller ?lab_code={code} for å finne bestillingen som hører til et fysisk sett du har i hånden – det naturlige første steget i en aktiveringsflyt.

Opprette en bestilling av hjemmetestsett

Bestill et hjemmetestsett for en pasientprofil:
Send profile_id, en delivery_address og én enkelt panel_id. Bestillingen opprettes med statusen pending. Send en valgfri Idempotency-Key-header slik at et nytt forsøk ikke bestiller et ekstra sett – se Idempotens. Nøyaktig ett panel, fordi et hjemmetestsett tilsvarer et fysisk settprodukt 1:1 – panelet er settet. Bare paneler som Aniva har konfigurert som hjemmetestsett kan bestilles; alle andre paneler avvises med 422. Det må oppgis ved opprettelse fordi bestillingen går rett i pakkekøen og pakkingen kan starte umiddelbart. Så lenge bestillingen er pending, kan du bytte panel via Oppdater. For å sende et nytt sett for et som ikke kunne gi resultater, sender du replaces_home_kit_order_id i stedet for å velge et panel – se Erstatningssett.

Erstatningssett

Noen ganger kan et sett ikke gi resultater: pasienten fikk ikke fylt røret, prøven kom frem med for lite materiale, laboratoriet kunne ikke analysere deler av den. Bestill en erstatning for det:
En erstatning er en ny bestilling med ny labkode, også når det første settet aldri ble aktivert: laboratoriet trenger en ny rekvisisjon, og to prøver med samme kode kan ikke skilles fra hverandre. Begge bestillingene forblir lesbare, koblet sammen via replaces_home_kit_order_id. Bestillingen du erstatter blir ikke berørt. Den beholder sin status, sin labkode og eventuelle resultater som allerede er registrert på den, slik at en pasient som likevel sender inn det første settet får det laboratoriet klarer å lese ut av det. Panelet arves. Utelat panel_id, så får erstatningen panelet fra bestillingen den erstatter – det er det pasienten kjøpte og slik esken er merket. Send et annet panel bare når hele panelet skal erstattes; et panel og et utvalg markører sammen avvises med 422, fordi et utvalg bare gir mening innenfor panelet det ble valgt fra. Panelet på en erstatning kan heller ikke byttes i etterkant. Du velger hva som kjøres på nytt. Send biomarker_ids med markørene som feilet, så kjører laboratoriet bare dem på nytt, og settet sendes bare med rørene de krever. Utelat feltet for å kjøre hele panelet på nytt – det riktige valget når ingenting ble analysert i det hele tatt. Dette krever ikke noe ekstra scope: å kjøre markører pasienten allerede har betalt for på nytt er ikke et à la carte-valg. Disse markørene kan ikke fjernes i etterkant, fordi de utgjør hele rekvisisjonen.
Markører kjøres på nytt som panelets grupper, ikke én og én. Oppgir du én markør i en gruppe, kjøres hele den gruppen på nytt, fordi det ikke er mulig å legge inn en laboratoriebestilling som rapporterer mer enn det som ble bestilt. En erstatning for én enkelt markør kan derfor komme tilbake med mer enn ett resultat, og antall rør kan være høyere enn markørlisten antyder.
Bare én erstatning per sett kan være på vei om gangen – mens en erstatning er pending eller dispatched, returnerer et nytt opprettelsesforsøk for samme bestilling 409 med referanse til den. Resultatene kommer inn under erstatningens egen lab_code, via dens egen Hent resultater. En erstatning er ikke måten å håndtere en pakke som aldri kom frem. Gi heller beskjed til Aniva: da sendes den samme bestillingen på nytt under samme labkode, ikke som en ny bestilling.

Oppdatere en bestilling av hjemmetestsett

Endre leveringsadressen, bytt panelet, oppdater metadataene dine eller erstatt e-postadressene for resultatvarsler:
Ta bare med feltene du vil endre. panel_id erstatter det tilknyttede panelet – med nøyaktig ett panel per sett er et bytte den eneste meningsfulle paneloperasjonen, og derfor finnes det ingen endepunkter for å legge til eller fjerne paneler. Adressen og panelet kan bare endres mens statusen er pending; metadata kan skrives til gjennom hele bestillingens levetid. results_ready_emails kan skrives til helt til bestillingen blir cancelled.

Kansellere en bestilling av hjemmetestsett

Kanseller en bestilling av hjemmetestsett som ikke lenger trengs:
Dette setter statusen på bestillingen av hjemmetestsett til cancelled. Den kansellerte bestillingen returneres i svaret. Bare en bestilling med status pending kan kanselleres. Fra og med dispatched er settet pakket og merket – det finnes ingen automatisk tilbakekalling – og kallet returnerer 409. Hvis et sett som allerede er sendt må stoppes, ta kontakt med Aniva direkte. Når du kansellerer en pending-bestilling der settet allerede er bestilt fra lageret, kanselleres det der også, og kallet lykkes bare hvis lageret godtar det:
  • 409 – settet er allerede pakket og merket, så det kan ikke lenger kalles tilbake, selv om bestillingen fortsatt står som pending.
  • 502 – lageret avviste kanselleringen (feilen inneholder begrunnelsen deres), eller kunne ikke nås. Ingenting ble endret – bestillingen er fortsatt aktiv og kan kanselleres på nytt.
En kansellering som returnerer en feil lar bestillingen stå nøyaktig slik den var, så 200 er den eneste bekreftelsen på at det ikke kommer noe sett. Å kansellere en bestilling som allerede er cancelled returnerer samme 200, uansett hvilken status den ble kansellert fra.

Aktivere en bestilling av hjemmetestsett

Når pasienten har tatt prøven, rapporterer du det:
Send activated_at – tidspunktet da pasienten faktisk tok prøven, som et UTC-tidspunkt. Dette er prøvetakingstidspunktet som vil stå på laboratorierapporten, så send det faktiske tidspunktet for prøvetakingen, ikke ditt eget behandlingstidspunkt. Aktivering er endelig: bestillingen går til activated og kan ikke lenger kanselleres eller endres. Hjemmetestsettets motstykke til Bekreft blodprøvetaking, uten strekkode – settets kode påføres når settet pakkes, så du trenger aldri å kjenne til den. Bestillingen må ha fått sin lab_code innen da; en bestilling uten en slik kode returnerer 409. Aktivering er også det som legger inn laboratoriebestillingen: settets panel bestilles hos laboratoriet under sin lab_code, slik at den returnerte prøven forventes og resultatene kobles til etter hvert som laboratoriet rapporterer dem. Dette kjører etter at svaret er sendt, og et problem på laboratoriesiden håndteres av Aniva i stedet for å returneres på forespørselen din.

Individuelle biomarkører

Du kan legge til enkeltstående biomarkører på en bestilling av hjemmetestsett som à la carte-tester, utenfor panelet. Dette er nyttig når du ønsker et skreddersydd utvalg i tillegg til settet. De tilknyttede biomarkørene vises i svaret for bestillingen av hjemmetestsett som en individual_biomarkers-array (på samme nivå som panels). Begge biomarkørendepunktene krever tilgangsomfanget home_kit_orders_individual_biomarker_selection i tillegg til home_kit_orders_manage — hjemmetestsett bestilles per panel, så enkeltmarkører aktiveres per partner. Spør Aniva hvis integrasjonen din trenger det. Legg til biomarkører (idempotent – biomarkører som allerede er tilknyttet, beholdes):
Fjern biomarkører (idempotent — en ID som ikke er tilknyttet, ignoreres):
Begge endepunktene tar en biomarker_ids-liste. Bruk List opp biomarkører med home_kit=true for å finne biomarkør-ID-er. Biomarkører kan bare endres mens settet er pending (se Livssyklus).

Hente labresultater

Når laboratoriet har behandlet den returnerte prøven, henter du kliniske og genetiske resultater:
Svaret inkluderer planlagte tester (status planned) sammen med mottatte resultater, slik at du kan følge med på hva som fortsatt venter. Resultatene registreres under bestillingens lab_code og kommer inn markør for markør etter hvert som laboratoriet analyserer dem, så delvise svar er normalt. Feltet status på toppnivå er in_progress frem til sluttrapporten, og deretter completed (eller fault hvis alle laboratoriebestillinger feilet uten å rapportere) — bruk dette for å avgjøre om laboratoriearbeidet for bestillingen av hjemmetestsettet er ferdig. En home_kit_order.results.completed-webhook gir deg beskjed når det skjer, slik at du slipper å polle. PDF-er med laboratorierapporter refereres i documents-listen — bruk GET /api/v1/documents/{id} for å laste dem ned.

Eksempel på bestilling av hjemmetestsett