> ## 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 envío

> Crear una orden de envío logístico con origen y destino especificados

Crea una orden de envío desde la ubicación de origen especificada. Indicas el laboratorio de destino con `destination_lab`. El envío va a la dirección de envío registrada de ese laboratorio.

Requiere el scope `shipments_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

**location\_id** `string` *required*

UUID de la ubicación de pruebas de origen. La ubicación debe estar activa y dentro del contexto de
acceso de tu clave de API. Usa [Listar ubicaciones](https://docs.anivahealth.com/es/api/locations/list-locations.md) para encontrar
los ID de ubicación disponibles.

**destination\_lab** `string` *required*

Laboratorio de destino. Uno de `zotzklimas`, `labclinic`, `nordicgroup`, `biomes`, `imd` o
`quade`. El envío va a la dirección de envío registrada para este laboratorio. Un laboratorio sin
dirección de envío registrada devuelve `400`.

**appointment\_id** `string`

UUID de cita opcional al que vincular este envío al crearlo. La cita debe estar dentro del
contexto de acceso de tu clave de API. El vínculo aparece directamente como una entrada en el
array `appointments` del envío y, de forma recíproca, como una entrada en el array `shipments` de
la cita. Para vincular más citas tras la creación o eliminar el vínculo inicial, usa [Vincular
citas al envío](https://docs.anivahealth.com/es/api/shipments/attach-appointments-to-shipment.md) y [Desvincular citas del
envío](https://docs.anivahealth.com/es/api/shipments/detach-appointments-from-shipment.md).

**pickup\_date** `string` *required*

Fecha de recogida en formato `YYYY-MM-DD` (p. ej., `2026-04-15`), interpretada en la zona horaria
de la ubicación de origen. Debe ser un día laborable (de lunes a viernes), hoy o en el futuro.
Las recogidas en el mismo día no están disponibles después de las 16:00 Europe/Berlin.

**pickup\_time\_from** `string` *required*

Hora más temprana de recogida en formato `HH:MM` (p. ej., `09:00`), interpretada como hora local
en la zona horaria de la ubicación de origen. Debe estar entre `09:00` y `19:00`.

**pickup\_time\_till** `string` *required*

Hora límite de recogida en formato `HH:MM` (p. ej., `12:00`), interpretada como hora local en la
zona horaria de la ubicación de origen. Debe estar entre `09:00` y `19:00`. La franja
(`pickup_time_till -
    pickup_time_from`) debe ser de al menos 2 horas.

**package\_count** `integer` (default: 1)

Número de paquetes. Por defecto, `1`.

**weight** `number` (default: 0.5)

Peso en kg. Por defecto, `0.5`.

**pickup\_remarks** `string`

Instrucciones para el mensajero en la recogida (observaciones del remitente). Si se omite, se
usan las observaciones guardadas de la dirección de recogida (o ninguna si la dirección no tiene).
Máximo 128 caracteres.

**contents** `string`

Descripción en texto libre del contenido del paquete, que se muestra al mensajero y se devuelve
como `contents`. Máximo 40 caracteres (p. ej., `Medizinisch freigestellte Probe`).

**notes** `string`

Notas internas opcionales. Máximo 128 caracteres.

## Respuesta

Si tiene éxito, la API devuelve `201 Created` con el nuevo envío.

**id** `string` *required*

Identificador de referencia del envío (p. ej., `P2604151234`).

**status** `string` *required*

Estado del ciclo de vida del envío. Uno de `pending`, `in_transit`, `delivered`, `fault` o `cancelled`.

**logistics\_provider** `string` *required*

Proveedor logístico. Puede ser `go`, `dhl_parcel`, `dhl_warenpost`, `rotrunner`, `rapido`,
`ups` o `dhl_express`. Un paquete de kit a domicilio es `dhl_parcel`, o `dhl_warenpost` cuando se envía al extranjero
como Warenpost International.

**tracking\_number** `string`

Número de seguimiento externo del proveedor logístico. Puede ser `null`.

**contents** `string`

Descripción en texto libre del contenido del paquete, tal como se indicó al crearlo. Puede ser `null`.

**booked\_by** `string` *required*

Quién imprimió la etiqueta: `aniva` o `external`. Un envío creado por ti es `aniva`.

**paired\_with** `string`

Referencia del otro paquete en un envío de dos paquetes. Es `null` para un paquete solo de ida.

**origin** `object`

Dirección de recogida. Puede ser `null`.

**objeto de dirección**

**name** `string` *required*

Nombre del destinatario, la empresa o la ubicación.

**company\_name** `string`

Línea de empresa / a la atención de. Puede ser `null`.

**street** `string` *required*

Nombre de la calle, sin el número.

**house\_number** `string`

Número de portal. Puede ser `null`.

**address\_line\_2** `string`

Edificio, entrada o planta. Puede ser `null`.

**city** `string` *required*

Ciudad.

**state** `string`

Estado o provincia. Puede ser `null`.

**postal\_code** `string` *required*

Código postal.

**country\_code** `string` *required*

Código de país ISO 3166-1 alfa-2.

**phone** `string`

Teléfono de contacto. Puede ser `null`.

**email** `string`

Correo electrónico de contacto. Puede ser `null`.

**destination** `object`

Dirección de entrega. Misma estructura que `origin`. Puede ser `null`.

**pickup** `object`

Franja de recogida programada. Puede ser `null`.

**Objeto pickup**

**from** `string` *required*

Inicio de la franja de recogida como instante UTC (ISO 8601 con sufijo `Z`).

**till** `string` *required*

Fin de la franja de recogida como instante UTC (ISO 8601 con sufijo `Z`).

**timezone** `string` *required*

Zona horaria IANA del lugar de recogida (p. ej., `Europe/Berlin`). Úsala para mostrar `from` / `till` en la hora local del lugar de recogida.

**notes** `string`

Notas opcionales. Puede ser `null`.

**status\_updates** `object[]` *required*

Eventos cronológicos del ciclo de vida del proveedor logístico (del más antiguo al más reciente).
Cada entrada tiene `state`, `code`, `detail_code`, `status`, `description`, `location` y `time`.
Consulta [Obtener envío](https://docs.anivahealth.com/es/api/shipments/get-shipment.md) para cada campo. Array vacío justo tras la
creación. La sincronización en segundo plano añade eventos a medida que el proveedor los notifica.

**appointments** `ShipmentAppointmentLink[]` *required*

Citas vinculadas a este envío, del vínculo más antiguo al más reciente. Cada entrada es
`{ id, added_at }`; consulta cada `id` en [Obtener cita](https://docs.anivahealth.com/es/api/appointments/get-appointment.md).
Contiene la cita pasada mediante `appointment_id` (si la hay) justo tras la creación.

**home\_kit\_orders** `ShipmentHomeKitOrderLink[]` *required*

Pedidos de kits a domicilio vinculados a este envío, con el mismo formato `{ id, added_at }`.
Array vacío para un envío creado por ti.

**synced\_at** `string`

Cuándo se sincronizó por última vez el envío con su transportista, como instante UTC. `null` hasta
la primera sincronización.

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

Marca de tiempo de creación (ISO 8601).

**updated\_at** `string`

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

## Respuestas de error

| Estado | Descripción |
| - | - |
| `400` | Error de validación: p. ej., formato de fecha no válido, fecha en fin de semana, franja de recogida demasiado corta o hora límite del mismo día superada. También se devuelve cuando `destination_lab` o la ubicación de origen no tienen dirección registrada. |
| `403` | Prohibido: tu clave de API no tiene acceso a esta operación o la ubicación está fuera de tu contexto de acceso. |
| `404` | Ubicación no encontrada o inactiva, o se proporcionó `appointment_id` pero la cita no existe. |
| `409` | La `Idempotency-Key` ya se usó con un cuerpo de solicitud distinto o su solicitud original aún no ha finalizado. |
| `500` | Error interno del servidor. |
| `502` | El proveedor logístico rechazó la solicitud. Incluye el mensaje de error del proveedor. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/shipments \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "destination_lab": "labclinic",
    "appointment_id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
    "pickup_date": "2026-04-15",
    "pickup_time_from": "09:00",
    "pickup_time_till": "12:00",
    "notes": "Handle with care — temperature-sensitive samples"
  }'
```

