Siirry pääsisältöön
Lähetys on yksi fyysinen paketti: kuriirinouto, joka kuljettaa verinäytteet testipaikasta laboratorioon, kotitestipakkaus matkalla potilaalle tai näyte, jonka potilas postittaa takaisin. Shipments API antaa sinun luoda, seurata, muokata ja peruuttaa lähetystilauksia sekä listaa kaikki paketit samassa paikassa riippumatta siitä, kuka ne varasi.

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, luetaan destination-kentästä.
  • booked_by — kuka tulosti osoitekortin: aniva tai external. Vain aniva-lähetykset hyväksyvät kutsut Päivitä ja Peruuta; external-pakettia seurataan samalla listalla, mutta molemmat kutsut palauttavat koodin 501.
Paketti, jonka mukana lähetettiin palautusosoitekortti, ja paketti, jonka kyseinen osoitekortti tuo takaisin, viittaavat toisiinsa 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.
  • appointments ja home_kit_orders listaavat 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 kirjaa synced_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öpaikan location_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ä.
Molemmissa taulukoissa vanhin yhteys on ensin. Jokainen 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 kutsumalla PATCH /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ä.
Lähetyksiä ei voi muokata sen jälkeen, kun kuriiri on noutanut paketin. Yritys päivittää lähetys tilassa in_transit, delivered tai fault palauttaa 409 Conflict.
Jos logistiikkatoimittaja hylkää peruutuksen tai uudelleenluonnin päivityksen aikana, API palauttaa 502 Bad Gateway ja toimittajan virheilmoituksen.

Lähetysten peruminen

Peru lähetys kutsumalla DELETE /api/v1/shipments/{id}. Tämä kutsuu logistiikkatoimittajan rajapintaa tilauksen perumiseksi ja päivittää tilaksi cancelled.
Lähetyksiä ei voi perua noudon jälkeen. Yritys perua lähetys, joka on jo tilassa in_transit, delivered tai fault, palauttaa 409 Conflict. Jo tilassa cancelled olevan lähetyksen peruminen ei tee muutoksia ja palauttaa tilakoodin 200 lähetyksen kanssa — katso Idempotenssi.
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 palauttaa 409 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ähetysvastauksen origin- ja destination-kentät sisältävät selvitetyt osoiteoliot seuraavassa rakenteessa:
Vastaanoton paketissa 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ähetysvastauksen pickup-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ä on status_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 koskaan cancelled — peruutus on meidän, ei kuljetusyhtiön tapahtuma.
  • code — kuljetusyhtiön oma tilakoodi (GO!:n GO10, GO90, GOY001; DHL:n VA, ZF, LA, ZU). null, kun kuljetusyhtiö ei toimittanut koodia. Pysyy samana status-kentän kieliversioista riippumatta.
  • detail_code — kuljetusyhtiön tarkempi koodi, jos sellainen on: DHL:n statusDetailed, esim. CNRFC_NRQRD_ZF (ohjattu postitoimipaikkaan), HLDCC_SERPT_LA (noutovalmis siellä), DLVRD_SERPT_ZU (noudettu). Muulloin null.
  • 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).
Kun kuljetusyhtiö lähettää paketin takaisin lähettäjälle, aikajanaan tulee yksi merkintä, jonka 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:
Paluulähetyksen rivi on olemassa siitä hetkestä lähtien, kun palautustarra tulostetaan, ja pysyy tilassa pending, kunnes potilas postittaa näytteen — tämä on todellinen tila, ei puute.