> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anivahealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Crear pedido de kit de prueba en casa

> Solicitar un kit de prueba en casa por correo para un perfil

Solicita un pedido de kit de prueba en casa para un perfil de paciente. Un pedido de kit de prueba en casa envía un kit de prueba por correo para hacer en casa: Aniva envía el kit a la dirección de entrega, el paciente se toma la muestra en casa y la devuelve por correo. Esto es distinto de una [cita](https://docs.anivahealth.com/es/api/appointments/create-appointment.md), que es una extracción de sangre venosa en un centro de pruebas.

**Se requiere exactamente un panel.** Un kit de prueba en casa se corresponde 1:1 con un producto de kit físico —el panel es el kit— y el pedido entra en la cola de empaquetado en cuanto se crea, por lo que la composición debe ser definitiva desde el principio. Aun así, puedes cambiar el panel mediante [Actualizar pedido de kit de prueba en casa](https://docs.anivahealth.com/es/api/home-kit-orders/update-home-kit.md) mientras el pedido esté en `pending`.

## Kits de reemplazo

Cuando un kit no pueda dar sus resultados —el paciente no pudo llenar el tubo, la muestra llegó con muy poco material, el laboratorio no pudo analizarla—, pide un **reemplazo** enviando `replaces_home_kit_order_id`.

Un reemplazo es un pedido nuevo con un nuevo código de laboratorio, incluso cuando el primer kit nunca se activó: el laboratorio necesita una nueva solicitud y no se pueden distinguir dos muestras bajo un mismo código. El pedido que reemplazas no se modifica: mantiene su propio estado, su propio código de laboratorio y cualquier resultado que ya esté registrado en él.

Esto implica dos cosas:

* **El panel se hereda.** Omite `panel_id` y el reemplazo llevará el panel del pedido al que reemplaza, que es lo que compró el paciente y la marca que lleva la caja.
* **Tú eliges qué se vuelve a analizar.** Envía `biomarker_ids` con los marcadores que fallaron y el laboratorio volverá a analizar solo esos, para que el kit se envíe solo con los tubos necesarios. Omítelo para volver a analizar el panel completo.

Los marcadores se vuelven a analizar según los grupos del panel, no uno por uno. Indicar un marcador de un grupo hace que se vuelva a analizar todo ese grupo, porque no se puede hacer un pedido de laboratorio que informe más de lo solicitado. Por tanto, un reemplazo de un solo marcador puede llegar con más de un resultado, y el número de tubos puede ser mayor de lo que sugiere la lista de marcadores.

Solo puede haber un reemplazo en camino por kit a la vez.

> [!NOTE]
>
> Si hiciste la integración antes de que existieran estos campos, Aniva también lee
> `metadata.original_kit_id` y `metadata.replacement_reason` al crear un pedido y lo trata como un
> reemplazo. Este es el único lugar donde se interpretan los metadatos, existe solo para mantener
> esa integración anterior y los campos de arriba siempre prevalecen. Envía los campos.

Un `201` significa que el pedido está confirmado y se pasará a logística: no tienes que hacer nada más para que el kit se empaquete y se envíe.

Requiere el scope `home_kit_orders_manage`.

Envía una cabecera opcional `Idempotency-Key` para que esta creación se pueda reintentar con seguridad: repetir la misma clave devuelve la respuesta original en lugar de crear otra. Consulta [Idempotencia](https://docs.anivahealth.com/es/concepts/idempotency.md).

## Solicitud

### Parámetros del cuerpo

**profile\_id** `string` *required*

UUID del perfil de paciente para el que se crea el pedido de kit de prueba en casa.

**panel\_id** `string` *required*

UUID del panel del catálogo que se va a pedir. Exactamente uno: un kit de prueba en casa se
corresponde 1:1 con un producto de kit físico, así que el panel es el kit. Aniva proporciona los
ID de panel para tu cuenta de partner; consulta [Listar
paneles](https://docs.anivahealth.com/es/api/panels/list-panels.md). Opcional en un reemplazo, donde toma por defecto el panel del
pedido que reemplazas.

**replaces\_home\_kit\_order\_id** `string`

UUID del pedido de kit de prueba en casa al que este reemplaza. Enviarlo convierte este pedido en
un kit de reemplazo; consulta [Kits de reemplazo](#kits-de-reemplazo) más arriba. El pedido debe
pertenecer al mismo perfil y no debe tener ya un reemplazo en camino.

**replacement\_reason** `string`

Motivo por el que se necesita el reemplazo, en una frase (por ejemplo, `Zu wenig Material, HbA1c nicht
    auswertbar`). Obligatorio cuando envías `replaces_home_kit_order_id`, e ignorado en caso
contrario. Máximo 500 caracteres.

**biomarker\_ids** `integer[]`

En un reemplazo, los marcadores que el laboratorio vuelve a analizar, normalmente los que el
primer kit no pudo dar. Cada uno debe formar parte de lo que pidió el pedido que reemplazas;
contrasta con [Listar biomarcadores](https://docs.anivahealth.com/es/api/biomarkers/list-biomarkers.md) con `home_kit=true`.
Omítelo para volver a analizar el panel completo. Solo se acepta junto con
`replaces_home_kit_order_id`, y no junto con un `panel_id` distinto. Esto no necesita ningún
scope adicional: volver a analizar marcadores que el paciente ya pagó no es una selección a la
carta.

**metadata** `object`

Tus propios pares clave/valor, que se devuelven literalmente en cada lectura y Aniva nunca
interpreta. Úsalo para incluir tu referencia de pedido y así poder relacionarlos sin guardar
nuestros ID. Máximo 20 claves; las claves deben coincidir con `[A-Za-z0-9_-]` y tener como máximo
40 caracteres; los valores pueden ser una cadena, un número o un booleano, con cadenas de 500
caracteres como máximo; 16.384 bytes serializados en total. Las claves que empiezan por `aniva_`
están reservadas. Nunca incluyas datos personales ni clínicos en `metadata`: no se trata como
datos de paciente.

**results\_ready\_emails** `string[]`

Hasta 5 direcciones que reciben un correo cada una cuando todos los resultados de laboratorio son
definitivos. El correo enlaza a la página de resultados en el panel de administración de Aniva. Tu
clave necesita acceso `results_view` al paciente; si no, devuelve `403`. Omítelo para usar las
direcciones predeterminadas del grupo del paciente. Una lista vacía desactiva los correos.
Consulta [Correos de resultados listos](https://docs.anivahealth.com/es/concepts/results.md#correos-de-resultados-listos).

**delivery\_address** `object` *required*

La dirección a la que se envía el kit por correo, con uno de estos dos formatos: o bien `{ location_id }` haciendo referencia a un centro de pruebas conocido, o bien los campos de dirección en línea (`name`, `street`, `city`, `postal_code`, `country_code`; `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` opcionales, el mismo vocabulario que la API de ubicaciones). Indica exactamente uno: una referencia a una ubicación o una dirección en línea, no ambos.

**dirección de entrega**

> [tab] Referenciar una ubicación
>
> **location\_id** `string` *required*
>
> UUID de un centro de pruebas conocido al que enviar el kit. Relaciónalo con [Listar
> ubicaciones](https://docs.anivahealth.com/es/api/locations/list-locations.md).

> [tab] Dirección en línea
>
> **name** `string` *required*
>
> Nombre del destinatario, de la empresa o de la ubicación.
>
> **company\_name** `string`
>
> Empresa que recibe el paquete en nombre del destinatario: un tercero `c/o` o un departamento.
>
> **street** `string` *required*
>
> Nombre de la calle, sin el número (p. ej., `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Número de la calle (p. ej., `118` o `12a`).
>
> **address\_line\_2** `string`
>
> Edificio, portal o planta.
>
> **city** `string` *required*
>
> **state** `string`
>
> Estado o provincia. Opcional.
>
> **postal\_code** `string` *required*
>
> Código postal. Una dirección alemana (`country_code` `DE`) necesita exactamente 5 dígitos, p. ej., `10117`.
>
> **country\_code** `string` *required*
>
> Código ISO 3166-1 alfa-2 (dos letras, p. ej., `DE`). Se aceptan minúsculas y se guarda en
> mayúsculas.
>
> **phone** `string`
>
> Número de teléfono del destinatario, con prefijo internacional (p. ej., `+4791234567`). El
> transportista lo usa para avisar al destinatario sobre el paquete, por ejemplo, si le espera
> en un punto de recogida. Si lo omites, el transportista no recibe ningún número de teléfono.
>
> **email** `string`
>
> Correo electrónico del destinatario. El transportista lo usa igual que `phone`. Si lo
> omites, el transportista no recibe ningún correo electrónico.

> [!NOTE]
>
> **Packstation o Postfiliale (solo Alemania):** establece `street` como `Packstation` o
> `Postfiliale`, `house_number` como el número de estación de tres dígitos y `address_line_2` como
> el Postnummer de DHL del destinatario (6–10 dígitos, se permiten espacios). Sin el Postnummer, no
> se puede reservar el envío del paquete. No se admite un Postfach.

## Respuesta

Si tiene éxito, la API devuelve `201 Created` con el nuevo pedido de kit de prueba en casa.

**id** `string` *required*

Identificador único del pedido de kit de prueba en casa (UUID).

**profile\_id** `string` *required*

UUID del perfil al que pertenece este pedido de kit de prueba en casa.

**status** `string` *required*

Estado actual del pedido de kit de prueba en casa. Puede ser `pending`, `dispatched`, `activated`
o `cancelled`. Un pedido recién creado empieza en `pending`.

**delivery\_address** `object` *required*

La dirección a la que se envía el kit, con uno de estos dos formatos: `{ location_id }` para referenciar una ubicación de pruebas conocida, o los campos de dirección en línea (`name`, `street`, `city`, `postal_code`, `country_code`; `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` opcionales, con el mismo vocabulario que la API de ubicaciones). Indica exactamente uno: una referencia de ubicación o una dirección en línea, no ambos.

**dirección de entrega**

> [tab] Referencia de ubicación
>
> **location\_id** `string` *required*
>
> UUID de la ubicación de pruebas a la que se envía el kit.

> [tab] Dirección en línea
>
> **name** `string` *required*
>
> Nombre del destinatario, la empresa o la ubicación.
>
> **company\_name** `string`
>
> Empresa que recibe el paquete para el destinatario: un destinatario `c/o` o un departamento.
>
> **street** `string` *required*
>
> Nombre de la calle, sin el número (p. ej., `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Número de la calle (p. ej., `118` o `12a`).
>
> **address\_line\_2** `string`
>
> Edificio, portal o piso.
>
> **city** `string` *required*
>
> **state** `string`
>
> Estado o provincia. Opcional.
>
> **postal\_code** `string` *required*
>
> **country\_code** `string` *required*
>
> Código ISO 3166-1 alfa-2 (dos letras, p. ej., `DE`).
>
> **phone** `string`
>
> **email** `string`

**metadata** `object` *required*

Los pares clave/valor que proporcionaste. Siempre presente: `{}` si no indicaste ninguno.

**replaces\_home\_kit\_order\_id** `string`

El pedido de kit de prueba en casa al que este reemplaza. `null` en un pedido normal.

**replacement\_reason** `string`

El motivo que proporcionaste. `null` en un pedido normal.

**results\_ready\_emails** `string[]` *required*

Direcciones que reciben un correo cada una cuando todos los resultados de laboratorio son definitivos, en minúsculas. Vacío cuando está desactivado. Consulta
[Correos de resultados listos](https://docs.anivahealth.com/es/concepts/results.md#correos-de-resultados-listos).

**lab\_code** `string`

Código de muestra de laboratorio bajo el que se notifican los resultados: viene impreso en el kit físico y es lo que el
paciente lee en la caja como código de activación. `null` hasta que se empaqueta el kit.
Solo lectura.

**activated\_at** `string` *required*

Marca temporal de la recogida comunicada mediante [Activar](https://docs.anivahealth.com/es/api/home-kit-orders/activate-home-kit.md). `null` hasta
que se active el kit.

**created\_at** `string` *required*

Marca de tiempo ISO 8601 de cuándo se creó el pedido de kit de prueba en casa.

**updated\_at** `string`

Marca de tiempo ISO 8601 de la última actualización. Puede ser `null`.

**profile** `object` *required*

El perfil de paciente asociado a este pedido de kit de prueba en casa.

**perfil**

**id** `string`

Identificador único del perfil (UUID).

**handle** `string`

Alias o nombre de usuario del perfil. Puede ser `null`.

**first\_name** `string`

Nombre. Puede ser `null`.

**last\_name** `string`

Apellido. Puede ser `null`.

**email** `string`

Dirección de correo electrónico. Puede ser `null`.

**phone** `string`

Número de teléfono en formato E.164. Puede ser `null`.

**sex** `integer`

Sexo biológico según ISO/IEC 5218. Puede ser `null`.

**date\_of\_birth** `string`

Fecha de nacimiento en formato `YYYY-MM-DD`. Puede ser `null`.

**height** `number`

Altura en centímetros. Puede ser `null`.

**weight** `number`

Peso en kilogramos. Puede ser `null`.

**language** `string`

Idioma preferido: uno de los 32 códigos en [Crear perfil](https://docs.anivahealth.com/es/api/profiles/create-profile.md).

**transactional\_emails\_enabled** `boolean`

Indica si este perfil recibe correos transaccionales (programáticos). Puede ser `null`.

**created\_at** `string`

Marca de tiempo ISO 8601 de cuándo se creó el perfil.

**updated\_at** `string`

Marca de tiempo ISO 8601 de la última actualización del perfil. Puede ser `null`.

**panels** `HomeKitOrderPanel[]` *required*

El panel asociado a este pedido de kit de prueba en casa: el que proporcionaste en `panel_id`,
con la marca temporal de creación del pedido. Siempre es exactamente uno. Consulta los detalles
del panel (nombre, biomarcadores) mediante [Listar paneles](https://docs.anivahealth.com/es/api/panels/list-panels.md).

**Campos de vinculación del panel**

**panel\_id** `string`

UUID del panel: consúltalo en [Listar paneles](https://docs.anivahealth.com/es/api/panels/list-panels.md).

**added\_at** `string`

Marca de tiempo ISO 8601 en la que se vinculó por primera vez el panel a este pedido de kit de prueba en casa.

**individual\_biomarkers** `HomeKitOrderIndividualBiomarker[]` *required*

Biomarcadores asociados fuera del panel. Vacío en una creación normal: los pedidos de kit de
prueba en casa se piden por panel, y modificar esta lista después requiere el scope de capacidad
`home_kit_orders_individual_biomarker_selection`. En un reemplazo contiene los `biomarker_ids` que
enviaste, que son los que el laboratorio vuelve a analizar.

**Campos de biomarcadores individuales**

**biomarker\_id** `integer`

Identificador del biomarcador: consúltalo en
[Listar biomarcadores](https://docs.anivahealth.com/es/api/biomarkers/list-biomarkers.md) con `home_kit=true`.

**added\_at** `string`

Marca de tiempo ISO 8601 en la que se vinculó por primera vez el biomarcador a este pedido de kit de prueba en casa.

**shipments** `HomeKitOrderShipmentLink[]` *required*

Paquetes vinculados a este pedido de kit de prueba en casa, empezando por el vínculo más antiguo.
Siempre vacío al crear el pedido: consulta los paquetes completos con [Listar
envíos](https://docs.anivahealth.com/es/api/shipments/list-shipments.md) y `?home_kit_order_id=`.

**Campos de enlace de envío**

**id** `string`

Referencia del envío: consúltala en [Obtener envío](https://docs.anivahealth.com/es/api/shipments/get-shipment.md).

**added\_at** `string`

Marca de tiempo ISO 8601 en la que se vinculó el envío a este pedido de kit de prueba en casa.

## Respuestas de error

| Estado | Descripción |
| - | - |
| `400` | Error de validación: p. ej., falta un campo en `delivery_address` o contiene un código postal alemán que no tiene 5 dígitos, `panel_id` no es un UUID válido o falta `replacement_reason` en un reemplazo. |
| `403` | Prohibido: tu clave de API no tiene acceso a esta operación, el perfil está fuera de tu ámbito de permisos o has establecido `results_ready_emails` sin acceso `results_view` al paciente. |
| `404` | No se ha encontrado el perfil, el panel o el pedido de kit de prueba en casa que se va a reemplazar. |
| `409` | Conflicto: la clave `Idempotency-Key` ya se usó con un cuerpo distinto, su solicitud original aún no ha finalizado o el kit que estás reemplazando ya tiene un reemplazo en camino. |
| `422` | El panel no se puede pedir como kit de prueba en casa: no hay ningún producto de kit de logística configurado para él. En un reemplazo: el pedido que reemplazas pertenece a otro perfil, una entrada de `biomarker_ids` no forma parte de lo que se pidió o has enviado marcadores junto con un `panel_id` distinto. |
| `500` | Error interno del servidor. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/home-kit-orders \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
    "metadata": { "your_order_ref": "ORD-10482", "priority": true },
    "delivery_address": {
      "name": "Maria Schmidt",
      "company_name": "c/o Weber",
      "street": "Friedrichstraße",
      "house_number": "123",
      "postal_code": "10117",
      "city": "Berlin",
      "country_code": "DE",
      "phone": "+4930123456789",
      "email": "maria.schmidt@example.com"
    }
  }'
```

```bash Replacement kit theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/home-kit-orders \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "replaces_home_kit_order_id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
    "replacement_reason": "Too little material, HbA1c could not be analysed",
    "biomarker_ids": [103],
    "metadata": { "your_order_ref": "ORD-10482-R1" },
    "delivery_address": {
      "name": "Maria Schmidt",
      "street": "Friedrichstraße",
      "house_number": "123",
      "postal_code": "10117",
      "city": "Berlin",
      "country_code": "DE"
    }
  }'
```

```json 201 theme={null}
{
  "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
  "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
  "status": "pending",
  "delivery_address": {
    "name": "Maria Schmidt",
    "company_name": "c/o Weber",
    "address_line_2": null,
    "street": "Friedrichstraße",
    "house_number": "123",
    "postal_code": "10117",
    "city": "Berlin",
    "country_code": "DE",
    "phone": "+4930123456789",
    "email": "maria.schmidt@example.com"
  },
  "created_at": "2026-04-01T09:45:00Z",
  "updated_at": null,
  "profile": {
    "id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "handle": null,
    "first_name": "Maria",
    "last_name": "Schmidt",
    "email": "maria.schmidt@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1985-03-22",
    "height": 168,
    "weight": 65,
    "language": "de",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:14:32Z",
    "updated_at": null
  },
  "panels": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T09:45:00Z"
    }
  ],
  "individual_biomarkers": [],
  "metadata": { "your_order_ref": "ORD-10482", "priority": true },
  "replaces_home_kit_order_id": null,
  "replacement_reason": null,
  "results_ready_emails": [],
  "lab_code": null,
  "activated_at": null,
  "shipments": []
}
```

```json 400 theme={null}
{
  "error": "panel_id: panel_id must be a valid UUID"
}
```

```json 404 theme={null}
{
  "error": "Profile not found"
}
```

```json 409 theme={null}
{
  "error": "Idempotency-Key \"ORD-10482\" was already used with a different request body. Use a new key for a different request, or resend the original body to read back its result."
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.