Kotitestipakkausten tilausten päätepisteet vaativat
home_kit_orders_view- (luku) tai
home_kit_orders_manage-käyttöoikeusalueen (kirjoitus). Aktivoi hyväksyy myös suppeamman
home_kit_orders_activate-käyttöoikeusalueen. Hae tulokset ja
Lähetä tulokset sähköpostilla vaativat lisäksi results_view-käyttöoikeusalueen — laboratoriotulokset
ja asiakirjat edellyttävät sitä aina.Kentät
Anivan automaattisesti luoma UUID. Käytä tätä tilauksen päivittämiseen, paneelin vaihtamiseen, aktivointiin,
peruuttamiseen ja tulosten hakemiseen.
Nykyinen elinkaaren tila. Jokin arvoista
pending, dispatched, activated tai cancelled. Katso
Elinkaari alla. Laboratoriotulosten valmistumisen tarkempi tila (in_progress vs. completed)
saadaan päätepisteestä Hae tulokset.Osoite, johon pakkaus postitetaan — jommassakummassa kahdesta muodosta: joko tunnettuun
testipisteeseen viittaava
{location_id} tai suorat osoitekentät (name, street, city, postal_code,
country_code; company_name / house_number / address_line_2 / state / phone / email
valinnaisia — sama sanasto kuin locations-API:ssa). Anna täsmälleen toinen — sijaintiviite
tai suora osoite, ei molempia.Packstation tai Postfiliale (vain Saksa): aseta
street-kenttään Packstation tai Postfiliale,
house_number-kenttään kolminumeroinen toimipistenumero ja address_line_2-kenttään vastaanottajan DHL
Postnummer (6–10 numeroa, välilyönnit sallitaan). Ilman Postnummer-numeroa pakettia ei voi varata.
Postfach-osoitteita ei tueta.Viimeisimmän päivityksen ISO 8601 -aikaleima. Null, jos kotitestipakkauksen tilausta ei ole koskaan päivitetty.
Potilaan täydellinen profiiliobjekti, upotettuna jokaiseen kotitestipakkauksen tilausvastaukseen.
Kotitestipakkauksen tilaukseen liitetty paneeli — aina täsmälleen yksi
{ panel_id, added_at } -merkintä,
koska kotitestipakkaus vastaa 1:1 fyysistä pakkaustuotetta. Tarkista panel_id-arvo
päätepisteestä Listaa paneelit.Kotitestipakkauksen tilaukseen paneelin ulkopuolelta liitetyt biomarkkerit. Jokainen merkintä on
{ biomarker_id, added_at }. Tarkista jokainen biomarker_id-arvo
päätepisteestä Listaa biomarkkerit parametrilla home_kit=true. Tavallisessa tilauksessa nämä ovat yksittäisiä lisätestejä
paneelin päälle; korvaavassa pakkauksessa ne ovat testit, jotka laboratorio
ajaa uudelleen.Kotitestipakkauksen tilaus, jonka tämä tilaus korvaa, kun kyseessä on korvaava pakkaus. Tavallisessa tilauksessa
null.Osoitteet pienin kirjaimin, joihin kuhunkin lähetetään yksi sähköposti, kun kaikki laboratoriotulokset ovat valmiit. Aina mukana —
tyhjä, kun pois käytöstä. Aseta päätepisteessä Luo tai
Päivitä. Katso
Tulokset valmiit -sähköpostit.
Omat avain-arvoparisi, jotka palautetaan sellaisinaan eikä Aniva koskaan tulkitse niitä. Aina mukana
luettaessa —
{}, jos et aseta yhtään. Enintään 20 avainta; avaimet vastaavat muotoa [A-Za-z0-9_-] ja ovat enintään 40
merkkiä pitkiä; arvot ovat merkkijonoja, numeroita tai totuusarvoja, merkkijonot enintään 500 merkkiä; yhteensä 16 384
tavua sarjoitettuna. Alkuosalla aniva_ alkavat avaimet on varattu.
Päivitä-kutsussa metadata yhdistetään: pois jättämäsi avaimet säilyvät,
arvolla null lähetetty avain poistetaan ja {} tyhjentää kaiken. Validointi on joko kaikki tai ei mitään. Älä koskaan laita
henkilö- tai kliinisiä tietoja metadata-kenttään — sitä ei käsitellä potilastietona.Laboratorion näytekoodi. Yksi koodi, kolme roolia: koodi, jonka alla laboratoriotulokset raportoidaan, joka on painettu
fyysiseen pakkaukseen ja jonka potilas lukee rasiasta aktivointikoodina. Myönnetään, kun
pakkaus pakataan —
null tilauksen ollessa tilassa pending, paitsi kun Aniva lähettää pakkauksen uudelleen (katso
Elinkaari). Aina vain luku -muodossa. Etsi käsissä olevaa pakkausta
vastaava tilaus kutsulla GET /api/v1/home-kit-orders?lab_code=….Päätepisteen Aktivoi kautta ilmoitettu näytteenottoaika — ajankohta, jolloin
potilas todellisuudessa otti näytteensä, UTC-aikana.
null, kunnes pakkaus on aktivoitu.
Tämä on laboratorioraportissa näkyvä näytteenottoaika.Tähän tilaukseen liitetyt paketit vanhimmasta liitoksesta alkaen, kukin muodossa
{ id, added_at } — potilaalle matkalla oleva pakkaus
ja seurattavalla palautuksella varustetuissa pakkauksissa takaisin laboratorioon matkalla oleva näyte, joka
ilmestyy heti pakettikorttien tulostuessa. Tyhjä tilauksen ollessa tilassa
pending, paitsi kun Aniva lähettää pakkauksen uudelleen. Lue
kaikkien pakettien täydet tiedot yhdellä kutsulla GET /api/v1/shipments?home_kit_order_id={id} — katso
Lähetykset.Elinkaari
Kotitestipakkausten tilauksilla on neljä elinkaaren tilaa:
Kun Aniva lähettää kadonneen pakkauksen uudelleen, tilaus palaa tilaan
pending, mutta säilyttää
koodinsa lab_code ja aiemmat pakettinsa kentässä shipments. Uudessa pakkauksessa on sama koodi.
Uuteen pakettiin laitetaan käyttämätön palautustarra. Vain Aniva tekee nämä kaksi siirtymää; API ei
tarjoa niitä. Kumpikin siirtymä lähettää webhookin home_kit_order.pending
tai home_kit_order.cancelled.
Kotitestipakkauksen tilauksen tilamalli on tarkoituksella karkea. Toimituksen etenemistä potilaalle
ja takaisin seurataan tilauksen lähetyksistä –
dispatched tarkoittaa, että
pakkauksella on lähetystarra ja laboratoriokoodi, ei sitä, että se on jo liikkeellä; lähtevän
lähetyksen status kertoo, onko se liikkunut. Laboratoriotulosten käsittely tapahtuu
laboratoriolähetteissä. Laboratoriotulosten valmistuminen (in_progress vs. completed) näkyy
Hae tulokset -kutsussa – ylätason status-kenttä on
in_progress, kunnes jokainen lähete sulkeutuu, ja sen jälkeen completed – tai fault, jos
jokainen lähete keskeytyi raportoimatta tuloksia.Pakettien seuranta
destination on
laboratorio), yhdistettynä kentällä paired_with. Palautuspaketti pysyy tilassa pending –
seurantakoodi on jo tiedossa – kunnes potilas postittaa sen. Suolistomikrobiomipakkaus tulee yhtenä
lähetyksenä: pakkaus potilaalle. Sen palautuskuori on valmiiksi maksettu ja seuraamaton, joten
paluumatkalle ei varata lähetystä. booked_by kertoo, kuka varasi lähetystarran: "aniva" tai
"external". Vain "aniva"-pakettia voi muokata täällä, ja lähetystarran tulostamisen jälkeen vain
sen notes-kenttää. Jokaisessa paketissa on kuljetusyhtiön täydet status_updates-tiedot, mukaan
lukien DHL:n detail_code postitoimipaikkaan ohjaamisesta.
Lähetyksen home_kit_orders listaa vain oman käyttöoikeuskontekstisi tilaukset. Katso
Käyttöoikeudet.
Kotitestipakkaustilausten listaaminen
Hae kaikki API-avaimellesi näkyvät kotitestipakkaustilaukset:?profile_id={uuid} suodattaaksesi tietyn profiilin mukaan tai
?lab_code={code} selvittääksesi käsillä olevan fyysisen pakkauksen tilauksen – tämä on aktivointiprosessin
luonteva ensimmäinen vaihe.
Kotitestipakkaustilauksen luominen
Tee kotitestipakkaustilaus potilasprofiilille:profile_id, delivery_address ja yksi panel_id. Tilaus luodaan tilassa pending.
Välitä valinnainen Idempotency-Key-otsikko, jotta uudelleenyritys ei tilaa toista pakkausta – katso Idempotenssi.
Tarkalleen yksi paneeli, koska kotitestipakkaus vastaa 1:1 fyysistä pakkaustuotetta – paneeli on pakkaus. Vain paneelit, jotka Aniva on määrittänyt kotitestipakkauksiksi, ovat tilattavissa; muut paneelit hylätään koodilla 422. Se vaaditaan luontivaiheessa, koska tilaus siirtyy heti pakkausjonoon ja pakkaaminen voi alkaa välittömästi. Kun tilaus on tilassa pending, voit vaihtaa paneelin Päivitä-kutsulla.
Jos haluat lähettää toisen pakkauksen sellaisen tilalle, josta ei saatu tuloksia, välitä replaces_home_kit_order_id paneelin valitsemisen sijaan – katso Korvaavat pakkaukset.
Korvaavat pakkaukset
Joskus pakkauksesta ei saada tuloksia: potilas ei saanut putkea täyteen, näytteessä oli saapuessa liian vähän materiaalia tai laboratorio ei pystynyt analysoimaan osaa siitä. Tilaa sille korvaava pakkaus:replaces_home_kit_order_id.
Korvattavaan tilaukseen ei kosketa. Se säilyttää tilansa, laboratoriokoodinsa ja kaikki sille jo kirjatut tulokset, joten jos potilas silti postittaa ensimmäisen pakkauksen, hän saa kaikki tulokset, jotka laboratorio pystyy siitä lukemaan.
Paneeli periytyy. Jätä panel_id pois, niin korvaava tilaus saa korvattavan tilauksen paneelin – sen potilas osti, ja sen mukaan paketti on brändätty. Lähetä eri paneeli vain koko paneelin korvaamista varten; paneeli ja biomarkkerien osajoukko yhdessä hylätään koodilla 422, koska osajoukko tarkoittaa oikeaa asiaa vain sen paneelin alla, josta se on valittu. Korvaavan tilauksen paneelia ei myöskään voi vaihtaa jälkikäteen.
Sinä valitset, mitä ajetaan uudelleen. Lähetä biomarker_ids-kentässä epäonnistuneet biomarkkerit, niin laboratorio analysoi vain ne uudelleen ja pakkauksessa lähetetään vain niihin tarvittavat putket. Jätä se pois, jos haluat ajaa koko paneelin uudelleen – tämä on oikea valinta, kun mitään ei saatu analysoitua. Tämä ei vaadi erillistä käyttöoikeutta: potilaan jo maksamien biomarkkerien uudelleenajo ei ole à la carte -valinta. Näitä biomarkkereita ei voi poistaa jälkikäteen, koska ne muodostavat koko lähetteen.
Biomarkkerit ajetaan uudelleen paneelin ryhminä, ei yksitellen. Yhden ryhmään kuuluvan
biomarkkerin nimeäminen ajaa koko ryhmän uudelleen, koska sellaista laboratoriotilausta ei voi
tehdä, joka raportoi enemmän kuin on tilattu. Yhden biomarkkerin korvaava tilaus voi siksi
palauttaa useamman tuloksen, ja putkien määrä voi olla suurempi kuin biomarkkerilista antaa
ymmärtää.
pending tai dispatched, toinen luontipyyntö samalle tilaukselle palauttaa virheen 409 ja nimeää kyseisen tilauksen. Tulokset saapuvat korvaavan tilauksen omalla koodilla lab_code sen oman Hae tulokset -kutsun kautta.
Korvaava tilaus ei ole oikea tapa hoitaa pakettia, joka ei koskaan saapunut perille. Kerro sen sijaan Anivalle: kyse on saman tilauksen uudelleenlähetyksestä samalla laboratoriokoodilla, ei uudesta tilauksesta.
Kotitestipakkaustilauksen päivittäminen
Muuta toimitusosoitetta, vaihda paneeli, päivitä metatiedot tai korvaa tulosten valmistumisesta ilmoittavat sähköpostiosoitteet:panel_id korvaa liitetyn paneelin – kun pakkauksessa on tarkalleen yksi paneeli, vaihto on ainoa mielekäs paneelitoiminto, minkä vuoksi paneelin lisäys- tai poistopäätepisteitä ei ole. Osoitetta ja paneelia voi muokata vain tilassa pending; metadata pysyy muokattavana koko tilauksen elinkaaren ajan. results_ready_emails pysyy muokattavana, kunnes tilaus on tilassa cancelled.
Kotitestipakkaustilauksen peruminen
Peru kotitestipakkaustilaus, jota ei enää tarvita:cancelled. Peruttu kotitestipakkaustilaus palautetaan vastauksessa.
Vain tilassa pending olevan tilauksen voi perua. Tilasta dispatched alkaen pakkaus on pakattu ja varustettu lähetystarralla – automaattista takaisinkutsua ei ole – ja kutsu palauttaa virheen 409. Jos jo lähetetty pakkaus pitää pysäyttää, ota suoraan yhteyttä Anivaan.
Jos perut pending-tilauksen, jonka pakkaus on jo tilattu logistiikkakumppanilta, se perutaan myös siellä, ja kutsu onnistuu vain, jos logistiikkakumppani hyväksyy peruutuksen:
409– pakkaus oli jo pakattu ja varustettu lähetystarralla, joten sitä ei voi enää kutsua takaisin, vaikka tilauksen tilana näkyy yhäpending.502– logistiikkakumppani hylkäsi peruutuksen (virhe sisältää heidän perustelunsa) tai siihen ei saatu yhteyttä. Mitään ei muutettu – tilaus on yhä voimassa ja sen voi perua uudelleen.
200 on ainoa vahvistus siitä, ettei pakkausta ole tulossa.
Jo tilassa cancelled olevan tilauksen peruminen palauttaa saman 200-vastauksen riippumatta siitä, mistä tilasta se peruttiin.
Kotitestipakkaustilauksen aktivointi
Kun potilas on ottanut näytteensä, ilmoita siitä:activated_at – hetki, jolloin potilas todellisuudessa otti näytteen, UTC-aikaleimana. Tämä on näytteenottoaika, joka tulee laboratorioraporttiin, joten lähetä todellinen näytteenottohetki, älä omaa käsittelyaikaasi. Aktivointi on lopullinen: tilaus siirtyy tilaan activated, eikä sitä voi enää perua tai muuttaa. Kotitestipakkauksen vastine Vahvista verinäytteenotto -kutsulle ilman viivakoodia – pakkauksen koodi kiinnitetään pakkaamisen yhteydessä, joten sinun ei tarvitse koskaan tietää sitä. Tilauksella on oltava lab_code siihen mennessä; tilaus ilman sitä palauttaa virheen 409.
Aktivointi tekee myös laboratoriotilauksen: pakkauksen paneeli tilataan laboratoriosta sen koodilla lab_code, jotta palautuvaa näytettä osataan odottaa ja tulokset liitetään tilaukseen laboratorion raportoidessa ne. Tämä ajetaan vastauksen jälkeen, ja laboratorion puolen ongelmat hoitaa Aniva sen sijaan, että ne näkyisivät pyynnössäsi.
Yksittäiset biomarkkerit
Voit liittää kotitestipakkaustilaukseen yksittäisiä biomarkkereita à la carte -testeinä paneelin ulkopuolelta. Tämä on hyödyllistä, kun haluat räätälöidyn valikoiman pakkauksen lisäksi. Liitetyt biomarkkerit näkyvät kotitestipakkaustilauksen vastauksessaindividual_biomarkers-taulukkona (panels-kentän rinnalla).
Molemmat biomarkkeripäätepisteet vaativat home_kit_orders_individual_biomarker_selection-oikeusalueen home_kit_orders_manage-oikeusalueen lisäksi — kotitestipakkaukset tilataan paneeleittain, joten yksittäiset markkerit otetaan käyttöön kumppanikohtaisesti. Kysy Anivalta, jos integraatiosi tarvitsee sitä.
Lisää biomarkkereita (idempotentti — jo liitetyt biomarkkerit säilytetään):
biomarker_ids-taulukon. Hae biomarkkerien ID:t Listaa biomarkkerit -päätepisteellä parametrilla home_kit=true. Biomarkkereita voi muuttaa vain, kun pakkaus on tilassa pending (katso Elinkaari).
Laboratoriotulosten hakeminen
Kun laboratorio on käsitellyt palautetun näytteen, hae kliiniset ja geneettiset tulokset:planned) saatujen tulosten ohella, joten voit seurata, mikä on vielä kesken. Tulokset kirjautuvat tilauksen lab_code-koodin alle ja saapuvat markkeri kerrallaan laboratorion analysoidessa niitä, joten osittaiset vastaukset ovat normaaleja. Ylätason status-kenttä on in_progress lopulliseen raporttiin asti ja sen jälkeen completed (tai fault, jos jokainen laboratoriotilaus epäonnistui raportoimatta) — päättele tästä, onko kotitestipakkaustilauksen laboratoriotyö valmis. home_kit_order.results.completed-webhook kertoo, kun näin tapahtuu, joten sinun ei tarvitse tehdä toistuvia kyselyjä. Laboratorioraporttien PDF-tiedostoihin viitataan documents-taulukossa — lataa ne kutsulla GET /api/v1/documents/{id}.