Hoppa till huvudinnehåll
En bokning är en planerad blodprovstagning för en patientprofil på en fysisk testplats, utförd av vårdpersonal. Kit som skickas med post till en patient är inte bokningar – se Beställningar av hemtestkit.

Fält

string
obligatorisk
UUID som genereras automatiskt av Aniva. Använd det för att lägga till paneler, bekräfta blodprovstagningen och hämta resultat.
string
obligatorisk
UUID för den profil som bokningen tillhör.
string
UUID för den testplats där blodprovstagningen ska ske. Hemtestkit är inte bokningar – se Beställningar av hemtestkit.
string
Planerat datum och tid för blodprovstagningen i ISO 8601-format. Returneras alltid som en UTC-tidpunkt med suffixet Z (t.ex. 2026-04-15T08:30:00Z). Vid skapande / uppdatering måste värdet innehålla en tidszonsangivelse (antingen Z eller en uttrycklig förskjutning som +02:00) – datum och tider utan tidszon avvisas. Måste ligga i framtiden, och på platser som drivs av Aniva minst 12 timmar framåt (minsta framförhållning).
string
obligatorisk
Aktuell livscykelstatus. Ett av värdena pending, confirmed, blood_drawn eller cancelled. Se Livscykel nedan. Detaljstatus för färdiga labbresultat (in_progress respektive completed) hämtas från Hämta resultat; mer detaljerad försändelsestatus (på väg, levererad osv.) får du genom att följa varje post i den inbäddade shipments-arrayen till Hämta försändelse.
string
Orsak i fritext som registrerades när bokningen avbokades (t.ex. uteblivet besök, sen avbokning, ‘Misslyckades. Behöver göras om’). null om inte status är cancelled.
string[]
obligatorisk
Adresser som var och en får ett mejl när alla labbresultat är slutgiltiga, i gemener. Tom när funktionen är avstängd. Se Mejl när resultat är klara.
string
obligatorisk
Hur blodet tas: capillary (fingertopp eller överarm, i mikrorör) eller venous (från ven, i provrör). Det är metoden som bokningen anger, annars default_draw_method för dess provtagningsställe. Efter blodprovstagningen är det den metod som användes.
string
obligatorisk
ISO 8601-tidsstämpel för när bokningen skapades.
string
ISO 8601-tidsstämpel för den senaste uppdateringen. Null om bokningen aldrig har uppdaterats.
string[]
obligatorisk
Labbkoder (streckkoder på provrör) som registreras vid Bekräfta blodprovstagning, i skanningsordning. Tom tills blodprovstagningen är bekräftad. En venös blodprovstagning har en kod tryckt på varje rör; en kapillär blodprovstagning har en kod per mikrorör. Resultat och dokument refererar till dessa via lab_code.
object[]
obligatorisk
Paneler kopplade till den här bokningen, som { panel_id, added_at }-poster. Se Lägga till paneler.
object[]
obligatorisk
Enskilda biomarkörer kopplade till den här bokningen, som { biomarker_id, added_at }-poster. Se Enskilda biomarkörer.
object[]
obligatorisk
Försändelser kopplade till den här bokningen, som { id, added_at }-poster, med äldsta kopplingen först. Se Koppla försändelser.
object
obligatorisk
Det fullständiga profilobjektet för patienten, inbäddat i varje bokningssvar. Fälten nedan är ett urval. Hämta bokning listar alla fält.

Livscykel

Bokningar har fyra livscykeltillstånd:
Bokningsstatusen är medvetet grovkornig – mer detaljerad status visas via särskilda endpoints:
  • Färdiga labbresultat → Hämta resultat – status-fältet på toppnivå är in_progress eller completed.
  • Försändelsestatus (på väg, levererad osv.) → följ varje post i den inbäddade shipments-arrayen på bokningen till Hämta försändelse – varje försändelse har sin egen status och en status_updates-händelselogg.
Varje statusändring skickar en appointment.*-webhook, till exempel appointment.confirmed. En ny tid eller plats skickar appointment.rescheduled.
Att bekräfta en bokning (ändra den till blood_drawn) är oåterkalleligt. När du har skickat in labbkod(er) startas labbeställningsflödet och det kan inte ångras. Uppdateringar och avbokningar är bara tillåtna medan bokningen har statusen pending eller confirmed.

Lista bokningar

Hämta alla bokningar som din API-nyckel har åtkomst till:
Skicka eventuellt med ?profile_id={uuid} för att filtrera på en specifik profil. Utan den här parametern används ett standardtidsfönster (de senaste 2 månaderna till 1 månad framåt).

Uppdatera en bokning

