Yksi lista, suodatettuna
GET /api/v1/shipments on ainoa kokoelma. Lähetys on itsenäinen — sillä on monesta moneen -suhde ajanvarauksiin, ja se voi kuulua kotitestipakkaustilaukseen — joten ylätason alle sisällytettyä listaa ei ole. Rajaa samaa listaa parametrilla ?appointment_id= tai ?home_kit_order_id=, sivuta se parametreilla limit / offset ja seuraa ylätason upotettua shipments-taulukkoa ({ id, added_at } sekä ajanvarauksissa että kotitestipakkaustilauksissa) kutsuun Hae lähetys, kun sinulla on yksi tunniste.
Sisältö ja varaaja
Jokaisessa lähetyksessä on kaksi tietoa, jotka eivät näy sen osoitteista:contents— vapaamuotoinen teksti paketin sisällöstä, joka asetetaan luonnin yhteydessä ("Medizinisch freigestellte Probe","Home test kit") ja näytetään kuriirille. Vain tiedoksi. Suunta ei ole oma kenttänsä: se, onko paketti menossa laboratorioon, luetaandestination-kentästä.booked_by— kuka tulosti osoitekortin:anivataiexternal. Vainaniva-lähetykset hyväksyvät kutsut Päivitä ja Peruuta;external-pakettia seurataan samalla listalla, mutta molemmat kutsut palauttavat koodin501.
paired_with-kentän kautta.
Käyttöoikeudet
- Voit lukea paketin tiedot, kun vähintään yksi siihen yhdistetty ajanvaraus tai kotitestipakkaustilaus kuuluu käyttöoikeusalueeseesi tai kun paketti lähti käyttöoikeusalueeseesi kuuluvasta toimipaikasta.
appointmentsjahome_kit_orderslistaavat vain käyttöoikeusalueeseesi kuuluvat ajanvaraukset ja tilaukset.- Kutsut Päivitä, Peruuta, Liitä ajanvarauksia ja Irrota ajanvarauksia edellyttävät, että jokainen yhdistetty kotitestipakkaustilaus kuuluu käyttöoikeusalueeseesi. Muutoin kutsu palauttaa koodin
403, ja vain Aniva voi muokata pakettia.
Lukupyynnöt eivät koskaan kutsu kuljetusyhtiötä
Jokainen lukupyyntö palvellaan tietokannastamme. Taustasynkronointi täsmäyttää jokaisen lähetyksen sen kuljetusyhtiön kanssa (GO! 10 minuutin välein, DHL tunnin välein) ja kirjaasynced_at-aikaleiman, joka kertoo vastauksen iän. Pakotettua päivitystä ei ole — DHL sallii yhden seurantakutsun viiden sekunnin välein, joten kuljetusyhtiölle asti menevää lukupyyntöä ei voida tarjota.
Lähetyksen luominen
Lähetystä luodessasi määrität lähtöpaikanlocation_id — testipaikan, josta kuriiri noutaa lähetyksen. Nimeät myös kohdelaboratorion kentällä destination_lab. Lähetys kuljetetaan kyseisen laboratorion rekisteröityyn toimitusosoitteeseen.
Toimipaikan on kuuluttava API-avaimesi käyttöoikeusalueeseen. Löydät käytettävissä olevat toimipaikkatunnisteet kutsulla Listaa toimipaikat.
Voit halutessasi välittää parametrin appointment_id yhdistääksesi lähetyksen tiettyyn ajanvaraukseen
luonnin yhteydessä. Yhteys näkyy upotettuna molemmilla puolilla:
- lähetyksessä
appointments-taulukkona, jossa on{ id, added_at }-merkintöjä; - ajanvarauksessa
shipments-taulukkona, jossa on{ id, added_at }-merkintöjä.
id viittaa varsinaiseen tietopäätepisteeseen
(Hae ajanvaraus /
Hae lähetys), josta saa täydet tiedot — kumppanit, jotka haluavat
seurata kuriirin etenemistä ajanvarauskohtaisesti, seuraavat kutakin ajanvarauksen shipments-taulukon merkintää
lähetyksen tietopäätepisteeseen.
Lähetys voidaan yhdistää useaan ajanvaraukseen, ja ajanvaraus voidaan yhdistää useaan
lähetykseen. Hallitse yhteyksiä luonnin jälkeen kutsuilla Liitä ajanvarauksia
lähetykseen /
Irrota ajanvarauksia lähetyksestä. Jokainen
muutos palauttaa lähetyksen päivitetyn ajanvarauslistan.
Muutossääntö on seuraava: yhteyksiä voi luoda tai poistaa, kun JOKO ajanvarauksen
verinäytteenotto on jo tehty (blood_drawn) tai lähetys on luotu alle 24 tuntia sitten. Tämän
aikaikkunan ulkopuolella yhteys on lukittu, jotta historiatiedot pysyvät muuttumattomina.
Elinkaari
Lähetykset etenevät seuraavien tilojen läpi:
Jokainen tilamuutos lähettää
shipment.*-webhookin, esimerkiksi
shipment.delivered. shipment.updated laukeaa jokaisesta luettavissa olevasta muutoksesta, kuten uudesta skannauksesta.
Noutoaikataulun säännöt
Seuraavat säännöt pätevät lähetyksen noutoaikataulua luotaessa tai päivitettäessä.pickup_date
(YYYY-MM-DD) ja pickup_time_from / pickup_time_till (HH:MM, 24 h) ovat paikallisia aikoja,
jotka tulkitaan lähtöpaikan IANA-aikavyöhykkeessä — et lähetä aikavyöhykettä niiden mukana.
Lähetysten muokkaaminen
Voit päivittää lähetyksen noutoaikataulun, pakettien määrän, painon ja muistiinpanot kutsumallaPATCH /api/v1/shipments/{id}. Jos jokin logistiikkaan vaikuttava kenttä muuttuu (noutopäivä, kellonaika, pakettien määrä tai paino), olemassa oleva kuljetustilaus perutaan automaattisesti ja luodaan uusi. Päivityspyynnöstä pois jättämäsi kentät säilyvät nykyisestä lähetyksestä — esimerkiksi pelkän weight-kentän päivittäminen luo tilauksen uudelleen samalla noutoaikataululla. Päivitetyt aikataulukentät validoidaan samoilla noutoaikataulun säännöillä.
Jos logistiikkatoimittaja hylkää peruutuksen tai uudelleenluonnin päivityksen aikana, API palauttaa 502 Bad Gateway ja toimittajan virheilmoituksen.
Lähetysten peruminen
Peru lähetys kutsumallaDELETE /api/v1/shipments/{id}. Tämä kutsuu logistiikkatoimittajan rajapintaa tilauksen perumiseksi ja päivittää tilaksi cancelled.
Logistiikkatoimittaja voi myös hylätä peruutuksen omista syistään (esim. peruutuksen takaraja on ohitettu). Tällöin API palauttaa 502 Bad Gateway sekä toimittajan virheilmoituksen ja virhekoodin.
Palautustarrat
DHL:n palautustarra on osa lähtevää tilausta. DHL ei voi perua tarraa erikseen, joten palautustarraa seuraavan rivin peruminen palauttaa409 Conflict. Peru sen sijaan lähtevä paketti, kun se on tilassa pending. Se peruu samalla myös tarran: jokainen lähtevän paketin tilassa pending oleva paluulähetyksen rivi siirtyy tilaan cancelled ja saa RETURN_LEG_CANCELLED-merkinnän status_updates-kenttäänsä. Palautuspaketti, jonka potilas on jo postittanut, jatkaa matkaansa. Kun lähtevä paketti on lähetetty, tarra pysyy voimassa ja Aniva sulkee paluulähetyksen rivin manuaalisesti.
Lähetysten viitetunnisteet
Jokaisella lähetyksellä on 11-merkkinen viitetunnus: kirjain, päivämäärä ja neljä merkkiä,{letter}YYMMDDXXXX (esimerkiksi P2611194821). Kirjain kertoo, mihin lähetys kuuluu, ei koskaan sen suuntaa:
Lähetys ajalta 20.–22. marraskuuta 2026 säilyttää tunnuksensa, jonka alussa on sana:
API, MAN, AUTO tai KIT (esimerkiksi AUTO261121UWKX). Molemmat muodot pysyvät voimassa. Älä tarkista tunnuksen pituutta tai ensimmäistä kirjainta. Käytä tunnusta lähetyksen hakemiseen, päivittämiseen tai peruuttamiseen.
Lähetyksen osoitteet
Lähetysvastauksenorigin- ja destination-kentät sisältävät selvitetyt osoiteoliot seuraavassa rakenteessa:
origin-osoite määräytyy luontihetkellä määrittämäsi testipaikan
perusteella ja destination on destination_lab-kentässä nimeämäsi laboratorio.
Kotitestipaketissa potilaan toimitusosoite on pakkauksen destination ja
näytteen palautuksen origin; pakkauksen pakkaava toimipiste on sen origin. Osoitteessa ei ole
location_id-kenttää — yhdistä vastaanoton paketti siihen linkitetyn ajanvarauksen
kautta.
Noutoikkuna
Lähetysvastauksenpickup-kenttä sisältää kuriirin sovitun noutoikkunan. Se
sisältää from- ja till-aikaleimat UTC-hetkinä (ISO 8601 Z-päätteellä, esim.
2026-04-15T07:00:00Z) sekä timezone-merkkijonon (noutopaikan IANA-aikavyöhyke).
Luonti- tai päivityshetkellä lähettämäsi paikallisaika pickup_date / pickup_time_* muunnetaan näiksi
absoluuttisiksi hetkiksi kyseisen aikavyöhykkeen avulla — käytä timezone-kenttää, kun muunnat from- ja till-arvot
takaisin noutopaikan paikallisaikaan. Kenttä on null, kun noutoikkunaa ei ole sovittu.
Tilapäivitysloki
Jokaisessa lähetyksessä onstatus_updates-taulukko — kaikki logistiikkatoimittajan
raportoimat elinkaaritapahtumat vanhimmasta uusimpaan. Jokainen merkintä sisältää:
state— tapahtuma lähetyksen tilasanastossa (pending,in_transit,delivered,fault), jotta voit lukea aikajanaa tuntematta kuljetusyhtiön koodeja.null, kun tapahtumalla ei ole tilaa (tarran luonti, kuljetusyhtiön skannaus ilman tietoja, merkinnät ajalta ennen kentän olemassaoloa). Ei koskaancancelled— peruutus on meidän, ei kuljetusyhtiön tapahtuma.code— kuljetusyhtiön oma tilakoodi (GO!:nGO10,GO90,GOY001; DHL:nVA,ZF,LA,ZU).null, kun kuljetusyhtiö ei toimittanut koodia. Pysyy samanastatus-kentän kieliversioista riippumatta.detail_code— kuljetusyhtiön tarkempi koodi, jos sellainen on: DHL:nstatusDetailed, esim.CNRFC_NRQRD_ZF(ohjattu postitoimipaikkaan),HLDCC_SERPT_LA(noutovalmis siellä),DLVRD_SERPT_ZU(noudettu). Muulloinnull.status— kuljetusyhtiön ihmiselle luettava tilateksti (esim."Shipment picked up","Die Sendung wurde abgeholt.").description— koodin selitys tai kuljetusyhtiön pidempi lause.null, kun kumpaakaan ei ole.location— skannauspaikka kuljetusyhtiön nimeämänä: GO!:n terminaali, DHL:n kaupunki. Vapaa teksti, ei koordinaatti.time— tapahtuman ISO 8601 -aikaleima kuljetusyhtiön ilmoittamana (aikavyöhyke-eroineen).
code
on RETURNED_TO_SENDER. Sen status sisältää kuljetusyhtiön syyn. Lähetys pysyy sen jälkeen tilassa fault myös
sen jälkeen, kun kuljetusyhtiö on toimittanut paketin takaisin meille.
Lista voi olla tyhjä, jos kuljetusyhtiö ei ole vielä raportoinut tapahtumia.
Käytä ylätason status-kenttää varsinaisena nykytilana. Se etenee yhteen suuntaan — tilasta pending
tilaan in_transit ja tilaan delivered — ja fault näkyy sen päällä niin kauan kuin uusin tapahtuma raportoi ongelman;
kuljetusyhtiöt eivät järjestä tapahtumiaan tärkeyden mukaan (DHL lisää pre-transit-koodatun ohjausilmoituksen
luovutusskannauksen jälkeen), joten pelkkä uusin merkintä ei kerro, missä vaiheessa paketti on.
Esimerkkilähetys
Esimerkki kotitestipaketeista
GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-… palauttaa potilaalle matkalla olevan pakkauksen ja takaisin matkalla olevan näytteen parina:
pending, kunnes potilas postittaa näytteen — tämä on todellinen tila, ei puute.