Camps
UUID generat automàticament per Aniva. Fes-lo servir per afegir panells, confirmar l’extracció
de sang i obtenir resultats.
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.
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).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.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.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.
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.Marca de temps ISO 8601 de l’actualització més recent. Nul si la cita no s’ha actualitzat mai.
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.Panells associats a aquesta cita, com a entrades
{ panel_id, added_at }. Consulta
Afegir panells.Biomarcadors a la carta associats a aquesta cita, com a entrades
{ biomarker_id, added_at }.
Consulta Biomarcadors individuals.Enviaments vinculats a aquesta cita, com a entrades
{ id, added_at }, començant pel vincle més
antic. Consulta Vincular enviaments.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
statusde nivell superior ésin_progressocompleted. - Progrés de l’enviament (en trànsit, lliurat, etc.) → segueix cada entrada de la matriu
shipmentsinclosa a la cita cap a Obtenir enviament — cada enviament té el seu propistatusi un registre d’esdevenimentsstatus_updates.
appointment.*, per exemple
appointment.confirmed. Una nova hora o ubicació envia appointment.rescheduled.Llistar cites
Obtén totes les cites accessibles amb la teva clau API:?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: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é undraw_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: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: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: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 matriuindividual_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):
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: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: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
Per fer el seguiment de l’evolució posterior a l’extracció de sang, segueix cada entrada de la matriushipments
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
shipmentsd’entrades{ id, added_at }; - a l’enviament, com una matriu
appointmentsd’entrades{ id, added_at }.
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.
Recuperació dels resultats de laboratori
Un cop el laboratori hagi processat les mostres de sang, recupera els resultats clínics i genètics: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.