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
UUID generado automáticamente por Aniva. Úsalo para actualizar el pedido, cambiar su panel, activarlo,
cancelarlo y obtener resultados.
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.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.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.
El objeto completo del perfil del paciente, incluido en cada respuesta de pedido de kit de prueba en casa.
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.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.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.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.
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.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=….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.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
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.
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:?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: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: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.
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: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: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 enpending.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.
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: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 arrayindividual_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):
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: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.