Hopp til hovedinnhold
En forsendelse er én fysisk pakke: en budhenting som frakter blodprøver fra et teststed til et laboratorium, settet på vei til en pasient med hjemmetestsett, eller prøven pasienten sender tilbake i posten. Shipments-API-et lar deg opprette, spore, endre og kansellere forsendelsesbestillinger, og viser alle pakker på ett sted uansett hvem som bestilte dem.

Én liste, filtrert

GET /api/v1/shipments er den eneste samlingen. En forsendelse står alene – den har en mange-til-mange-relasjon til timer og kan tilhøre en bestilling av hjemmetestsett – så det finnes ingen liste nøstet under et overordnet objekt. Begrens den samme listen med ?appointment_id= eller ?home_kit_order_id=, paginer den med limit / offset, og følg den innebygde shipments-listen på det overordnede objektet ({ id, added_at } på både timer og bestillinger av hjemmetestsett) til Hent forsendelse når du har én ID.

Innhold og hvem som bestilte den

Hver forsendelse har to opplysninger som ikke er synlige ut fra adressene:
  • contents – fritekst som beskriver hva som er i pakken, satt ved opprettelse ("Medizinisch freigestellte Probe", "Home test kit") og vist til budet. Kun til informasjon. Retning er ikke et eget felt: om en pakke er på vei til et laboratorium, leses av destination.
  • booked_by – hvem som skrev ut etiketten: aniva eller external. Bare aniva-forsendelser godtar Oppdater og Kanseller; en external-pakke spores i den samme listen, men returnerer 501 på begge.
En pakke som inneholdt en returetikett, og pakken som den etiketten sender tilbake, peker på hverandre via paired_with.

Tilgang

  • Du kan lese en pakke når minst én koblet time eller bestilling av hjemmetestsett er i tilgangskonteksten din, eller når den ble sendt fra et sted i tilgangskonteksten din.
  • appointments og home_kit_orders viser bare timene og bestillingene i tilgangskonteksten din.
  • Oppdater, Kanseller, Koble til timer og Koble fra timer krever at alle koblede bestillinger av hjemmetestsett er i tilgangskonteksten din. Ellers returnerer kallet 403, og bare Aniva kan endre pakken.

Lesinger kaller aldri transportøren

Hver lesing besvares fra databasen vår. En bakgrunnssynkronisering avstemmer hver forsendelse med transportøren (hvert 10. minutt for GO!, hver time for DHL) og stempler synced_at, som viser hvor gammelt svaret er. Det finnes ingen tvungen oppdatering – DHL tillater ett sporingskall hvert femte sekund, så en lesing som går direkte til transportøren, kan ikke tilbys.

Opprette en forsendelse

Når du oppretter en forsendelse, oppgir du avsenderens location_id – teststedet der budet skal hente pakken. Du oppgir også mottakerlaboratoriet med destination_lab. Forsendelsen sendes til det laboratoriets registrerte leveringsadresse. Stedet må være innenfor tilgangskonteksten til API-nøkkelen din. Bruk List opp steder for å finne tilgjengelige steds-ID-er. Du kan valgfritt sende med appointment_id for å koble forsendelsen til en bestemt time ved opprettelse. Koblingen vises innebygd på begge sider:
  • på forsendelsen, som en appointments-liste med { id, added_at }-elementer;
  • på timen, som en shipments-liste med { id, added_at }-elementer.
Begge listene har den eldste koblingen først. Hver id kryssrefererer til det kanoniske detaljendepunktet (Hent time / Hent forsendelse) for hele payloaden – partnere som ønsker budstatus per time, følger hvert element i timens shipments-liste til detaljendepunktet for forsendelsen. En forsendelse kan kobles til flere timer, og en time kan kobles til flere forsendelser. Etter opprettelse administrerer du koblingene med Koble timer til forsendelse / Koble timer fra forsendelse. Hver endring returnerer forsendelsens timeliste etter endringen. Regelen for endringer er: koblinger kan opprettes eller fjernes når ENTEN timen er forbi blodprøvetaking (blood_drawn), eller forsendelsen ble opprettet for mindre enn 24 timer siden. Utenfor det tidsvinduet er koblingen låst slik at historiske oppføringer forblir stabile.

