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
UUID automatisk generert av Aniva. Bruk denne for å oppdatere bestillingen, bytte panel, aktivere
den, kansellere den og hente resultater.
Gjeldende livssyklusstatus. En av
pending, dispatched, activated eller cancelled. Se
Livssyklus nedenfor. Detaljert ferdigstillelsesstatus for labresultater
(in_progress kontra completed) utledes fra Hent resultater.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.ISO 8601-tidsstempel for den siste oppdateringen. Null hvis bestillingen av hjemmetestsett aldri
har blitt oppdatert.
Det fullstendige profilobjektet for pasienten, innebygd i hvert svar for bestilling av hjemmetestsett.
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.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.Bestillingen av hjemmetestsett som denne erstatter, når det er et
erstatningssett.
null på en vanlig bestilling.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.
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.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=….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.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
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.
Liste opp bestillinger av hjemmetestsett
Hent alle bestillinger av hjemmetestsett som API-nøkkelen din har tilgang til:?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: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: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.
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: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: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 sompending.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.
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: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 enindividual_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):
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: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.