É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 avdestination.booked_by– hvem som skrev ut etiketten:anivaellerexternal. Bareaniva-forsendelser godtar Oppdater og Kanseller; enexternal-pakke spores i den samme listen, men returnerer501på begge.
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.
appointmentsoghome_kit_ordersviser 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 stemplersynced_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 avsenderenslocation_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.
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 medPATCH /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.
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 medDELETE /api/v1/shipments/{id}. Dette kaller logistikkleverandørens API for å kansellere bestillingen og oppdaterer statusen til cancelled.
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 returnerer409 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
Felteneorigin og destination i forsendelsessvaret inneholder oppslåtte adresseobjekter med følgende struktur:
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
Feltetpickup 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 enstatus_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.nullnår hendelsen ikke har noen status (opprettelse av etikett, en skanning uten informasjon fra transportøren, oppføringer registrert før feltet fantes). Aldricancelled– en kansellering er vår, ikke en hendelse fra transportøren.code– transportørens egen statuskode (GO! sineGO10,GO90,GOY001; DHLsVA,ZF,LA,ZU).nullnår transportøren ikke oppga noen. Stabil på tvers av språkoversettelser avstatus.detail_code– transportørens mer detaljerte kode der den finnes: DHLsstatusDetailed, f.eks.CNRFC_NRQRD_ZF(omdirigert til et postkontor),HLDCC_SERPT_LA(klar til henting der),DLVRD_SERPT_ZU(hentet).nullellers.status– transportørens lesbare tekst (f.eks."Shipment picked up","Die Sendung wurde abgeholt.").description– en forklaring av koden, eller transportørens lengre setning.nullnå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).
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:
pending til pasienten sender prøven – det er den reelle statusen, ikke et hull.