Saltar al contingut principal
POST
Programa una cita d’extracció de sang per a un perfil de pacient en una ubicació de proves concreta. Un cop creada, la cita passa a l’estat confirmed per defecte (algunes ubicacions poden fer servir pending per defecte — és una configuració específica de cada ubicació). Fes servir Afegeix panells per associar panells d’anàlisi de sang abans de confirmar l’extracció de sang.
Un perfil pot tenir com a màxim una cita per ubicació i hora. Crear una cita per a una franja que el perfil ja ocupa retorna 409 amb l’appointment_id existent en lloc d’una segona cita — així una sol·licitud reintentada o repetida per error no pot duplicar mai una reserva. Consulta Cites duplicades.
Envia una capçalera opcional Idempotency-Key perquè aquesta creació es pugui reintentar amb seguretat — repetir la mateixa clau retorna la resposta original en lloc de crear-ne una segona. Consulta Idempotència. Requereix l’abast appointments_schedule.

Sol·licitud

Paràmetres del cos

string
requerit
UUID del perfil del pacient per al qual es crea la cita.
string
requerit
UUID de la ubicació de proves on es farà l’extracció de sang. Fes servir Llista les ubicacions per trobar els ID d’ubicació disponibles.
string
requerit
Data i hora de la cita en format ISO 8601 (p. ex., 2026-05-15T10:30:00Z o 2026-05-15T12:30:00+02:00). Ha d’incloure un indicador de fus horari — sigui Z o un desplaçament explícit com +02:00; les dates i hores sense fus horari es rebutgen. Ha de ser en el futur.Ha de coincidir exactament amb l’inici d’una franja de la graella de la ubicació, i la franja encara ha de tenir capacitat — consulta Obtén la disponibilitat primer. Les hores fora de graella retornen 400; una franja plena retorna 409. A les ubicacions gestionades per Aniva també ha de ser amb un mínim de 12 hores d’antelació — consulta Antelació mínima.
string[]
Fins a 5 adreces que reben cadascuna un correu un cop tots els resultats del laboratori són definitius. El correu enllaça a la pàgina de resultats del panell d’administració d’Aniva. La teva clau necessita accés results_view per al pacient; si no, retorna 403. Omet-lo per fer servir les adreces per defecte configurades per al grup del pacient. Una llista buida desactiva els correus. Consulta Correus de resultats disponibles.
string
Com es fa l’extracció de sang: capillary o venous. Omet-lo per fer servir el default_draw_method de la ubicació. La ubicació ha d’incloure el mètode a draw_methods; si no, retorna 400.

Resposta

Si té èxit, l’API retorna 201 Created amb la nova cita.
string
requerit
Identificador únic de la cita (UUID).
string
requerit
UUID del perfil al qual pertany aquesta cita.
string
UUID de la ubicació de proves on es fa l’extracció de sang.
string
Data i hora programades de la cita com a instant UTC (ISO 8601 amb el sufix Z, p. ex., 2026-05-15T10:30:00Z). Pot ser null.
string
requerit
Estat actual de la cita. Pot ser pending, confirmed, blood_drawn o cancelled. El detall de compleció dels resultats de laboratori s’obté mitjançant Obtén els resultats; el progrés detallat de l’enviament, a partir de cada entrada de la matriu shipments inclosa aquí (més avall) seguida a Obtén l’enviament.
string
Motiu en text lliure registrat en cancel·lar la cita (p. ex., absència, cancel·lació tardana, «Error. Cal repetir»). null llevat que status sigui cancelled.
string[]
requerit
Adreces que reben un correu electrònic cadascuna quan tots els resultats del laboratori són definitius, en minúscules. Buit quan està desactivat. Consulta Correus electrònics de resultats a punt.
string
requerit
Com es fa l’extracció de sang: capillary (de la punta del dit o de la part superior del braç, en microtubs) o venous (de la vena, en tubs). És el mètode definit a la cita o, si no n’hi ha, el default_draw_method de la seva ubicació. Després de l’extracció de sang, és el mètode que s’ha fet servir.
object
requerit
El perfil del pacient associat a aquesta cita.
AppointmentPanel[]
requerit
Panells associats actualment a aquesta cita. Buit en cites acabades de crear — associa’ls amb Afegeix panells. Consulta els detalls dels panells (nom, biomarcadors) amb Llista els panells.
AppointmentIndividualBiomarker[]
requerit
Biomarcadors a la carta associats a aquesta cita fora de qualsevol panell. Buit en cites acabades de crear — associa’ls amb Afegeix biomarcadors individuals. Creua cada biomarker_id amb Llista els biomarcadors per obtenir les dades de visualització.
AppointmentShipmentLink[]
requerit
Enviaments vinculats a aquesta cita, primer el vincle més antic. Buit en cites acabades de crear — vincula’ls amb Crea un enviament (amb appointment_id) o Adjunta cites a un enviament.
string[]
requerit
Codis de laboratori (codis de barres dels tubs) registrats per a aquesta cita, per ordre d’escaneig. Buit fins que es confirmi l’extracció de sang. Una extracció venosa porta un sol codi imprès a cada tub; una extracció capil·lar porta un codi per microtub. Els resultats i documents a Obtén els resultats fan referència a aquests codis mitjançant lab_code.

Antelació mínima

Les cites a les ubicacions gestionades per Aniva s’han de reservar com a mínim amb 12 hores d’antelació; reservar dins d’aquest marge retorna 400. Obtén la disponibilitat ja exclou aquestes franges, així que tot el que llegeixis d’aquesta graella es pot reservar. Les ubicacions que gestiones directament no tenen antelació mínima — les reserves per al mateix dia i sense cita prèvia no canvien.

Cites duplicades

Un perfil pot tenir com a màxim una cita no cancel·lada per ubicació i instant — una persona no pot fer-se dues extraccions al mateix lloc i al mateix moment, per moltes cadires que tingui la ubicació. Crear una cita per a una franja que el perfil ja ocupa retorna 409 amb un appointment_id que indica la cita que ja existeix:
Gestiona-ho tractant la sol·licitud com si ja s’hagués aplicat: recupera la cita amb Obtén la cita, mou-la amb Actualitza la cita o descarta-la amb Cancel·la la cita. No reintentis la creació — continuarà retornant 409. Això fa que les creacions repetides siguin segures: una sol·licitud que reenviïs després d’un temps d’espera exhaurit, o un formulari enviat dues vegades, no pot generar dues cites per al mateix pacient a la mateixa hora.
appointment_id només és present al 409 per duplicat. El 409 de capacitat — la franja és plena perquè l’ocupen altres pacients — retorna només error, i en aquest cas la solució correcta és triar una altra franja a Obtén la disponibilitat.

Respostes d’error