Én liste, filtreret
GET /api/v1/shipments er den eneste samling. En forsendelse står alene — den har et mange-til-mange-forhold til tider og kan tilhøre en hjemmetestkitordre — så der findes ingen liste indlejret under et overordnet objekt. Indsnævr den samme liste med ?appointment_id= eller ?home_kit_order_id=, paginer den med limit / offset, og følg et overordnet objekts inline shipments-array ({ id, added_at } på både tider og hjemmetestkitordrer) til Hent forsendelse, når du har ét id.
Indhold, og hvem der bookede den
Hver forsendelse indeholder to oplysninger, som ikke fremgår af adresserne:contents— fritekst, der beskriver, hvad der er i pakken, angivet ved oprettelse ("Medizinisch freigestellte Probe","Home test kit") og vist til kureren. Kun til information. Retning er ikke et felt: om en pakke er på vej til et laboratorium, aflæses afdestination.booked_by— hvem der udskrev labelen:anivaellerexternal. Kunaniva-forsendelser accepterer Opdater og Annuller; enexternal-pakke spores i den samme liste, men returnerer501på begge.
paired_with.
Adgang
- Du kan læse en pakke, når mindst én tilknyttet tid eller hjemmetestkitordre er i din adgangskontekst, eller når den blev afsendt fra en lokation i din adgangskontekst.
appointmentsoghome_kit_ordersviser kun de tider og ordrer, der er i din adgangskontekst.- Opdater, Annuller, Tilknyt tider og Fjern tider kræver, at alle tilknyttede hjemmetestkitordrer er i din adgangskontekst. Ellers returnerer kaldet
403, og kun Aniva kan ændre pakken.
Læsninger kalder aldrig fragtfirmaet
Hver læsning besvares fra vores database. En baggrundssynkronisering afstemmer hver forsendelse med fragtfirmaet (hvert 10. minut for GO!, hver time for DHL) og sættersynced_at, som viser, hvor gammelt et svar er. Der findes ingen tvungen opdatering — DHL tillader ét sporingskald hvert femte sekund, så en læsning, der kaldte fragtfirmaet direkte, kan ikke tilbydes.
Opret en forsendelse
Når du opretter en forsendelse, angiver du oprindelsenslocation_id — den testlokation, hvor kureren skal afhente. Du angiver også destinationslaboratoriet med destination_lab. Forsendelsen sendes til det pågældende laboratoriums registrerede forsendelsesadresse.
Lokationen skal være inden for din API-nøgles adgangskontekst. Brug Vis lokationer til at finde tilgængelige lokations-id’er.
Du kan valgfrit sende appointment_id med for at knytte forsendelsen til en bestemt tid ved
oprettelse. Tilknytningen vises inline på begge sider:
- på forsendelsen som et
appointments-array med{ id, added_at }-elementer; - på tiden som et
shipments-array med{ id, added_at }-elementer.
id krydsrefererer til det kanoniske detaljeendpoint
(Hent tid /
Hent forsendelse) for den fulde payload — partnere, der ønsker
kurerstatus pr. tid, følger hvert element i tidens shipments-array til
forsendelsens detaljeendpoint.
En forsendelse kan være knyttet til flere tider, og en tid kan være knyttet til flere
forsendelser. Efter oprettelse administrerer du tilknytningen med Tilknyt tider til
forsendelse /
Fjern tider fra forsendelse. Hver
ændring returnerer forsendelsens opdaterede liste over tider.
Reglen for ændringer er: tilknytninger kan oprettes eller fjernes, når ENTEN tiden er efter
blodprøvetagning (blood_drawn), eller forsendelsen blev oprettet for mindre end 24 timer siden. Uden for det
vindue er tilknytningen låst, så historiske data forbliver stabile.
Livscyklus
Forsendelser gennemgår følgende statusser:
Hver statusændring sender en
shipment.*-webhook, for eksempel
shipment.delivered. shipment.updated udløses ved hver ændring, du kan læse, som en ny scanning.
Regler for afhentningstidspunkt
Følgende regler gælder, når du opretter eller opdaterer en forsendelses afhentningstidspunkt.pickup_date
(YYYY-MM-DD) og pickup_time_from / pickup_time_till (HH:MM, 24 t) er lokale tidspunkter, der
fortolkes i afsendelsesstedets IANA-tidszone – du sender ikke en tidszone med.
Ændring af forsendelser
Du kan opdatere en forsendelses afhentningstidspunkt, antal pakker, vægt og noter medPATCH /api/v1/shipments/{id}. Hvis et logistikrelevant felt ændres (afhentningsdato, tidspunkt, antal pakker eller vægt), bliver den eksisterende logistikordre automatisk annulleret, og en ny oprettes. Felter, du udelader i opdateringens body, bevares fra den eksisterende forsendelse – hvis du for eksempel kun opdaterer weight, genoprettes ordren med det samme afhentningstidspunkt. Opdaterede tidsfelter valideres efter de samme regler for afhentningstidspunkt.
Hvis logistikudbyderen afviser annulleringen eller genoprettelsen under en opdatering, returnerer API’et 502 Bad Gateway med udbyderens fejlmeddelelse.
Annullering af forsendelser
Annuller en forsendelse medDELETE /api/v1/shipments/{id}. Det kalder logistikudbyderens API for at annullere ordren og opdaterer status til cancelled.
Logistikudbyderen kan også afvise annulleringen af egne grunde (fx hvis annulleringsfristen er udløbet). I så fald returnerer API’et 502 Bad Gateway med udbyderens fejlmeddelelse og fejlkode.
Returlabels
En DHL-returlabel er en del af den udgående ordre. DHL kan ikke annullere labelen alene, så annullering af den række, der sporer en returlabel, returnerer409 Conflict. Annuller i stedet den udgående pakke, mens den er pending. Det annullerer også labelen: Hver returrække med status pending for den udgående pakke bliver cancelled og får en RETURN_LEG_CANCELLED-post i sin status_updates. En returpakke, som patienten allerede har sendt, fortsætter uændret. Når den udgående pakke er afsendt, forbliver labelen gyldig, og Aniva lukker returrækken manuelt.
Reference-id’er for forsendelser
Hver forsendelse har et reference-ID på 11 tegn: et bogstav, datoen og fire tegn,{letter}YYMMDDXXXX (for eksempel P2611194821). Bogstavet viser, hvad forsendelsen hører til, aldrig dens retning:
En forsendelse fra 20. til 22. november 2026 beholder sit ID med et ord foran:
API, MAN, AUTO eller KIT (for eksempel AUTO261121UWKX). Begge former forbliver gyldige. Tjek ikke længden eller det første bogstav i et ID. Brug ID’et til at hente, opdatere eller annullere forsendelsen.
Forsendelsesadresser
Felterneorigin og destination i forsendelsessvaret indeholder opslåede adresseobjekter med følgende struktur:
origin-adressen op ud fra det teststed, du angav ved
oprettelsen, og destination er det laboratorium, du angav i destination_lab.
For en hjemmekitpakke er patientens leveringsadresse kittets destination og
origin for returforsendelsen af prøven; det sted, der pakker kittet, er kittets origin.
Adressen indeholder intet location_id – match en klinikpakke via den tid, den er
knyttet til.
Afhentningsvindue
Feltetpickup i forsendelsessvaret indeholder det planlagte afhentningsvindue for kureren. Det
omfatter tidsstemplerne from og till som UTC-tidspunkter (ISO 8601 med Z-suffiks, fx
2026-04-15T07:00:00Z) samt en timezone-streng (afhentningsstedets IANA-tidszone). De lokale
tidspunkter pickup_date / pickup_time_*, du sendte ved oprettelse/opdatering, omsættes til disse
absolutte tidspunkter ud fra den tidszone – brug timezone til at vise from / till tilbage i
afhentningsstedets lokale tid. Feltet er null, når der ikke er planlagt et afhentningsvindue.
Log over statusopdateringer
Hver forsendelse har etstatus_updates-array – hver livscyklushændelse, logistikudbyderen har
rapporteret, med den ældste først. Hver post indeholder:
state– hændelsen i forsendelsens statusvokabular (pending,in_transit,delivered,fault), så du kan læse en tidslinje uden at kende fragtfirmaets koder.null, når hændelsen ikke har nogen status (oprettelse af label, en fragtfirmascanning uden information, poster registreret før feltet fandtes). Aldrigcancelled– en annullering er vores, ikke en hændelse fra fragtfirmaet.code– fragtfirmaets egen statuskode (GO!‘sGO10,GO90,GOY001; DHL’sVA,ZF,LA,ZU).null, når fragtfirmaet ikke har angivet nogen. Stabil på tværs af sprogoversættelser afstatus.detail_code– fragtfirmaets mere detaljerede kode, når den findes: DHL’sstatusDetailed, fxCNRFC_NRQRD_ZF(omdirigeret til et posthus),HLDCC_SERPT_LA(klar til afhentning dér),DLVRD_SERPT_ZU(afhentet).nulli andre tilfælde.status– fragtfirmaets læsbare tekst (fx"Shipment picked up","Die Sendung wurde abgeholt.").description– en forklaring af koden eller fragtfirmaets længere beskrivelse.null, når ingen af delene findes.location– hvor scanningen skete, som fragtfirmaet angiver det: et GO!-depot, en DHL-by. Fri tekst, ikke et koordinat.time– ISO 8601-tidsstempel for hændelsen, som rapporteret af fragtfirmaet (med tidszoneforskydning).
code
RETURNED_TO_SENDER. Dens status indeholder fragtfirmaets årsag. Forsendelsen forbliver derefter fault, også
efter fragtfirmaet har leveret pakken tilbage til os.
Listen kan være tom, hvis fragtfirmaet endnu ikke har rapporteret nogen hændelser.
Brug status-feltet på øverste niveau for den gældende status. Den bevæger sig kun én vej – fra pending
til in_transit til delivered – med fault lagt ovenpå, mens den nyeste hændelse melder om en fejl;
fragtfirmaer sorterer ikke deres hændelser efter betydning (DHL tilføjer en pre-transit-kodet omdirigeringsbesked
efter overdragelsesscanningen), så den nyeste post alene viser ikke, hvor langt en pakke er.
Eksempel på forsendelse
Eksempel på hjemmekitpakker
GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-… returnerer kittet på vej til patienten og prøven på vej tilbage, parret:
pending, indtil patienten sender prøven – det er den reelle status, ikke en mangel.