```json 201 theme={null}
{
  "id": "P2611194821",
  "status": "pending",
  "logistics_provider": "go",
  "tracking_number": null,
  "contents": null,
  "booked_by": "aniva",
  "paired_with": null,
  "origin": {
    "name": "Aniva Berlin Mitte",
    "company_name": null,
    "street": "Unter den Linden",
    "house_number": "42",
    "address_line_2": null,
    "postal_code": "10117",
    "city": "Berlin",
    "state": null,
    "country_code": "DE",
    "phone": "+4930987654321",
    "email": "berlin-mitte@anivahealth.com"
  },
  "destination": {
    "name": "LabClinic GmbH",
    "company_name": null,
    "street": "Laborstraße",
    "house_number": "10",
    "address_line_2": null,
    "postal_code": "80331",
    "city": "München",
    "state": null,
    "country_code": "DE",
    "phone": null,
    "email": null
  },
  "pickup": {
    "from": "2026-04-15T07:00:00Z",
    "till": "2026-04-15T10:00:00Z",
    "timezone": "Europe/Berlin"
  },
  "notes": "Handle with care — temperature-sensitive samples",
  "status_updates": [],
  "appointments": [
    {
      "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
      "added_at": "2026-04-15T07:00:00Z"
    }
  ],
  "home_kit_orders": [],
  "synced_at": null,
  "created_at": "2026-04-15T07:00:00Z",
  "updated_at": null
}
```

```json 400 theme={null}
{
  "error": "pickup_date must be a weekday (Monday–Friday)"
}
```

```json 404 theme={null}
{
  "error": "Location not found or inactive"
}
```

```json 502 theme={null}
{
  "error": "Logistics provider error: Pickup on weekend/holiday not possible",
  "logistics_error_code": 2001
}
```


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