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
UUID automatisk genereret af Aniva. Brug dette til at opdatere bestillingen, skifte panelet,
aktivere den, annullere den og hente resultater.
Aktuel livscyklusstatus. En af
pending, dispatched, activated eller cancelled. Se
Livscyklus nedenfor. Detaljeret status for laboratorieresultater (in_progress vs.
completed) udledes fra Hent resultater.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.ISO 8601-tidsstempel for den seneste opdatering. Null, hvis bestillingen af hjemmetestkit aldrig
er blevet opdateret.
Det fulde profilobjekt for patienten, indlejret i hvert svar på en bestilling af hjemmetestkit.
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.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.Den bestilling af hjemmetestkit, som denne erstatter, når det er et
erstatningskit.
null på en almindelig bestilling.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.
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.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=….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.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
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.
Liste over ordrer på hjemmetestkits
Hent alle ordrer på hjemmetestkits, som din API-nøgle har adgang til:?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: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: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.
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: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: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 sompending.502– pakkeriet afviste annulleringen (fejlen indeholder deres begrundelse) eller kunne ikke nås. Intet blev ændret – ordren er stadig aktiv og kan annulleres igen.
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: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 etindividual_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):
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: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.