Livssyklus

Forsendelser går gjennom følgende statuser:
Hver statusendring sender en shipment.*-webhook, for eksempel shipment.delivered. shipment.updated utløses ved hver endring du kan lese, som en ny skanning.

Regler for hentetidspunkt

Følgende regler gjelder når du oppretter eller oppdaterer hentetidspunktet for en forsendelse. pickup_date (YYYY-MM-DD) og pickup_time_from / pickup_time_till (HH:MM, 24-timers) er lokale klokkeslett tolket i avsenderstedets IANA-tidssone – du sender ikke med noen tidssone.

Endre forsendelser

Du kan oppdatere hentetidspunkt, antall pakker, vekt og notater for en forsendelse med PATCH /api/v1/shipments/{id}. Hvis logistikkrelevante felt endres (hentedato, tidspunkt, antall pakker eller vekt), blir den eksisterende logistikkbestillingen automatisk kansellert og en ny opprettet. Felt du utelater fra oppdateringsforespørselen, beholdes fra den eksisterende forsendelsen – hvis du for eksempel bare oppdaterer weight, opprettes bestillingen på nytt med samme hentetidspunkt. Oppdaterte tidsfelt valideres mot de samme reglene for hentetidspunkt.
Forsendelser kan ikke endres etter at budet har hentet pakken. Forsøk på å oppdatere en forsendelse med status in_transit, delivered eller fault returnerer 409 Conflict.
Hvis logistikkleverandøren avviser kanselleringen eller nyopprettingen under en oppdatering, returnerer API-et 502 Bad Gateway med leverandørens feilmelding.

Kansellere forsendelser

Kanseller en forsendelse med DELETE /api/v1/shipments/{id}. Dette kaller logistikkleverandørens API for å kansellere bestillingen og oppdaterer statusen til cancelled.
Forsendelser kan ikke kanselleres etter henting. Forsøk på å kansellere en forsendelse som allerede er in_transit, delivered eller fault, returnerer 409 Conflict. Å kansellere en som allerede er cancelled, gjør ingenting og returnerer 200 med forsendelsen – se Idempotens.
Logistikkleverandøren kan også avvise kanselleringen av egne grunner (f.eks. at fristen for kansellering har gått ut). I så fall returnerer API-et 502 Bad Gateway med leverandørens feilmelding og feilkode.

Returetiketter

En DHL-returetikett er en del av den utgående bestillingen. DHL kan ikke kansellere etiketten alene, så å kansellere raden som sporer en returetikett returnerer 409 Conflict. Kanseller heller den utgående pakken mens den er pending. Da kanselleres etiketten samtidig: hver pending-returrad for den utgående pakken blir cancelled og får en RETURN_LEG_CANCELLED-oppføring i status_updates. En returpakke som pasienten allerede har sendt, fortsetter som normalt. Etter at den utgående pakken er sendt, forblir etiketten gyldig, og Aniva lukker returraden manuelt.

Referanse-ID-er for forsendelser

Hver forsendelse har en referanse-ID på 11 tegn: en bokstav, datoen og fire tegn, {letter}YYMMDDXXXX (for eksempel P2611194821). Bokstaven viser hva forsendelsen tilhører, aldri retningen: En forsendelse fra 20. til 22. november 2026 beholder ID-en sin med et ord foran: API, MAN, AUTO eller KIT (for eksempel AUTO261121UWKX). Begge formatene forblir gyldige. Ikke sjekk lengden eller den første bokstaven i en ID. Bruk ID-en til å hente, oppdatere eller kansellere forsendelsen.

