Saltar al contenido principal
Un pedido de kit de prueba en casa envía por correo al paciente un kit de pruebas para hacer por su cuenta. Aniva envía el kit, el paciente recoge la muestra en casa y la devuelve por correo. Esto se diferencia de una cita, que es una extracción de sangre venosa realizada por un profesional sanitario en un centro de pruebas físico.
Los endpoints de pedidos de kit de prueba en casa requieren el scope home_kit_orders_view (lectura) o home_kit_orders_manage (escritura). Activar también acepta el scope más restringido home_kit_orders_activate. Obtener resultados y Enviar resultados por correo requieren además results_view: los resultados de laboratorio y los documentos siempre están protegidos por este scope.

Campos

string
requerido
UUID generado automáticamente por Aniva. Úsalo para actualizar el pedido, cambiar su panel, activarlo, cancelarlo y obtener resultados.
string
requerido
El UUID del perfil al que pertenece este pedido de kit de prueba en casa.
string
requerido
Estado actual del ciclo de vida. Puede ser pending, dispatched, activated o cancelled. Consulta Ciclo de vida más abajo. El estado detallado de los resultados de laboratorio (in_progress o completed) se obtiene en Obtener resultados.
object
requerido
La dirección a la que se envía el kit por correo, con dos formatos posibles: {location_id}, que referencia un centro de pruebas conocido, o los campos de dirección directa (name, street, city, postal_code, country_code; company_name / house_number / address_line_2 / state / phone / email opcionales, con los mismos nombres que la API de ubicaciones). Indica exactamente uno: una referencia de ubicación o una dirección directa, nunca ambos.
Packstation o Postfiliale (solo en Alemania): define street como Packstation o Postfiliale, house_number con el número de estación de tres dígitos y address_line_2 con el DHL Postnummer del destinatario (6–10 dígitos, se admiten espacios). Sin el Postnummer, no se puede tramitar el envío del paquete. No se admite Postfach.
string
requerido
Marca de tiempo ISO 8601 de cuándo se creó el pedido de kit de prueba en casa.
string
Marca de tiempo ISO 8601 de la actualización más reciente. Nulo si el pedido de kit de prueba en casa nunca se ha actualizado.
object
El objeto completo del perfil del paciente, incluido en cada respuesta de pedido de kit de prueba en casa.
object[]
El panel asociado al pedido de kit de prueba en casa: siempre contiene exactamente una entrada { panel_id, added_at }, porque cada kit de prueba en casa corresponde 1:1 a un kit físico. Consulta panel_id en Listar paneles.
object[]
Biomarcadores asociados al pedido de kit de prueba en casa fuera de su panel. Cada entrada es { biomarker_id, added_at }. Consulta cada biomarker_id en Listar biomarcadores con home_kit=true. En un pedido normal son pruebas adicionales a la carta sobre el panel; en un kit de sustitución son las que el laboratorio vuelve a analizar.
string
El pedido de kit de prueba en casa al que sustituye, cuando se trata de un kit de sustitución. null en un pedido normal.
string
Motivo por el que se envió la sustitución, en una frase. null en un pedido normal.
string[]
Direcciones en minúsculas que reciben un correo cada una cuando todos los resultados de laboratorio son definitivos. Siempre presente; vacío cuando está desactivado. Configúralo en Crear o Actualizar. Consulta Correos de resultados listos.
object
Tus propios pares clave/valor, devueltos tal cual y nunca interpretados por Aniva. Siempre presente al leer: {} si no defines ninguno. Máximo 20 claves; las claves deben coincidir con [A-Za-z0-9_-] y tener como máximo 40 caracteres; los valores son cadenas, números o booleanos, con cadenas de hasta 500 caracteres; 16.384 bytes serializados en total. Las claves que empiezan por aniva_ están reservadas. En Actualizar, los metadatos se combinan: las claves que omitas se conservan, una clave enviada como null se elimina y {} lo borra todo. La validación es todo o nada. Nunca incluyas datos personales ni clínicos en metadata: no se tratan como datos del paciente.
string
El código de muestra de laboratorio. Un código, tres funciones: con el que se emiten los resultados de laboratorio, el que viene impreso en el kit físico y el que el paciente lee en la caja como código de activación. Se asigna al empaquetar el kit; es null mientras el pedido está en pending, salvo cuando Aniva reenvía un kit (consulta Ciclo de vida). Siempre de solo lectura. Encuentra el pedido de un kit físico con GET /api/v1/home-kit-orders?lab_code=….
string
La marca de tiempo de recogida indicada mediante Activar: cuándo recogió realmente el paciente su muestra, en formato UTC. null hasta que se activa el kit. Esta es la hora de recogida que figura en el informe de laboratorio.
object[]
Los paquetes vinculados a este pedido, del más antiguo al más reciente, cada uno con { id, added_at }: el kit de camino al paciente y, en los kits con seguimiento de devolución, la muestra de vuelta al laboratorio, que aparecen en cuanto se imprimen las etiquetas. Vacío mientras el pedido está en pending, salvo cuando Aniva reenvía un kit. Obtén los paquetes completos en una sola llamada con GET /api/v1/shipments?home_kit_order_id={id}; consulta Envíos.

