Saltar al contingut principal
Una comanda de kit de prova a casa envia un kit de prova per correu a un pacient perquè el faci servir a casa. Aniva envia el kit, el pacient recull la mostra a casa ell mateix i la retorna per correu. Això es diferencia d’una cita, que és una extracció de sang venosa feta per un professional sanitari en una ubicació de proves física.
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

string
requerit
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.
string
requerit
L’UUID del perfil al qual pertany aquesta comanda de kit de prova a casa.
string
requerit
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.
object
requerit
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.
string
requerit
Marca de temps ISO 8601 de quan es va crear la comanda de kit de prova a casa.
string
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.
object
L’objecte de perfil complet del pacient, incrustat en cada resposta d’una comanda de kit de prova a casa.
object[]
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.
object[]
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.
string
La comanda de kit de prova a casa que substitueix aquesta, quan es tracta d’un kit de substitució. null en una comanda normal.
string
Motiu pel qual s’ha enviat la substitució, en una frase. null en una comanda normal.
string[]
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.
object
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.
string
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=….
string
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.
object[]
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

El que es retorna depèn del kit. Un kit de sang arriba com dos enviaments un cop Aniva l’ha empaquetat: el paquet d’Aniva al pacient, i el del pacient al laboratori (la seva 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.
La composició d’una comanda de kit de prova a casa només es pot canviar mentre està en pending. Un cop la comanda passa a dispatched (o més endavant — activated/cancelled), els canvis de panell i els endpoints de /biomarkers retornen 409 Conflict: el kit físic s’empaqueta segons el panell seleccionat, de manera que el contingut queda fixat en el moment que surt cap al pacient. Si necessites canviar les proves d’una comanda que ja està bloquejada, posa’t en contacte directament amb Aniva — normalment encara és possible i farem el canvi per tu per mantenir la coherència del contingut del kit. Si el kit ja s’ha fet servir i no ha pogut donar els resultats, demana un kit de substitució.

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:
Opcionalment, passa ?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:
Passa el 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ó:
Una substitució és una comanda nova amb un codi de laboratori nou, fins i tot quan el primer kit no s’ha arribat a activar: el laboratori necessita una sol·licitud nova i dues mostres amb un mateix codi no es poden distingir. Totes dues comandes continuen sent llegibles, enllaçades mitjançant 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.
Només hi pot haver una substitució en camí alhora per cada kit — mentre una substitució està en 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:
Inclou només els camps que vulguis canviar. 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:
Això estableix l’estat de la comanda de kit de prova a casa a 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ï mostrant pending.
  • 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.
Una cancel·lació que retorna un error deixa la comanda exactament com estava, de manera que un 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:
Passa 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 array individual_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):
Elimina biomarcadors (idempotent — un ID que no estigui vinculat s’ignora):
Els dos endpoints reben una matriu 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:
La resposta inclou les proves previstes (estat 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.

Exemple de comanda de kit de prova a casa