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

# Vytvořit zásilku

> Vytvořit objednávku logistické zásilky se zadaným výchozím a cílovým místem

Vytvoří objednávku zásilky ze zadaného výchozího místa. Cílovou laboratoř určíš pomocí `destination_lab`. Zásilka půjde na registrovanou doručovací adresu této laboratoře.

Vyžaduje scope `shipments_manage`.

Odešli volitelnou hlavičku `Idempotency-Key`, aby šlo toto vytvoření bezpečně zopakovat — opakované použití stejného klíče vrátí původní odpověď místo vytvoření dalšího záznamu. Viz [Idempotence](https://docs.anivahealth.com/cs/concepts/idempotency.md).

## Požadavek

### Parametry těla

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

UUID výchozího testovacího místa. Místo musí být aktivní a v přístupovém kontextu tvého API klíče.
Dostupná ID míst najdeš přes [Vypsat místa](https://docs.anivahealth.com/cs/api/locations/list-locations.md).

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

Cílová laboratoř. Jedna z hodnot `zotzklimas`, `labclinic`, `nordicgroup`, `biomes`, `imd` nebo
`quade`. Zásilka půjde na doručovací adresu registrovanou pro tuto laboratoř. Laboratoř
bez registrované doručovací adresy vrátí `400`.

**appointment\_id** `string`

Volitelné UUID termínu, ke kterému se má tato zásilka přiřadit při vytvoření. Termín musí být
v přístupovém kontextu tvého API klíče. Propojení se zobrazí přímo jako položka v poli
`appointments` zásilky a obráceně jako položka v poli `shipments` termínu. Pro přiřazení
dalších termínů po vytvoření nebo odebrání původního propojení použij [Přiřadit termíny k
zásilce](https://docs.anivahealth.com/cs/api/shipments/attach-appointments-to-shipment.md) a [Odebrat termíny ze
zásilky](https://docs.anivahealth.com/cs/api/shipments/detach-appointments-from-shipment.md).

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

Datum vyzvednutí ve formátu `YYYY-MM-DD` (např. `2026-04-15`), vyhodnocované v časovém pásmu
výchozího místa. Musí to být pracovní den (pondělí–pátek), dnešek nebo budoucí datum. Vyzvednutí ve stejný den není
k dispozici po 16:00 Europe/Berlin.

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

Nejdřívější čas vyzvednutí ve formátu `HH:MM` (např. `09:00`), vyhodnocovaný jako místní čas v
časovém pásmu výchozího místa. Musí být mezi `09:00` a `19:00`.

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

Nejpozdější čas vyzvednutí ve formátu `HH:MM` (např. `12:00`), vyhodnocovaný jako místní čas v
časovém pásmu výchozího místa. Musí být mezi `09:00` a `19:00`. Časové okno (`pickup_time_till -
    pickup_time_from`) musí mít alespoň 2 hodiny.

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

Počet balíků. Výchozí hodnota je `1`.

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

Hmotnost v kg. Výchozí hodnota je `0.5`.

**pickup\_remarks** `string`

Pokyny pro kurýra při vyzvednutí (poznámky odesílatele). Pokud chybí, použijí se uložené poznámky
u adresy vyzvednutí (nebo žádné, pokud u adresy nejsou). Maximálně 128 znaků.

**contents** `string`

Volný textový popis obsahu balíku, který se zobrazí kurýrovi a vrátí zpět v poli
`contents`. Maximálně 40 znaků (např. `Medizinisch freigestellte Probe`).

**notes** `string`

Volitelné interní poznámky. Maximálně 128 znaků.

## Odpověď

Při úspěchu vrátí API `201 Created` s novou zásilkou.

**id** `string` *required*

Referenční identifikátor zásilky (např. `P2604151234`).

**status** `string` *required*

Stav životního cyklu zásilky. Jedna z hodnot `pending`, `in_transit`, `delivered`, `fault` nebo `cancelled`.

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

Poskytovatel logistiky. Jedna z hodnot `go`, `dhl_parcel`, `dhl_warenpost`, `rotrunner`, `rapido`,
`ups` nebo `dhl_express`. Balík s domácí sadou je `dhl_parcel`, případně `dhl_warenpost`, když jde do zahraničí
jako Warenpost International.

**tracking\_number** `string`

Externí sledovací číslo od poskytovatele logistiky. Může být `null`.

**contents** `string`

Volný textový popis obsahu balíku zadaný při vytvoření. Může být `null`.

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

Kdo vytiskl štítek: `aniva` nebo `external`. Zásilka, kterou vytvoříš, má hodnotu `aniva`.

**paired\_with** `string`

Reference druhého balíku zásilky se dvěma balíky. Pro jednosměrný balík je `null`.

**origin** `object`

Adresa vyzvednutí. Může být `null`.

**objekt adresy**

**name** `string` *required*

Jméno příjemce, název firmy nebo místa.

**company\_name** `string`

Řádek firma / c/o. Může být `null`.

**street** `string` *required*

Název ulice bez čísla domu.

**house\_number** `string`

Číslo domu. Může být `null`.

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

Budova, vchod nebo patro. Může být `null`.

**city** `string` *required*

Město.

**state** `string`

Stát nebo provincie. Může být `null`.

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

PSČ.

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

Kód země podle ISO 3166-1 alpha-2.

**phone** `string`

Kontaktní telefonní číslo. Může být `null`.

**email** `string`

Kontaktní e-mail. Může být `null`.

**destination** `object`

Doručovací adresa. Stejná struktura jako `origin`. Může být `null`.

**pickup** `object`

Naplánované okno vyzvednutí. Může být `null`.

**objekt pickup**

**from** `string` *required*

Začátek okna vyzvednutí jako okamžik v UTC (ISO 8601 s příponou `Z`).

**till** `string` *required*

Konec okna vyzvednutí jako okamžik v UTC (ISO 8601 s příponou `Z`).

**timezone** `string` *required*

Časové pásmo IANA místa vyzvednutí (např. `Europe/Berlin`). Použij k zobrazení `from` / `till` v místním čase místa vyzvednutí.

**notes** `string`

Volitelné poznámky. Může být `null`.

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

Chronologické události životního cyklu od poskytovatele logistiky (od nejstarší). Každá položka má
`state`, `code`, `detail_code`, `status`, `description`, `location` a `time`. Jednotlivá pole najdeš v [Získat
zásilku](https://docs.anivahealth.com/cs/api/shipments/get-shipment.md). Hned po vytvoření je pole prázdné.
Synchronizace na pozadí doplňuje události podle toho, jak je poskytovatel hlásí.

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

Termíny přiřazené k této zásilce, od nejstaršího přiřazení. Každá položka má tvar `{ id, added_at }`;
každé `id` dohledej přes [Získat termín](https://docs.anivahealth.com/cs/api/appointments/get-appointment.md).
Hned po vytvoření obsahuje termín předaný přes `appointment_id` (pokud byl zadán).

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

Objednávky domácích sad přiřazené k této zásilce ve stejném tvaru `{ id, added_at }`. Prázdné pole pro
zásilku, kterou vytvoříš.

**synced\_at** `string`

Kdy byla zásilka naposledy sladěna s přepravcem, jako okamžik v UTC. `null` až do první
synchronizace.

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

Časové razítko vytvoření (ISO 8601).

**updated\_at** `string`

Časové razítko poslední aktualizace (ISO 8601). Může být `null`.

## Chybové odpovědi

| Stav | Popis |
| - | - |
| `400` | Chyba validace — např. neplatný formát data, víkendové datum, příliš krátké okno vyzvednutí nebo překročená uzávěrka pro tentýž den. Vrací se také, když `destination_lab` nebo výchozí místo nemá registrovanou adresu. |
| `403` | Zakázáno — tvůj API klíč nemá k této operaci přístup nebo je místo mimo tvůj přístupový kontext. |
| `404` | Místo nebylo nalezeno nebo je neaktivní, případně bylo zadáno `appointment_id`, ale termín neexistuje. |
| `409` | Klíč `Idempotency-Key` už byl použit s jiným tělem požadavku nebo jeho původní požadavek ještě neskončil. |
| `500` | Interní chyba serveru. |
| `502` | Poskytovatel logistiky požadavek zamítl. Obsahuje chybovou zprávu poskytovatele. |

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