Ciclo de vida

Los pedidos de kit de prueba en casa exponen cuatro estados de ciclo de vida:
Cuando Aniva reenvía un kit perdido, el pedido vuelve a pending, pero conserva su lab_code y sus paquetes anteriores en shipments. El nuevo kit lleva el mismo código. En la nueva caja se incluye una etiqueta de devolución sin usar. Solo Aniva realiza estos dos cambios; la API no los ofrece. Cada cambio envía un webhook home_kit_order.pending o home_kit_order.cancelled.
Los estados del pedido de kit de prueba en casa son deliberadamente generales. El progreso del envío hacia y desde el paciente se sigue en los envíos del pedido: dispatched significa que el kit tiene etiqueta y código de laboratorio, no que se haya movido; el status del envío de ida indica si lo ha hecho. El procesamiento de los resultados de laboratorio se gestiona en las solicitudes de laboratorio. El estado de finalización de los resultados (in_progress frente a completed) se consulta mediante Obtener resultados: el campo status de nivel superior es in_progress hasta que se cierra cada solicitud, momento en el que pasa a completed, o a fault si todas terminaron sin informar resultados.

Seguimiento de los paquetes

Lo que se devuelve depende del kit. Un kit de sangre aparece como dos envíos una vez que Aniva lo ha empaquetado: el paquete de Aniva al paciente y el del paciente al laboratorio (su destination es el laboratorio), emparejados mediante paired_with. El paquete de devolución permanece en pending —con su número de seguimiento ya asignado— hasta que el paciente lo envía. Un kit de microbioma intestinal aparece como un solo envío: el kit hacia el paciente. Su sobre de devolución es prepagado y sin seguimiento, por lo que no se registra nada para la vuelta. booked_by indica quién generó la etiqueta: "aniva" o "external". Aquí solo se puede modificar un paquete de "aniva", y únicamente sus notes una vez impresa la etiqueta. Cada paquete incluye todas las status_updates del transportista, incluido el detail_code de DHL en caso de desvío a una oficina de correos. home_kit_orders en el envío solo incluye los pedidos de tu contexto de acceso. Consulta Acceso.
La composición de un pedido de kit de prueba en casa solo se puede modificar mientras está en pending. Una vez que el pedido pasa a dispatched (o posterior: activated/cancelled), los cambios de panel y los endpoints /biomarkers devuelven 409 Conflict: el kit físico se empaqueta según el panel seleccionado, por lo que su contenido queda fijado en cuanto sale hacia el paciente. Si necesitas cambiar las pruebas de un pedido que ya está bloqueado, ponte en contacto directamente con Aniva: suele ser posible y haremos el cambio por ti para mantener la coherencia del contenido del kit. Si el kit ya se ha utilizado y no ha podido ofrecer resultados, pide en su lugar un kit de sustitución.

Listar pedidos de kits de prueba en casa

Obtén todos los pedidos de kits de prueba en casa accesibles con tu clave de API:
De forma opcional, pasa ?profile_id={uuid} para filtrar por un perfil concreto, o ?lab_code={code} para asociar un kit físico que tengas a mano con su pedido: el primer paso habitual de un flujo de activación.