Forsendelsesadresser

Feltene origin og destination i forsendelsessvaret inneholder oppslåtte adresseobjekter med følgende struktur:
For en praksispakke hentes origin-adressen fra teststedet du oppga ved opprettelsen, og destination er laboratoriet du oppga i destination_lab. For en hjemmetestpakke er pasientens leveringsadresse destination for testsettet og origin for returen av prøven; stedet som pakker testsettet, er origin for det. Adressen har ingen location_id – koble en praksispakke gjennom timen den er knyttet til.

Hentevindu

Feltet pickup i forsendelsessvaret inneholder det planlagte hentevinduet for budet. Det inneholder tidsstemplene from og till som UTC-tidspunkter (ISO 8601 med Z-suffiks, f.eks. 2026-04-15T07:00:00Z) og en timezone-streng (hentestedets IANA-tidssone). De lokale klokkeslettene i pickup_date / pickup_time_* du sendte ved opprettelse / oppdatering, konverteres til disse absolutte tidspunktene med den tidssonen – bruk timezone for å vise from / till tilbake i hentestedets lokale klokketid. Feltet er null når det ikke er planlagt noe hentevindu.

Logg over statusoppdateringer

Hver forsendelse har en status_updates-liste – alle livssyklushendelser logistikkleverandøren har rapportert, med den eldste først. Hver oppføring inneholder:
  • state – hendelsen i statusvokabularet for forsendelser (pending, in_transit, delivered, fault), slik at du kan lese en tidslinje uten å kjenne transportørens koder. null når hendelsen ikke har noen status (opprettelse av etikett, en skanning uten informasjon fra transportøren, oppføringer registrert før feltet fantes). Aldri cancelled – en kansellering er vår, ikke en hendelse fra transportøren.
  • code – transportørens egen statuskode (GO! sine GO10, GO90, GOY001; DHLs VA, ZF, LA, ZU). null når transportøren ikke oppga noen. Stabil på tvers av språkoversettelser av status.
  • detail_code – transportørens mer detaljerte kode der den finnes: DHLs statusDetailed, f.eks. CNRFC_NRQRD_ZF (omdirigert til et postkontor), HLDCC_SERPT_LA (klar til henting der), DLVRD_SERPT_ZU (hentet). null ellers.
  • status – transportørens lesbare tekst (f.eks. "Shipment picked up", "Die Sendung wurde abgeholt.").
  • description – en forklaring av koden, eller transportørens lengre setning. null når ingen av delene finnes.
  • location – hvor skanningen skjedde, slik transportøren navngir det: et GO!-depot, en DHL-by. Fri tekst, ikke et koordinat.
  • time – ISO 8601-tidsstempel for hendelsen, slik det rapporteres av transportøren (med tidssoneforskyvning).
Når transportøren sender pakken tilbake til avsenderen, får tidslinjen én oppføring med code RETURNED_TO_SENDER. status inneholder transportørens begrunnelse. Forsendelsen forblir da fault, også etter at transportøren leverer pakken tilbake til oss. Listen kan være tom hvis transportøren ikke har rapportert noen hendelser ennå. Bruk toppnivåfeltet status for den gjeldende hovedstatusen. Den beveger seg én vei – pending til in_transit til delivered – med fault lagt over så lenge den nyeste hendelsen rapporterer en feil; transportører sorterer ikke hendelsene etter betydning (DHL legger til en pre-transit-kodet omdirigeringsmelding etter overleveringsskanningen), så den nyeste oppføringen alene sier ikke hvor en pakke befinner seg.

Eksempel på forsendelse

Eksempel på hjemmetestpakker

GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-… returnerer testsettet på vei til pasienten og prøven på vei tilbake, som et par:
Returraden finnes fra det øyeblikket returetiketten skrives ut, og forblir pending til pasienten sender prøven – det er den reelle statusen, ikke et hull.