Hoppa till huvudinnehåll
En försändelse är ett fysiskt paket: en budhämtning med blodprover från en provtagningsplats till ett laboratorium, kitet på väg till en patient med hemtestkit eller provet som patienten postar tillbaka. Shipments-API:et låter dig skapa, spåra, ändra och avboka försändelser, och listar alla paket på ett ställe oavsett vem som bokade dem.

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 av destination.
  • booked_by — vem som skrev ut etiketten: aniva eller external. Endast aniva-försändelser accepterar Uppdatera och Avboka; ett external-paket spåras i samma lista men returnerar 501 på båda.
Ett paket som innehöll en returetikett och paketet som etiketten skickar tillbaka pekar på varandra via 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.
  • appointments och home_kit_orders listar 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ätter synced_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ändarens location_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.
Båda arrayerna har den äldsta kopplingen först. Varje 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 med PATCH /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.
Försändelser kan inte ändras efter att budet har hämtat paketet. Försök att uppdatera en försändelse med status in_transit, delivered eller fault ger 409 Conflict.
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 med DELETE /api/v1/shipments/{id}. Detta anropar logistikleverantörens API för att avboka beställningen och uppdaterar statusen till cancelled.
Försändelser kan inte avbokas efter upphämtning. Försök att avboka en försändelse som redan har status in_transit, delivered eller fault ger 409 Conflict. Att avboka en som redan är cancelled gör ingenting och returnerar 200 med försändelsen – se Idempotens.
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ör 409 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älten origin och destination i försändelsesvaret innehåller uppslagna adressobjekt med följande struktur:
För ett mottagningspaket hämtas 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ältet pickup 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 en status_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. null när händelsen saknar status (etikett skapad, en skanning utan information från transportören, poster som registrerades innan fältet fanns). Aldrig cancelled – en avbokning är vår, inte en händelse från transportören.
  • code – transportörens egen statuskod (GO10, GO90, GOY001 hos GO!; VA, ZF, LA, ZU hos DHL). null när transportören inte skickade någon. Stabil över olika språköversättningar av status.
  • detail_code – transportörens mer detaljerade kod där en sådan finns: DHL:s statusDetailed, t.ex. CNRFC_NRQRD_ZF (omdirigerad till ett postombud), HLDCC_SERPT_LA (klar för upphämtning där), DLVRD_SERPT_ZU (uthämtad). null i ö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. null nä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).
När transportören skickar tillbaka paketet till avsändaren får tidslinjen en post med 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:
Returraden finns från det ögonblick returetiketten skrivs ut och förblir pending tills patienten skickar provet – det är det verkliga läget, inte en lucka.