Crear un pedido de kit de prueba en casa

Solicita un pedido de kit de prueba en casa para un perfil de paciente:
Pasa el profile_id, una delivery_address y un único panel_id. El pedido se crea en estado pending. Pasa una cabecera opcional Idempotency-Key para que un reintento no pida un segundo kit; consulta Idempotencia. Debe ser exactamente un panel, porque un kit de prueba en casa se corresponde 1:1 con un producto de kit físico: el panel es el kit. Solo se pueden pedir los paneles que Aniva haya configurado como kits de prueba en casa; cualquier otro panel se rechaza con 422. Es obligatorio al crearlo porque el pedido entra de inmediato en la cola de empaquetado y puede empezar a prepararse al instante. Mientras el pedido esté en pending, puedes cambiar el panel mediante Actualizar. Para enviar un segundo kit en lugar de uno que no pudo ofrecer resultados, pasa replaces_home_kit_order_id en vez de elegir un panel; consulta Kits de sustitución.

Kits de reemplazo

A veces un kit no puede ofrecer resultados: el paciente no pudo llenar el tubo, la muestra llegó con demasiado poco material o el laboratorio no pudo analizar una parte. Pide una sustitución:
Una sustitución es un nuevo pedido con un nuevo código de laboratorio, incluso cuando el primer kit nunca llegó a activarse: el laboratorio necesita una nueva solicitud y no se pueden distinguir dos muestras con el mismo código. Ambos pedidos siguen siendo legibles y quedan vinculados mediante replaces_home_kit_order_id. El pedido sustituido no se modifica. Conserva su estado, su código de laboratorio y cualquier resultado ya registrado en él, de modo que si el paciente acaba enviando el primer kit, recibirá lo que el laboratorio pueda analizar. El panel se hereda. Si omites panel_id, la sustitución lleva el panel del pedido al que sustituye: es lo que compró el paciente y el diseño que lleva la caja. Envía un panel distinto solo para sustituir un panel completo; enviar un panel y un subconjunto de marcadores a la vez se rechaza con 422, ya que un subconjunto solo tiene sentido dentro del panel del que se seleccionó. El panel de una sustitución tampoco se puede cambiar después. Tú eliges qué se vuelve a analizar. Envía biomarker_ids con los marcadores que fallaron y el laboratorio volverá a analizar solo esos, de modo que el kit se envía únicamente con los tubos necesarios. Omítelo para repetir el panel completo, que es la opción adecuada cuando no se analizó nada. Esto no requiere ningún scope adicional: repetir marcadores que el paciente ya pagó no es una selección a la carta. Esos marcadores no se pueden eliminar después, porque constituyen toda la solicitud.
Los marcadores se repiten por grupos del panel, no de uno en uno. Indicar un marcador de un grupo repite todo ese grupo, porque no se puede cursar una orden de laboratorio que informe más de lo solicitado. Por tanto, una sustitución para un solo marcador puede devolver más de un resultado y requerir más tubos de los que sugiere la lista de marcadores.
Solo puede haber una sustitución en curso por kit a la vez: mientras una sustitución esté en pending o dispatched, una segunda solicitud para el mismo pedido devuelve 409 indicándola. Los resultados llegan con el lab_code propio de la sustitución, a través de su propio Obtener resultados. Una sustitución no es la forma de gestionar un paquete que nunca llegó. En ese caso, avisa a Aniva: se trata de un reenvío del mismo pedido con el mismo código de laboratorio, no de uno nuevo.

Actualizar un pedido de kit de prueba en casa

Cambia la dirección de entrega, sustituye el panel, actualiza tus metadatos o reemplaza los correos de aviso de resultados disponibles:
Incluye solo los campos que quieras cambiar. panel_id sustituye el panel asociado: al haber exactamente un panel por kit, el cambio es la única operación de panel con sentido, por lo que no existen endpoints para añadir o eliminar paneles. La dirección y el panel solo se pueden modificar mientras el pedido está en pending; metadata se puede editar durante toda la vida del pedido. results_ready_emails se puede editar hasta que el pedido pase a cancelled.

Cancelar un pedido de kit de prueba en casa

