Spring til hovedindhold
En forsendelse er én fysisk pakke: en kurerafhentning med blodprøver fra en testlokation til et laboratorium, kittet på vej til en patient med hjemmetestkit eller prøven, som patienten sender retur. Forsendelses-API’et lader dig oprette, spore, ændre og annullere forsendelsesordrer og samler alle pakker ét sted, uanset hvem der har booket dem.

É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 af destination.
  • booked_by — hvem der udskrev labelen: aniva eller external. Kun aniva-forsendelser accepterer Opdater og Annuller; en external-pakke spores i den samme liste, men returnerer 501 på begge.
En pakke, der indeholdt en returlabel, og den pakke, som labelen sender retur, peger på hinanden via 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.
  • appointments og home_kit_orders viser 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ætter synced_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 oprindelsens location_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.
Begge arrays har ældste tilknytning først. Hvert 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 med PATCH /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.
Forsendelser kan ikke ændres, når kureren har afhentet pakken. Forsøg på at opdatere en forsendelse med status in_transit, delivered eller fault returnerer 409 Conflict.
Hvis logistikudbyderen afviser annulleringen eller genoprettelsen under en opdatering, returnerer API’et 502 Bad Gateway med udbyderens fejlmeddelelse.

Annullering af forsendelser

Annuller en forsendelse med DELETE /api/v1/shipments/{id}. Det kalder logistikudbyderens API for at annullere ordren og opdaterer status til cancelled.
Forsendelser kan ikke annulleres efter afhentning. Forsøg på at annullere en forsendelse, der allerede er in_transit, delivered eller fault, returnerer 409 Conflict. At annullere en forsendelse, der allerede er cancelled, har ingen effekt og returnerer 200 med forsendelsen – se Idempotens.
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, returnerer 409 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

Felterne origin og destination i forsendelsessvaret indeholder opslåede adresseobjekter med følgende struktur:
For en klinikpakke slås 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

Feltet pickup 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 et status_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). Aldrig cancelled – en annullering er vores, ikke en hændelse fra fragtfirmaet.
  • code – fragtfirmaets egen statuskode (GO!‘s GO10, GO90, GOY001; DHL’s VA, ZF, LA, ZU). null, når fragtfirmaet ikke har angivet nogen. Stabil på tværs af sprogoversættelser af status.
  • detail_code – fragtfirmaets mere detaljerede kode, når den findes: DHL’s statusDetailed, fx CNRFC_NRQRD_ZF (omdirigeret til et posthus), HLDCC_SERPT_LA (klar til afhentning dér), DLVRD_SERPT_ZU (afhentet). null i 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).
Når fragtfirmaet sender pakken tilbage til afsenderen, får tidslinjen én post med 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:
Returrækken findes fra det øjeblik, returlabelen udskrives, og forbliver pending, indtil patienten sender prøven – det er den reelle status, ikke en mangel.