Innan blodprovstagningen har bekräftats kan du boka om tiden eller byta testplats:
Skicka med valfri kombination av scheduled_at, location_id, draw_method och results_ready_emails för att uppdatera. Inkludera bara de fält du vill ändra.

Provtagningsmetod

Varje bokning har en draw_method: capillary (fingertopp eller överarm, i mikrorör) eller venous (från ven, i provrör). Den gäller bara själva blodprovstagningen. Urinprov, pinnprov och andra prover som inte är blodprover tas på samma sätt oavsett metod. Som standard används platsens default_draw_method. Ange draw_method vid skapande eller uppdatering för att använda en annan metod, eller sätt värdet till null för att återgå till platsens standard. Platsen måste lista metoden i draw_methods, och de bokade testerna måste kunna tas med den, annars returnerar förfrågan 400. Du kan inte ändra den efter blodprovstagningen. Efter blodprovstagningen visar draw_method vilken metod som användes.

En bokning per profil, plats och tid

En profil kan högst ha en icke-avbokad bokning per (location_id, scheduled_at)-par – en person kan inte lämna blodprov två gånger på samma plats vid samma tidpunkt, oavsett hur många parallella bokningar platsen tar emot. Både Skapa bokning och Uppdatera bokning tillämpar detta och returnerar 409 med ett appointment_id som pekar på den bokning som redan finns. Hantera det svaret som att bokningen redan finns snarare än ett fel som ska försökas igen: hämta, boka om eller avboka den angivna bokningen. Den praktiska effekten är att upprepade create-anrop är säkra. Ett create-anrop du skickar igen efter en nätverkstimeout, eller som en användare utlöser två gånger, blir till en enda bokning i stället för två – vilket också innebär att du aldrig behöver reda ut dubblettbokningar för samma patient i efterhand.
Uppdateringar är bara tillåtna före blodprovstagningen – alltså medan bokningen har status pending eller confirmed. När bokningen har gått över till blood_drawn eller är cancelled kan den inte ändras. Det enda undantaget är results_ready_emails: du kan fortfarande ändra enbart det efter blodprovstagningen.

Avboka en bokning

Avboka en bokning som inte längre behövs:
Detta sätter bokningens status till cancelled. Den avbokade bokningen returneras i svaret. Du kan valfritt skicka med cancellation_reason (upp till 500 tecken) i anropets body för att ange orsaken. Den sparas på bokningen och returneras som cancellation_reason vid senare läsningar.
Avbokning är bara tillåten före blodprovstagningen – alltså medan bokningen har status pending eller confirmed. Bokningar som redan har gått över till blood_drawn kan inte avbokas.

Lägga till paneler

Innan du bekräftar blodprovstagningen lägger du till de blodprovspaneler du vill köra genom att anropa:
Skicka en array med panel-UUID:er i fältet panel_ids. Panel-ID:n får du från Aniva för ditt partnerkonto.
Paneler måste läggas till före blodprovstagningen – alltså medan bokningen har status pending eller confirmed. Du kan inte lägga till eller ändra paneler när bokningen väl har gått över till blood_drawn.

Ta bort paneler

Om du behöver ta bort paneler före blodprovstagningen, anropa:
Skicka en array med panel-UUID:er i fältet panel_ids. Borttagningen är idempotent: en panel som inte är kopplad ignoreras.
Precis som tillägg av paneler är borttagning bara tillåten före blodprovstagningen – alltså medan bokningen har status pending eller confirmed. Paneler kan inte tas bort när bokningen har gått över till blood_drawn.

Enskilda biomarkörer

Du kan koppla enskilda biomarkörer till en bokning som fristående tester, utanför en färdig panel. Det är användbart när en behandlare vill ha ett skräddarsytt urval i stället för ett fördefinierat paket. De kopplade biomarkörerna syns i svaret för bokningen som en individual_biomarkers-array (på samma nivå som panels). Routingbeslut fattas längre fram i order- och logistikflödet utifrån varje biomarkörs mappning per laboratorium. Lägg till biomarkörer (idempotent – biomarkörer som redan är kopplade behålls):
Ta bort biomarkörer (idempotent – biomarkörer som inte är kopplade ignoreras):
Båda endpoints tar en biomarker_ids-array och validerar den resulterande uppsättningen mot varje laboratoriums beroenderegler – en beställning som inte kan läggas på ett giltigt sätt (t.ex. en CRP/HDL-kvot utan CRP och HDL) returnerar 400 med de biomarkörer du behöver lägga till, och sparar ingenting. Använd Lista biomarkörer för att hitta biomarkör-ID:n.
Precis som ändringar av paneler kan enskilda biomarkörer bara läggas till eller tas bort före blodprovstagningen – alltså medan bokningen har status pending eller confirmed. När bokningen går över till blood_drawn fryses den anpassade snapshoten.