Cancela un pedido de kit de prueba en casa que ya no sea necesario:
Esto cambia el estado del pedido de kit de prueba en casa a cancelled. La respuesta devuelve el pedido cancelado. Solo se puede cancelar un pedido en pending. A partir de dispatched, el kit ya está empaquetado y etiquetado —no existe retirada automática— y la llamada devuelve 409. Si necesitas detener un kit que ya ha salido, ponte en contacto directamente con Aniva. Cancelar un pedido en pending cuyo kit ya se haya solicitado al centro logístico también lo cancela allí, y la llamada solo tiene éxito si el centro logístico la acepta:
  • 409 — el kit ya estaba empaquetado y etiquetado, así que ya no se puede retirar, aunque el pedido aún aparezca en pending.
  • 502 — el centro logístico rechazó la cancelación (el error incluye el motivo) o no se pudo contactar con él. No se ha modificado nada: el pedido sigue activo y puedes volver a cancelarlo.
Una cancelación que devuelve error deja el pedido exactamente como estaba, así que un 200 es la única confirmación de que no se enviará ningún kit. Cancelar un pedido que ya está en cancelled devuelve el mismo 200, con independencia del estado desde el que se canceló.

Activar un pedido de kit de prueba en casa

Cuando el paciente haya recogido su muestra, notifícalo:
Pasa activated_at: el momento real en que el paciente recogió la muestra, como instante UTC. Esta es la hora de recogida que aparecerá en el informe de laboratorio, así que envía el momento real de la recogida, no tu hora de procesamiento. La activación es definitiva: el pedido pasa a activated y ya no se puede cancelar ni modificar. Es el equivalente para kits de prueba en casa de Confirmar extracción de sangre, sin código de barras: el código del kit se aplica al empaquetarlo, así que nunca necesitas conocerlo. Para entonces, el pedido debe tener su lab_code; un pedido sin él devuelve 409. La activación es también lo que cursa la orden de laboratorio: el panel del kit se solicita al laboratorio con su lab_code, de modo que la muestra devuelta queda esperada y los resultados se asocian a medida que el laboratorio los informa. Esto se ejecuta después de la respuesta, y cualquier incidencia en el laboratorio la gestiona Aniva en lugar de reflejarse en tu petición.

Biomarcadores individuales

Puedes añadir biomarcadores individuales a un pedido de kit de prueba en casa como pruebas a la carta, fuera del panel. Esto resulta útil cuando quieres una selección a medida además del kit. Los biomarcadores añadidos aparecen en la respuesta del pedido como un array individual_biomarkers (al mismo nivel que panels). Ambos endpoints de biomarcadores requieren el scope de capacidad home_kit_orders_individual_biomarker_selection además de home_kit_orders_manage: los kits de prueba en casa se piden por panel, así que los marcadores a la carta se activan por partner. Pregunta a Aniva si tu integración lo necesita. Añade biomarcadores (idempotente: los biomarcadores ya asociados se conservan):
Eliminar biomarcadores (idempotente: un ID que no esté asociado se ignora):
Ambos endpoints aceptan un array biomarker_ids. Usa Listar biomarcadores con home_kit=true para consultar los ID de biomarcadores. Los biomarcadores solo se pueden cambiar mientras el kit esté en pending (consulta Ciclo de vida).

Obtener resultados de laboratorio

Una vez que el laboratorio haya procesado la muestra devuelta, obtén los resultados clínicos y genéticos:
La respuesta incluye las pruebas planificadas (estado planned) junto con los resultados recibidos, para que puedas seguir qué queda pendiente. Los resultados se registran bajo el lab_code del pedido y llegan marcador a marcador a medida que el laboratorio los analiza, así que es normal recibir payloads parciales. El campo status de nivel superior es in_progress hasta el informe final, y luego completed (o fault cuando todas las órdenes de laboratorio fallan sin informar): úsalo para saber si el trabajo de laboratorio del pedido de kit de prueba en casa ha terminado. Un webhook home_kit_order.results.completed te avisa cuando esto ocurre, así que no necesitas hacer polling. Los PDF de los informes de laboratorio se referencian en el array documents: usa GET /api/v1/documents/{id} para descargarlos.

Ejemplo de pedido de kit de prueba en casa