Saltar al contingut principal
Una cita és una extracció de sang programada per a un perfil de pacient en una ubicació de proves física, feta per un professional sanitari. Els kits enviats per correu a un pacient no són cites — consulta Comandes de kits de prova a casa.

Camps

string
requerit
UUID generat automàticament per Aniva. Fes-lo servir per afegir panells, confirmar l’extracció de sang i obtenir resultats.
string
requerit
L’UUID del perfil al qual pertany aquesta cita.
string
L’UUID de la ubicació de proves on es farà l’extracció de sang. Els kits de prova a casa no són cites — consulta Comandes de kits de prova a casa.
string
Data i hora programades de l’extracció de sang en format ISO 8601. Sempre es retorna com un instant UTC amb el sufix Z (p. ex., 2026-04-15T08:30:00Z). En crear o actualitzar, el valor ha d’incloure un indicador de fus horari (ja 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 i, a les ubicacions gestionades per Aniva, amb almenys 12 hores d’antelació (antelació mínima).
string
requerit
Estat actual del cicle de vida. Pot ser pending, confirmed, blood_drawn o cancelled. Consulta Cicle de vida més avall. El detall sobre la finalització dels resultats de laboratori (in_progress o completed) s’obté a Obtenir resultats; l’evolució més detallada dels enviaments (en trànsit, lliurat, etc.) s’obté seguint cada entrada de la matriu shipments inclosa a Obtenir 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.
string
requerit
Marca de temps ISO 8601 de quan es va crear la cita.
string
Marca de temps ISO 8601 de l’actualització més recent. Nul si la cita no s’ha actualitzat mai.
string[]
requerit
Codis de laboratori (codis de barres dels tubs) registrats a Confirmar l’extracció de sang, en ordre d’escaneig. Buit fins que es confirma l’extracció. Una extracció venosa té un únic codi imprès a cada tub; una extracció capil·lar té un codi per microtub. Els resultats i els documents hi fan referència mitjançant lab_code.
object[]
requerit
Panells associats a aquesta cita, com a entrades { panel_id, added_at }. Consulta Afegir panells.
object[]
requerit
Biomarcadors a la carta associats a aquesta cita, com a entrades { biomarker_id, added_at }. Consulta Biomarcadors individuals.
object[]
requerit
Enviaments vinculats a aquesta cita, com a entrades { id, added_at }, començant pel vincle més antic. Consulta Vincular enviaments.
object
requerit
L’objecte de perfil complet del pacient, inclòs en cada resposta de cita. Els camps següents en són un subconjunt. Obtenir cita els llista tots.

Cicle de vida

Les cites exposen quatre estats del cicle de vida:
El conjunt d’estats de la cita és intencionadament general — el progrés més detallat s’exposa mitjançant endpoints dedicats:
  • Finalització dels resultats de laboratori → Obtenir resultats — el camp status de nivell superior és in_progress o completed.
  • Progrés de l’enviament (en trànsit, lliurat, etc.) → segueix cada entrada de la matriu shipments inclosa a la cita cap a Obtenir enviament — cada enviament té el seu propi status i un registre d’esdeveniments status_updates.
Cada canvi d’estat envia un webhook appointment.*, per exemple appointment.confirmed. Una nova hora o ubicació envia appointment.rescheduled.
Confirmar una cita (passar-la a blood_drawn) és irreversible. Un cop enviïs el codi o els codis de laboratori, s’activa el flux de comanda al laboratori i no es pot desfer. Només es permeten actualitzacions i cancel·lacions mentre la cita està en estat pending o confirmed.

Llistar cites

Obtén totes les cites accessibles amb la teva clau API:
Opcionalment, passa ?profile_id={uuid} per filtrar per un perfil concret. Sense aquest paràmetre, s’aplica una finestra de temps predeterminada (dels últims 2 mesos fins a 1 mes en el futur).

Actualitzar una cita

Abans que es confirmi l’extracció de sang, pots reprogramar la cita o canviar la ubicació de proves:
Passa qualsevol combinació de scheduled_at, location_id, draw_method i results_ready_emails per actualitzar-la. Inclou només els camps que vulguis canviar.

Mètode d’extracció

Cada cita té un draw_method: capillary (del dit o de la part superior del braç, en microtubs) o venous (de la vena, en tubs). Només s’aplica a l’extracció de sang. Les mostres d’orina, d’escovilló i altres mostres que no són de sang es recullen de la mateixa manera amb qualsevol dels dos mètodes. Per defecte, és el default_draw_method de la ubicació. Defineix draw_method en crear o actualitzar per fer servir un altre mètode, o assigna-li null per tornar al valor per defecte de la ubicació. La ubicació ha d’incloure el mètode a draw_methods i les proves reservades s’han de poder fer amb aquest mètode; si no, la sol·licitud retorna 400. No el pots canviar després de l’extracció de sang. Després de l’extracció, draw_method és el mètode que s’ha fet servir.

Una cita per perfil, ubicació i hora

Un perfil pot tenir com a màxim una cita no cancel·lada per cada parell (location_id, scheduled_at) — a una persona no se li pot fer l’extracció dues vegades al mateix lloc i en el mateix moment, independentment de quantes reserves paral·leles accepti la ubicació. Tant Crear cita com Actualitzar cita apliquen aquesta regla i retornen 409 amb un appointment_id que apunta a la cita que ja existeix. Tracta aquesta resposta com una cita ja reservada i no com un error que calgui reintentar: obtén, reprograma o cancel·la la cita que indica. L’efecte pràctic és que les creacions repetides són segures. Una creació que tornis a enviar després que s’esgoti el temps d’espera de la xarxa, o que un usuari activi dues vegades, es resol en una sola cita en lloc de dues — i això també vol dir que no hauràs de conciliar mai reserves duplicades per al mateix pacient a posteriori.
Les actualitzacions només es permeten abans de l’extracció de sang — és a dir, mentre la cita està en estat pending o confirmed. Un cop la cita passa a blood_drawn o ha quedat en cancelled, no es pot modificar. L’única excepció és results_ready_emails: encara el pots canviar sol després de l’extracció de sang.

Cancel·lar una cita

Cancel·la una cita que ja no cal:
Això canvia l’estat de la cita a cancelled. La cita cancel·lada es retorna a la resposta. Opcionalment, envia un cancellation_reason (fins a 500 caràcters) al cos per registrar-ne el motiu. Es desa a la cita i es retorna com a cancellation_reason en lectures posteriors.
La cancel·lació només es permet abans de l’extracció de sang — és a dir, mentre la cita està en estat pending o confirmed. Les cites que ja han passat a blood_drawn no es poden cancel·lar.

Afegir panells

Abans de confirmar l’extracció de sang, afegeix els panells d’anàlisi de sang que vulguis fer cridant:
Passa una matriu d’UUID de panells al camp panel_ids. Aniva proporciona els ID de panell per al teu compte de col·laborador.
Els panells s’han d’afegir abans de l’extracció de sang — és a dir, mentre la cita està en estat pending o confirmed. No pots afegir ni canviar panells un cop la cita ha passat a blood_drawn.

Eliminar panells

Si necessites eliminar panells abans de l’extracció de sang, crida:
Passa una matriu d’UUID de panells al camp panel_ids. L’eliminació és idempotent: un panell que no estigui vinculat s’ignora.
Igual que afegir panells, eliminar-los només es permet abans de l’extracció de sang — és a dir, mentre la cita està en estat pending o confirmed. Els panells no es poden eliminar un cop la cita ha passat a blood_drawn.

Biomarcadors individuals

Pots vincular biomarcadors individuals a una cita com a proves a la carta, fora de qualsevol panell preconfigurat. Això és útil quan un professional vol una selecció a mida en lloc d’un paquet predefinit. Els biomarcadors vinculats apareixen a la resposta de la cita com una matriu individual_biomarkers (al mateix nivell que panels). Les decisions d’encaminament es prenen posteriorment al flux de logística de comandes segons les correspondències per laboratori de cada biomarcador. Afegeix biomarcadors (idempotent — els biomarcadors ja vinculats es conserven):
Elimina biomarcadors (idempotent — els biomarcadors que no estiguin vinculats s’ignoren):
Tots dos endpoints accepten una matriu biomarker_ids i validen el conjunt resultant segons les regles de tancament de cada laboratori — una comanda que no es pugui cursar correctament (p. ex., una relació CRP/HDL sense CRP ni HDL) retorna 400 amb els biomarcadors que hauries d’afegir, i no desa res. Fes servir Llista els biomarcadors per descobrir els ID de biomarcador.
Igual que les modificacions de panells, els biomarcadors individuals només es poden afegir o eliminar abans de l’extracció de sang — és a dir, mentre la cita està en estat pending o confirmed. Un cop la cita passa a blood_drawn, la instantània personalitzada queda congelada.

Previsualitzar els requisits de contenidors

Després d’afegir panells o biomarcadors individuals, previsualitza els contenidors físics de recollida de mostres que caldran per a la presa de mostres:
La matriu containers de la resposta inclou el tipus, el nom, el color del tap, el volum, el número d’article del fabricant i la quantitat de cada contenidor necessari. Això ajuda els professionals a preparar el material correcte abans de l’extracció de sang. La resposta també inclou un objecte pricing — la factura de tota la cistella de la cita (les posicions que s’han aplicat, els panells vinculats i una fila per cada biomarcador lliurat, amb el preu de la teva tarifa i el preu de venda al públic al costat; consulta Preus), que s’emplena quan la cita té proves vinculades i la teva clau té l’àmbit prices_view; en cas contrari, és null. De manera intencionada, routing no s’exposa mai i sempre és null.
La previsualització reflecteix els panells i biomarcadors vinculats actualment. Si afegeixes o elimines panells després de previsualitzar-los, torna a cridar l’endpoint de previsualització per obtenir els requisits de contenidors actualitzats.

Confirmar l’extracció de sang

Un cop feta l’extracció de sang, envia els codis de laboratori (codis de barres dels tubs) per activar el flux de comandes de laboratori:
Envia lab_code quan hi ha un sol codi imprès a cada tub (extracció venosa), o lab_codes amb una entrada per codi — cadascuna amb els panel_ids que cobreix — quan cada panell s’extreu als seus propis tubs amb el seu propi codi (extracció capil·lar). Aleshores, cada panell és la seva pròpia sol·licitud de laboratori amb el seu codi. Els codis es retornen com a lab_codes a la cita. En una extracció capil·lar, l’extracció s’envasa en microtubs. Els panells van primer, per ordre de reserva. Els biomarcadors individuals omplen després l’espai lliure dels microtubs dels panells. Quan necessiten més espai, obren nous microtubs. Els repartim de manera uniforme. Cada microtub admet com a màxim 150 µl de biomarcadors individuals. Les crides que canvien panells o biomarcadors responen amb 400 quan el conjunt resultant incompleix aquesta regla. Això canvia l’estat de la cita a blood_drawn i inicia el processament al laboratori. Aquesta acció és irreversible.

Recollida de l’enviament

POST /api/v1/appointments/pickup s’ha eliminat, juntament amb l’estat de cita shipment_picked_up. Ara respon 405 Method Not Allowed, perquè el camí acaba a la ruta de cita per ID. L’endpoint va passar la seva fase final com una operació sense efecte que acceptava la crida i no feia res, així que eliminar-lo no canvia cap comportament del qual depenguessis.
Per fer el seguiment de l’evolució posterior a l’extracció de sang, segueix cada entrada de la matriu shipments integrada a la cita fins a Obtén l’enviament — cada enviament té el seu propi status i un historial status_updates.

Vincular enviaments

Una cita es pot vincular a un o més enviaments (i viceversa — la relació és de molts a molts). El conjunt actual de vincles apareix integrat a tots dos costats:
  • a la cita, com una matriu shipments d’entrades { id, added_at };
  • a l’enviament, com una matriu appointments d’entrades { id, added_at }.
Totes dues matrius van del vincle més antic al més recent. Cada id remet a l’endpoint canònic de detall (Obtén l’enviament / Obtén la cita) per obtenir el contingut complet. Els enviaments es vinculen en el moment de la creació mitjançant el camp appointment_id de Crea un enviament. Després de crear-los, gestiona els vincles des de l’enviament amb Vincula cites a un enviament i Desvincula cites d’un enviament; cadascun retorna la llista de cites posterior a la modificació per a aquell enviament. Per llegir els paquets d’una cita al complet, fes servir Llista els enviaments amb ?appointment_id=. La regla de modificació és: els vincles es poden crear o eliminar quan O BÉ
  • la cita ja ha passat l’extracció de sang (blood_drawn), o
  • l’enviament es va crear fa menys de 24 hores.
Fora d’aquest marge, el vincle queda bloquejat perquè els registres històrics es mantinguin estables.

Recuperació dels resultats de laboratori

Un cop el laboratori hagi processat les mostres de sang, recupera els resultats clínics i genètics:
La resposta inclou les proves planificades (estat planned) juntament amb els resultats rebuts, perquè puguis fer el seguiment del que encara està pendent. El camp status de nivell superior és in_progress fins que es tanquen totes les trameses, i aleshores passa a completed (o fault quan cap no ha informat) — fes-lo servir per determinar si la feina de laboratori de la cita ha acabat. Un webhook appointment.results.completed t’avisa quan això passa, de manera que no cal que facis consultes periòdiques. La matriu submissions ho desglossa per petició de laboratori, cadascuna amb el seu lab_code. Cada resultat i document rebut porta el lab_code amb què es va registrar. Els PDF dels informes de laboratori es referencien a la matriu documents — fes servir GET /api/v1/documents/{id} per descarregar-los.

Exemple de cita