Förhandsgranska krav på behållare

När du har lagt till paneler eller enskilda biomarkörer, förhandsgranska de fysiska provtagningsbehållare som behövs för provtagningen:
Svarets containers-array innehåller typ, namn, korkfärg, volym, tillverkarens artikelnummer och antal för varje behållare som krävs. Det hjälper behandlare att förbereda rätt material före blodprovstagningen. Svaret innehåller också ett pricing-objekt – bokningens samlade prisunderlag (de poster som aktiverades, de kopplade panelerna och en rad per levererad biomarkör, prissatt enligt din prislista med ordinarie pris bredvid; se Prissättning), som fylls i när bokningen har kopplade tester och din nyckel har scopet prices_view, annars null. routing exponeras medvetet aldrig och är alltid null.
Förhandsgranskningen återspeglar de paneler och biomarkörer som är kopplade just nu. Om du lägger till eller tar bort paneler efter förhandsgranskningen anropar du förhandsgransknings-endpointen igen för att få uppdaterade krav på behållare.

Bekräfta blodprovstagningen

Efter blodprovstagningen skickar du in labbkoderna (rörens streckkoder) för att starta orderflödet till laboratoriet:
Skicka lab_code när en och samma kod är tryckt på varje rör (venös blodprovstagning), eller lab_codes med en post per kod – var och en med de panel_ids den täcker – när varje panel tas i egna rör med egen kod (kapillär blodprovstagning). Varje panel blir då en egen laboratorieremiss under sin kod. Koderna returneras som lab_codes på bokningen. Vid en kapillär blodprovstagning fördelas provet i mikrorör. Paneler kommer först, i bokningsordning. Enskilda biomarkörer fyller sedan det lediga utrymmet i panelernas mikrorör. När de behöver mer plats öppnas nya mikrorör. Vi fördelar dem jämnt. Varje mikrorör rymmer högst 150 µl av enskilda biomarkörer. De anrop som ändrar paneler eller biomarkörer svarar med 400 när den resulterande uppsättningen bryter mot den här regeln. Detta ändrar bokningens status till blood_drawn och startar bearbetningen på laboratoriet. Åtgärden kan inte ångras.

Upphämtning av försändelse

POST /api/v1/appointments/pickup har tagits bort, tillsammans med bokningsstatusen shipment_picked_up. Den svarar nu med 405 Method Not Allowed, eftersom sökvägen faller igenom till routen för bokning per ID. Endpointen fungerade under sin sista fas som en no-op som tog emot anropet utan att göra något, så borttagningen ändrar inget beteende som du förlitade dig på.
För att spåra förloppet efter blodprovstagningen följer du varje post i bokningens inbäddade shipments-array till Hämta försändelse – varje försändelse har sin egen status och en status_updates-historik.

Koppla försändelser

En bokning kan kopplas till en eller flera försändelser (och vice versa – relationen är många-till-många). De aktuella kopplingarna visas inbäddat på båda sidor:
  • på bokningen, som en shipments-array med { id, added_at }-poster;
  • på försändelsen, som en appointments-array med { id, added_at }-poster.
Båda arrayerna har den äldsta kopplingen först. Varje id hänvisar till den kanoniska detalj-endpointen (Hämta försändelse / Hämta bokning) för hela payloaden. Försändelser kopplas när de skapas via fältet appointment_id i Skapa försändelse. Efter skapandet hanterar du kopplingar från försändelsen med Koppla bokningar till försändelse och Koppla bort bokningar från försändelse; båda returnerar försändelsens bokningslista efter ändringen. För att läsa en boknings paket i sin helhet använder du Lista försändelser med ?appointment_id=. Ä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.

Hämta labbresultat

När labbet har analyserat blodproverna hämtar du kliniska och genetiska resultat:
Svaret innehåller planerade tester (status planned) tillsammans med mottagna resultat, så att du kan följa vad som fortfarande väntar. Fältet status på toppnivå är in_progress tills varje inlämning avslutas, därefter completed (eller fault om ingen av dem rapporterade) — använd detta för att avgöra om bokningens labbarbete är klart. En webhook för appointment.results.completed meddelar dig när det sker, så du behöver inte polla. Arrayen submissions delar upp detta per laboratorieremiss, var och en med sin lab_code. Varje mottaget resultat och dokument har den lab_code det registrerades under. PDF-filer med labbrapporter refereras i arrayen documents — använd GET /api/v1/documents/{id} för att ladda ner dem.

Exempel på bokning