En lista, filtrerad
GET /api/v1/shipments är den enda samlingen. En försändelse står för sig själv — den har en många-till-många-relation med bokningar och kan höra till en beställning av hemtestkit — så det finns ingen lista kapslad under ett överordnat objekt. Begränsa samma lista med ?appointment_id= eller ?home_kit_order_id=, paginera den med limit / offset och följ den inbäddade shipments-arrayen ({ id, added_at } på både bokningar och beställningar av hemtestkit) till Hämta försändelse när du har ett id.
Innehåll och vem som bokade
Varje försändelse innehåller två uppgifter som inte framgår av adresserna:contents— fritext som beskriver vad som finns i paketet, anges vid skapandet ("Medizinisch freigestellte Probe","Home test kit") och visas för budet. Endast för information. Riktning är inte ett fält: om ett paket är på väg till ett laboratorium framgår avdestination.booked_by— vem som skrev ut etiketten:anivaellerexternal. Endastaniva-försändelser accepterar Uppdatera och Avboka; ettexternal-paket spåras i samma lista men returnerar501på båda.
paired_with.
Åtkomst
- Du kan läsa ett paket när minst en kopplad bokning eller beställning av hemtestkit finns i din åtkomstkontext, eller när det skickades från en plats i din åtkomstkontext.
appointmentsochhome_kit_orderslistar bara de bokningar och beställningar som finns i din åtkomstkontext.- Uppdatera, Avboka, Koppla bokningar och Koppla bort bokningar kräver att varje kopplad beställning av hemtestkit finns i din åtkomstkontext. Annars returnerar anropet
403, och bara Aniva kan ändra paketet.
Läsningar anropar aldrig transportören
Varje läsning besvaras från vår databas. En bakgrundssynkronisering stämmer av varje försändelse mot dess transportör (var 10:e minut för GO!, varje timme för DHL) och sättersynced_at, som visar hur gammalt ett svar är. Det finns ingen tvingad uppdatering — DHL tillåter ett spårningsanrop var femte sekund, så en läsning som anropar transportören direkt kan inte erbjudas.
Skapa en försändelse
När du skapar en försändelse anger du avsändarenslocation_id — provtagningsplatsen där budet ska hämta upp. Du anger också mottagande laboratorium med destination_lab. Försändelsen skickas till laboratoriets registrerade leveransadress.
Platsen måste ingå i din API-nyckels åtkomstkontext. Använd Lista platser för att hitta tillgängliga plats-ID:n.
Du kan valfritt skicka med appointment_id för att koppla försändelsen till en specifik bokning vid
skapandet. Kopplingen visas direkt på båda sidor:
- på försändelsen, som en
appointments-array med{ id, added_at }-poster; - på bokningen, som en
shipments-array med{ id, added_at }-poster.
id korsrefererar till den kanoniska detalj-endpointen
(Hämta bokning /
Hämta försändelse) för hela payloaden — partner som vill
följa budets status per bokning följer varje post i bokningens shipments-array till
försändelsens detalj-endpoint.
En försändelse kan kopplas till flera bokningar, och en bokning kan kopplas till flera
försändelser. Efter skapandet hanterar du kopplingen med Koppla bokningar till
försändelse /
Koppla bort bokningar från försändelse. Varje
ändring returnerar försändelsens uppdaterade bokningslista.
Ändringsregeln är: kopplingar kan skapas eller tas bort när ANTINGEN bokningen har passerat
blodprovstagning (blood_drawn), eller försändelsen skapades för mindre än 24 timmar sedan. Utanför det
fönstret är kopplingen låst så att historiska poster förblir stabila.
Livscykel
Försändelser går igenom följande statusar:
Varje statusändring skickar en
shipment.*-webhook, till exempel
shipment.delivered. shipment.updated utlöses vid varje ändring du kan läsa av, som en ny skanning.
Regler för upphämtningsschema
Följande regler gäller när du skapar eller uppdaterar en försändelses upphämtningsschema.pickup_date
(YYYY-MM-DD) och pickup_time_from / pickup_time_till (HH:MM, 24-timmarsformat) är lokala tider
som tolkas i avsändarplatsens IANA-tidszon – du skickar inte med någon tidszon tillsammans med dem.
Ändra försändelser
Du kan uppdatera en försändelses upphämtningsschema, antal paket, vikt och anteckningar medPATCH /api/v1/shipments/{id}. Om något logistikrelevant fält ändras (upphämtningsdatum, tid, antal paket eller vikt) avbokas den befintliga logistikbeställningen automatiskt och en ny skapas. Fält som du utelämnar i uppdateringsbegäran behålls från den befintliga försändelsen – om du till exempel bara uppdaterar weight skapas beställningen på nytt med samma upphämtningsschema. Uppdaterade schemafält valideras mot samma regler för upphämtningsschema.
Om logistikleverantören avvisar avbokningen eller nybeställningen vid en uppdatering returnerar API:et 502 Bad Gateway med leverantörens felmeddelande.
Avboka försändelser
Avboka en försändelse medDELETE /api/v1/shipments/{id}. Detta anropar logistikleverantörens API för att avboka beställningen och uppdaterar statusen till cancelled.
Logistikleverantören kan också avvisa avbokningen av egna skäl (t.ex. om tidsfristen för avbokning har passerat). I så fall returnerar API:et 502 Bad Gateway med leverantörens felmeddelande och felkod.
Returetiketter
En returetikett från DHL är en del av den utgående beställningen. DHL kan inte makulera etiketten på egen hand; att avboka raden som spårar en returetikett ger därför409 Conflict. Avboka det utgående paketet i stället, medan det är pending. Då makuleras etiketten samtidigt: varje returrad med status pending för det utgående paketet blir cancelled och får en RETURN_LEG_CANCELLED-post i sin status_updates. Ett returpaket som patienten redan har skickat fortsätter på sin väg. När det utgående paketet har skickats fortsätter etiketten att gälla och Aniva stänger returraden manuellt.
Referens-ID:n för försändelser
Varje försändelse har ett referens-ID på 11 tecken: en bokstav, datumet och fyra tecken,{letter}YYMMDDXXXX (till exempel P2611194821). Bokstaven visar vad försändelsen tillhör, aldrig dess riktning:
En försändelse från 20 till 22 november 2026 behåller sitt ID med ett ord framför:
API, MAN, AUTO eller KIT (till exempel AUTO261121UWKX). Båda formaten förblir giltiga. Kontrollera inte längden eller den första bokstaven i ett ID. Använd ID:t för att hämta, uppdatera eller avbryta försändelsen.
Adresser för försändelser
Fältenorigin och destination i försändelsesvaret innehåller uppslagna adressobjekt med följande struktur:
origin-adressen från den testplats du angav när försändelsen
skapades, och destination är det laboratorium du angav i destination_lab.
För ett hemtestpaket är patientens leveransadress destination för kitet och
origin för provreturen; platsen som packar kitet är dess origin. Adressen
innehåller inget location_id – koppla ett mottagningspaket via den bokning det är
knutet till.
Upphämtningsfönster
Fältetpickup i försändelsesvaret innehåller det schemalagda upphämtningsfönstret för budet. Det
innehåller tidsstämplarna from och till som UTC-tidpunkter (ISO 8601 med suffixet Z, t.ex.
2026-04-15T07:00:00Z) och en timezone-sträng (upphämtningsplatsens IANA-tidszon). De
lokala värdena pickup_date / pickup_time_* som du skickade när försändelsen skapades eller
uppdaterades räknas om till dessa absoluta tidpunkter med hjälp av den tidszonen – använd timezone
för att visa from / till i upphämtningsplatsens lokala tid igen. Fältet är null när inget
upphämtningsfönster har schemalagts.
Logg över statusuppdateringar
Varje försändelse har enstatus_updates-array – alla livscykelhändelser som logistikleverantören
har rapporterat, äldst först. Varje post innehåller:
state– händelsen i försändelsens statusvokabulär (pending,in_transit,delivered,fault), så att du kan läsa en tidslinje utan att känna till transportörens koder.nullnär händelsen saknar status (etikett skapad, en skanning utan information från transportören, poster som registrerades innan fältet fanns). Aldrigcancelled– en avbokning är vår, inte en händelse från transportören.code– transportörens egen statuskod (GO10,GO90,GOY001hos GO!;VA,ZF,LA,ZUhos DHL).nullnär transportören inte skickade någon. Stabil över olika språköversättningar avstatus.detail_code– transportörens mer detaljerade kod där en sådan finns: DHL:sstatusDetailed, t.ex.CNRFC_NRQRD_ZF(omdirigerad till ett postombud),HLDCC_SERPT_LA(klar för upphämtning där),DLVRD_SERPT_ZU(uthämtad).nulli övriga fall.status– transportörens läsbara text (t.ex."Shipment picked up","Die Sendung wurde abgeholt.").description– en förklaring av koden, eller transportörens längre beskrivning.nullnär ingetdera finns.location– var skanningen skedde, så som transportören anger det: en GO!-depå, en stad hos DHL. Fritext, inte en koordinat.time– ISO 8601-tidsstämpel för händelsen, så som transportören rapporterade den (med sin tidsförskjutning).
code
RETURNED_TO_SENDER. Dess status innehåller transportörens orsak. Försändelsen förblir sedan
fault, även efter att transportören har levererat tillbaka paketet till oss.
Listan kan vara tom om transportören inte har rapporterat några händelser ännu.
Använd toppnivåfältet status för aktuell gällande status. Den rör sig åt ett håll – pending
till in_transit till delivered – med fault överlagrat medan den senaste händelsen rapporterar
ett fel; transportörer sorterar inte sina händelser efter betydelse (DHL lägger till en avisering
om omdirigering med koden pre-transit efter överlämningsskanningen), så den senaste posten ensam
säger inte var ett paket befinner sig.
Exempelförsändelse
Exempel på hemtestpaket
GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-… returnerar kitet på väg till patienten och provet på väg tillbaka, ihopparade:
pending tills patienten skickar provet – det är det verkliga läget, inte en lucka.