Els endpoints de comandes de kit de prova a casa requereixen l’abast
home_kit_orders_view
(lectura) o home_kit_orders_manage (escriptura). Activa
també accepta l’abast més restringit home_kit_orders_activate.
Obtén els resultats i
Envia els resultats per correu electrònic requereixen a més
results_view — els resultats de laboratori i els documents sempre estan protegits per aquest abast.Camps
UUID generat automàticament per Aniva. Fes-lo servir per actualitzar la comanda, canviar-ne el
panell, activar-la, cancel·lar-la i recuperar els resultats.
Estat actual del cicle de vida. Pot ser
pending, dispatched, activated o cancelled.
Consulta Cicle de vida més avall. El grau de compleció dels resultats de laboratori
(in_progress o completed) s’obté a través d’Obtén els resultats.L’adreça on s’ha d’enviar el kit per correu — pot tenir dues formes: o bé
{location_id} fent
referència a una ubicació de proves coneguda, o bé els camps d’adreça directes (name, street,
city, postal_code, country_code; company_name / house_number / address_line_2 /
state / phone / email opcionals — el mateix vocabulari que l’API d’ubicacions).
Proporciona’n exactament una — una referència d’ubicació o una adreça directa, no totes dues.Packstation o Postfiliale (només a Alemanya): defineix
street com a Packstation o
Postfiliale, house_number amb el número de tres dígits de l’estació i address_line_2 amb
el DHL Postnummer del destinatari (de 6 a 10 dígits, s’admeten espais). Sense el Postnummer, no
es pot reservar el paquet. No s’admet un Postfach.Marca de temps ISO 8601 de l’actualització més recent. Nul·la si la comanda de kit de prova a casa no s’ha actualitzat mai.
L’objecte de perfil complet del pacient, incrustat en cada resposta d’una comanda de kit de prova a casa.
El panell associat a la comanda de kit de prova a casa — sempre exactament una entrada de
{ panel_id, added_at }, perquè un kit de prova a casa es correspon 1:1 amb un producte de kit
físic. Contrasta el panel_id amb Llista els panells.Biomarcadors associats a la comanda de kit de prova a casa fora del seu panell. Cada entrada és
{ biomarker_id, added_at }. Contrasta cada biomarker_id amb
Llista els biomarcadors amb home_kit=true. En una comanda
normal són proves a la carta afegides al panell; en un kit de substitució
són les que el laboratori torna a analitzar.La comanda de kit de prova a casa que substitueix aquesta, quan es tracta d’un
kit de substitució.
null en una comanda normal.Adreces que reben un correu electrònic cadascuna un cop tots els resultats de laboratori són
definitius, en minúscules. Sempre present — buit quan està desactivat. Configura’l a
Crea o Actualitza.
Consulta Correus electrònics de resultats a punt.
Els teus propis parells clau/valor, retornats literalment i mai interpretats per Aniva. Sempre
present en lectura —
{} si no n’has definit cap. Com a màxim 20 claus; les claus segueixen el
patró [A-Za-z0-9_-] i tenen com a màxim 40 caràcters; els valors són una cadena, un número o un
booleà, amb cadenes de 500 caràcters com a màxim; 16.384 bytes serialitzats en total. Les claus
que comencen per aniva_ estan reservades. A Actualitza,
les metadades es combinen: les claus que ometis es conserven, una clau enviada com a null
s’elimina i {} ho esborra tot. La validació és de tot o res. No posis mai dades personals ni
clíniques a metadata — no es tracten com a dades del pacient.El codi de mostra del laboratori. Un sol codi, tres funcions: el codi amb què s’informen els
resultats de laboratori, el que hi ha imprès al kit físic i el que el pacient llegeix a la caixa
com a codi d’activació. S’assigna quan s’empaqueta el kit —
null mentre la comanda és
pending, tret de després que Aniva reenviï un kit (consulta Cicle de vida).
Sempre de només lectura. Troba la comanda d’un kit que tinguis a mà amb
GET /api/v1/home-kit-orders?lab_code=….La marca de temps de recollida comunicada mitjançant
Activa — el moment en què el pacient va recollir
realment la mostra, com a instant UTC.
null fins que s’activa el kit. Aquesta és l’hora de
recollida que consta a l’informe de laboratori.Els paquets vinculats a aquesta comanda, del vincle més antic al més recent, cadascun
{ id, added_at } — el kit en camí cap al pacient i, en el cas dels kits amb seguiment del
trajecte de tornada, la mostra en camí de retorn cap al laboratori, que apareixen en el moment en
què s’imprimeixen les etiquetes. Buit mentre la comanda és pending, tret de després que Aniva
reenviï un kit. Llegeix els paquets complets en una sola crida amb
GET /api/v1/shipments?home_kit_order_id={id} — consulta Enviaments.Cicle de vida
Les comandes de kit de prova a casa exposen quatre estats del cicle de vida:
Quan Aniva torna a enviar un kit perdut, la comanda torna a
pending, però manté el seu lab_code i els
paquets anteriors a shipments. El kit nou porta el mateix codi. A la caixa nova s’hi posa una etiqueta de retorn
sense fer servir. Només Aniva fa aquests dos canvis; l’API no els ofereix. Cada canvi envia un
webhook home_kit_order.pending o home_kit_order.cancelled.
Els estats de la comanda de kit de prova a casa són intencionadament generals. El progrés del lliurament cap al pacient i de
tornada se segueix als enviaments de la comanda —
dispatched vol dir que el kit
té etiqueta i codi de laboratori, no que hagi sortit; el camp status de l’enviament d’anada indica si
ja s’ha mogut. El processament dels resultats de laboratori es fa a les trameses. L’estat dels resultats de laboratori (in_progress o
completed) s’exposa mitjançant Obtén els resultats — el camp
status de nivell superior és in_progress fins que es tanquen totes les trameses, i llavors passa a completed — o a fault quan
totes han fallat sense informar resultats.Seguiment dels paquets
destination és el laboratori), vinculats mitjançant paired_with. El
paquet de retorn queda en pending — amb el número de seguiment ja conegut — fins que el pacient
l’envia per correu. Un kit de microbioma intestinal arriba com un sol enviament: el kit al pacient. El sobre de retorn és
prepagat i sense seguiment, així que no es reserva res per a la tornada. booked_by indica qui ha reservat
l’etiqueta: "aniva" o "external". Aquí només es pot modificar un paquet "aniva", i només el camp
notes un cop impresa l’etiqueta. Cada paquet inclou totes les status_updates del transportista,
inclòs el detail_code de DHL per a una redirecció a una oficina de correus.
home_kit_orders a l’enviament només llista les comandes dins del teu context d’accés. Consulta
Accés.
Llistar les comandes de kits de prova a casa
Obtén totes les comandes de kits de prova a casa accessibles amb la teva clau API:?profile_id={uuid} per filtrar per un perfil concret, o ?lab_code={code} per
associar un kit físic que tens a la mà amb la seva comanda — el primer pas natural d’un flux d’activació.
Crear una comanda de kit de prova a casa
Sol·licita una comanda de kit de prova a casa per a un perfil de pacient:profile_id, una delivery_address i un únic panel_id. La comanda es crea en estat pending.
Passa una capçalera opcional Idempotency-Key perquè un reintent no demani un segon kit — consulta Idempotència.
Exactament un panell, perquè un kit de prova a casa correspon 1:1 a un producte de kit físic — el panell és el kit. Només es poden demanar els panells que Aniva ha configurat com a kits de prova a casa; qualsevol altre panell es rebutja amb un 422. És obligatori en crear la comanda perquè entra a la cua d’empaquetatge immediatament i l’empaquetatge pot començar de seguida. Mentre la comanda és pending, pots canviar el panell mitjançant Actualitza.
Per enviar un segon kit per un que no ha pogut donar els resultats, passa replaces_home_kit_order_id en lloc de triar un panell — consulta Kits de substitució.
Kits de substitució
De vegades un kit no pot donar els resultats: el pacient no ha pogut omplir el tub, la mostra ha arribat amb massa poc material o el laboratori no n’ha pogut analitzar una part. Demana’n una substitució:replaces_home_kit_order_id.
La comanda que substitueixes no es toca. Manté el seu estat, el codi de laboratori i tots els resultats ja registrats, de manera que si el pacient encara envia el primer kit per correu, rebrà tot el que el laboratori en pugui llegir.
El panell s’hereta. Si no inclous panel_id, la substitució porta el panell de la comanda que substitueix — és el que ha comprat el pacient i la marca que porta la caixa. Envia un panell diferent només per a una substitució de panell complet; un panell juntament amb un subconjunt de marcadors es rebutja amb un 422, perquè un subconjunt només té sentit dins del panell d’on s’ha triat. El panell d’una substitució tampoc no es pot canviar després.
Tu tries què es torna a analitzar. Envia biomarker_ids amb els marcadors que han fallat i el laboratori només tornarà a analitzar aquests, així el kit només inclou els tubs necessaris. No l’incloguis per tornar a analitzar tot el panell — l’opció adequada quan no s’ha analitzat res. Això no requereix cap scope addicional: tornar a analitzar marcadors que el pacient ja ha pagat no és una selecció a la carta. Aquests marcadors no es poden eliminar després, perquè constitueixen tota la sol·licitud.
Els marcadors es tornen a analitzar pels grups del panell, no un per un. Indicar un marcador d’un grup fa que es torni a analitzar
tot el grup, perquè no es pot fer una comanda de laboratori que informi de més del que s’ha demanat.
Per això, una substitució per a un sol marcador pot tornar amb més d’un resultat, i
el nombre de tubs pot ser més gran del que suggereix la llista de marcadors.
pending o dispatched, una segona creació per a la mateixa comanda retorna un 409 que l’indica. Els resultats arriben amb el lab_code propi de la substitució, a través del seu propi Obtén els resultats.
Una substitució no és la manera de gestionar un paquet que no ha arribat mai. Avisa Aniva: es tracta d’un reenviament de la mateixa comanda amb el mateix codi de laboratori, no d’una de nova.
Actualitzar una comanda de kit de prova a casa
Modifica l’adreça de lliurament, canvia el panell, actualitza les teves metadades o substitueix els correus electrònics d’avís de resultats disponibles:panel_id substitueix el panell associat — amb exactament un panell per kit, el canvi és l’única operació de panell que té sentit, i per això no hi ha endpoints per afegir o eliminar panells. L’adreça i el panell només es poden modificar mentre la comanda és pending; metadata continua sent editable durant tota la vida de la comanda. results_ready_emails continua sent editable fins que la comanda passa a cancelled.
Cancel·lar una comanda de kit de prova a casa
Cancel·la una comanda de kit de prova a casa que ja no cal:cancelled. La comanda de kit de prova a casa cancel·lada es retorna a la resposta.
Només es pot cancel·lar una comanda en pending. A partir de dispatched, el kit ja s’ha empaquetat i etiquetat — no hi ha retirada automàtica — i la crida retorna 409. Si cal aturar un kit que ja s’ha enviat, posa’t en contacte directament amb Aniva.
Cancel·lar una comanda en pending el kit de la qual ja s’ha demanat al centre logístic també el cancel·la allà, i la crida només té èxit si el centre logístic ho accepta:
409— el kit ja estava empaquetat i etiquetat, així que ja no es pot retirar, encara que la comanda continuï mostrantpending.502— el centre logístic ha rebutjat la cancel·lació (l’error n’inclou el motiu) o no s’hi ha pogut contactar. No s’ha canviat res — la comanda continua activa i es pot tornar a cancel·lar.
200 és l’única confirmació que no s’enviarà cap kit.
Cancel·lar una comanda que ja està en cancelled retorna el mateix 200, independentment de l’estat des del qual s’hagi cancel·lat.
Activar una comanda de kit de prova a casa
Quan el pacient hagi recollit la mostra, notifica-ho:activated_at — el moment en què el pacient ha recollit realment la mostra, com a instant UTC. Aquesta és l’hora de recollida que portarà l’informe del laboratori, així que envia el moment real de la recollida, no la teva hora de processament. L’activació és terminal: la comanda passa a activated i ja no es pot cancel·lar ni modificar. És l’equivalent en kit de prova a casa de Confirma l’extracció de sang, sense codi de barres — el codi del kit s’aplica quan s’empaqueta, així que mai no cal que el sàpigues. La comanda ja ha de tenir el seu lab_code en aquest punt; una comanda que no en tingui retorna 409.
L’activació també és el que fa la comanda al laboratori: el panell del kit es demana al laboratori amb el seu lab_code, de manera que la mostra retornada ja s’espera i els resultats s’adjunten a mesura que el laboratori els informa. Això s’executa després de la resposta, i qualsevol problema del laboratori el gestiona Aniva en lloc de mostrar-se a la teva petició.
Biomarcadors individuals
Pots adjuntar biomarcadors individuals a una comanda de kit de prova a casa com a proves a la carta, fora del panell. Això és útil quan vols una selecció a mida a més del kit. Els biomarcadors adjunts apareixen a la resposta de la comanda de kit de prova a casa com un arrayindividual_biomarkers (al mateix nivell que panels).
Els dos endpoints de biomarcadors requereixen el scope de capacitat home_kit_orders_individual_biomarker_selection a més de home_kit_orders_manage — els kits de prova a casa es demanen per panell, així que els marcadors a la carta s’activen per soci. Demana-ho a Aniva si la teva integració ho necessita.
Afegeix biomarcadors (idempotent — els biomarcadors ja vinculats es conserven):
biomarker_ids. Fes servir Llista els biomarcadors amb home_kit=true per trobar els ID de biomarcadors. Els biomarcadors només es poden canviar mentre el kit estigui en estat pending (consulta Cicle de vida).
Recuperació dels resultats de laboratori
Un cop el laboratori hagi processat la mostra retornada, recupera els resultats clínics i genètics:planned) juntament amb els resultats rebuts, perquè puguis fer el seguiment del que encara està pendent. Els resultats s’arxiven sota el lab_code de la comanda i arriben marcador per marcador a mesura que el laboratori els analitza, així que és normal rebre dades parcials. El camp status de nivell superior és in_progress fins a l’informe final, i després passa a completed (o fault quan totes les ordres de laboratori han fallat sense informe) — fes-lo servir per saber si la feina de laboratori de la comanda de kit de prova a casa ha acabat. Un webhook home_kit_order.results.completed t’avisa quan això passa, així que no cal que facis consultes periòdiques. Els PDF dels informes de laboratori es referencien a la matriu documents — fes servir GET /api/v1/documents/{id} per descarregar-los.