> ## 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.

# Crea un enviament

> Crea una ordre d'enviament logístic amb l'origen i la destinació especificats

Crea una ordre d'enviament des de la ubicació d'origen especificada. Indiques el laboratori de destinació amb `destination_lab`. L'enviament va a l'adreça d'enviament registrada d'aquest laboratori.

Requereix l'àmbit `shipments_manage`.

Envia una capçalera opcional `Idempotency-Key` perquè aquesta creació es pugui reintentar amb seguretat — repetir la mateixa clau retorna la resposta original en lloc de crear-ne una segona. Consulta [Idempotència](https://docs.anivahealth.com/ca/concepts/idempotency.md).

## Sol·licitud

### Paràmetres del cos

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

UUID de la ubicació d'anàlisi d'origen. La ubicació ha d'estar activa i dins del context d'accés de la teva clau API.
Fes servir [Llista les ubicacions](https://docs.anivahealth.com/ca/api/locations/list-locations.md) per trobar els ID d'ubicació disponibles.

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

Laboratori de destinació. Un de `zotzklimas`, `labclinic`, `nordicgroup`, `biomes`, `imd` o
`quade`. L'enviament va a l'adreça d'enviament registrada per a aquest laboratori. Un laboratori
sense adreça d'enviament registrada retorna `400`.

**appointment\_id** `string`

UUID de cita opcional per vincular-hi aquest enviament en el moment de crear-lo. La cita ha d'estar
dins del context d'accés de la teva clau API. El vincle apareix integrat com una entrada a la matriu
`appointments` de l'enviament i, inversament, com una entrada a la matriu `shipments` de la cita. Per vincular
cites addicionals després de la creació o eliminar el vincle inicial, fes servir [Vincula cites a
l'enviament](https://docs.anivahealth.com/ca/api/shipments/attach-appointments-to-shipment.md) i [Desvincula cites de
l'enviament](https://docs.anivahealth.com/ca/api/shipments/detach-appointments-from-shipment.md).

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

Data de recollida en format `YYYY-MM-DD` (p. ex., `2026-04-15`), interpretada en la zona horària de la ubicació
d'origen. Ha de ser un dia feiner (dilluns–divendres), avui o en el futur. Les recollides per al mateix dia no estan
disponibles després de les 16:00 Europe/Berlin.

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

Hora mínima de recollida en format `HH:MM` (p. ex., `09:00`), interpretada com a hora local en la
zona horària de la ubicació d'origen. Ha de ser entre `09:00` i `19:00`.

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

Hora màxima de recollida en format `HH:MM` (p. ex., `12:00`), interpretada com a hora local en la zona
horària de la ubicació d'origen. Ha de ser entre `09:00` i `19:00`. La franja (`pickup_time_till -
    pickup_time_from`) ha de ser com a mínim de 2 hores.

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

Nombre de paquets. Per defecte és `1`.

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

Pes en kg. Per defecte és `0.5`.

**pickup\_remarks** `string`

Instruccions per al missatger en la recollida (observacions del remitent). Si s'omet, es fan servir les
observacions desades de l'adreça de recollida (o cap si l'adreça no en té). Màxim 128 caràcters.

**contents** `string`

Descripció en text lliure del contingut del paquet, que es mostra al missatger i es retorna com a
`contents`. Màxim 40 caràcters (p. ex., `Medizinisch freigestellte Probe`).

**notes** `string`

Notes internes opcionals. Màxim 128 caràcters.

## Resposta

Si té èxit, l'API retorna `201 Created` amb el nou enviament.

**id** `string` *required*

Identificador de referència de l'enviament (p. ex., `P2604151234`).

**status** `string` *required*

Estat del cicle de vida de l'enviament. Un de `pending`, `in_transit`, `delivered`, `fault` o `cancelled`.

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

Proveïdor logístic. Pot ser `go`, `dhl_parcel`, `dhl_warenpost`, `rotrunner`, `rapido`,
`ups` o `dhl_express`. Un paquet de kit a domicili és `dhl_parcel`, o `dhl_warenpost` quan s'envia a l'estranger
com a Warenpost International.

**tracking\_number** `string`

Número de seguiment extern del proveïdor logístic. Pot ser `null`.

**contents** `string`

Descripció en text lliure del contingut del paquet, tal com es va indicar en crear-lo. Pot ser `null`.

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

Qui ha imprès l'etiqueta: `aniva` o `external`. Un enviament que crees tu és `aniva`.

**paired\_with** `string`

Referència de l'altre paquet d'un enviament de dos paquets. `null` per a un paquet d'un sol trajecte.

**origin** `object`

Adreça de recollida. Pot ser `null`.

**objecte d'adreça**

**name** `string` *required*

Nom del destinatari, empresa o ubicació.

**company\_name** `string`

Empresa / línia c/o. Pot ser `null`.

**street** `string` *required*

Nom del carrer, sense el número.

**house\_number** `string`

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

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

Edifici, entrada o pis. Pot ser `null`.

**city** `string` *required*

Ciutat.

**state** `string`

Estat o província. Pot ser `null`.

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

Codi postal/ZIP.

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

Codi de país ISO 3166-1 alfa-2.

**phone** `string`

Telèfon de contacte. Pot ser `null`.

**email** `string`

Correu electrònic de contacte. Pot ser `null`.

**destination** `object`

Adreça de lliurament. Mateixa estructura que `origin`. Pot ser `null`.

**pickup** `object`

Franja de recollida programada. Pot ser `null`.

**objecte pickup**

**from** `string` *required*

Inici de la franja de recollida com a instant UTC (ISO 8601 amb el sufix `Z`).

**till** `string` *required*

Final de la franja de recollida com a instant UTC (ISO 8601 amb el sufix `Z`).

**timezone** `string` *required*

Zona horària IANA de la ubicació de recollida (p. ex., `Europe/Berlin`). Fes-la servir per mostrar `from` / `till` en l'hora local de la ubicació de recollida.

**notes** `string`

Notes opcionals. Pot ser `null`.

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

Esdeveniments cronològics del cicle de vida del proveïdor logístic (el més antic primer). Cada entrada té
`state`, `code`, `detail_code`, `status`, `description`, `location` i `time`. Consulta [Obtén
l'enviament](https://docs.anivahealth.com/ca/api/shipments/get-shipment.md) per a cada camp. Matriu buida just després de la creació.
La sincronització en segon pla afegeix esdeveniments a mesura que el proveïdor els comunica.

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

Cites vinculades a aquest enviament, el vincle més antic primer. Cada entrada és `{ id, added_at }`;
consulta cada `id` a [Obtén la cita](https://docs.anivahealth.com/ca/api/appointments/get-appointment.md).
Conté la cita passada mitjançant `appointment_id` (si n'hi ha) just després de la creació.

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

Comandes de kits a domicili vinculades a aquest enviament, amb el mateix format `{ id, added_at }`. Matriu buida per a un
enviament que crees tu.

**synced\_at** `string`

Quan es va conciliar l'enviament per última vegada amb el transportista, com a instant UTC. `null` fins a la primera
sincronització.

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

Marca de temps de creació (ISO 8601).

**updated\_at** `string`

Marca de temps de l'última actualització (ISO 8601). Pot ser `null`.

## Respostes d'error

| Estat | Descripció |
| - | - |
| `400` | Error de validació — p. ex., format de data no vàlid, data en cap de setmana, franja de recollida massa curta, hora límit per al mateix dia superada. També es retorna quan `destination_lab` o la ubicació d'origen no té cap adreça registrada. |
| `403` | Prohibit — la teva clau API no té accés a aquesta operació o la ubicació és fora del teu context d'accés. |
| `404` | Ubicació no trobada o inactiva, o s'ha proporcionat `appointment_id` però la cita no existeix. |
| `409` | `Idempotency-Key` ja s'ha fet servir amb un cos de sol·licitud diferent, o la seva sol·licitud original no s'ha completat. |
| `500` | Error intern del servidor. |
| `502` | El proveïdor logístic ha rebutjat la sol·licitud. Inclou el missatge d'error del proveïdor. |

```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.