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

# Utwórz przesyłkę

> Utwórz zlecenie przesyłki logistycznej z określonym miejscem nadania i docelowym

Utwórz zlecenie przesyłki ze wskazanej lokalizacji nadania. Docelowe laboratorium określasz przez `destination_lab`. Przesyłka trafia na zarejestrowany adres wysyłkowy tego laboratorium.

Wymaga zakresu `shipments_manage`.

Wyślij opcjonalny nagłówek `Idempotency-Key`, aby ponawianie tego żądania utworzenia było bezpieczne — powtórzenie tego samego klucza zwraca pierwotną odpowiedź zamiast tworzyć kolejną wizytę. Zobacz [Idempotentność](https://docs.anivahealth.com/pl/concepts/idempotency.md).

## Żądanie

### Parametry treści

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

UUID źródłowej lokalizacji badań. Lokalizacja musi być aktywna i znajdować się w kontekście dostępu twojego klucza API.
Użyj [Wyświetl lokalizacje](https://docs.anivahealth.com/pl/api/locations/list-locations.md), aby znaleźć dostępne ID lokalizacji.

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

Docelowe laboratorium. Jedna z wartości: `zotzklimas`, `labclinic`, `nordicgroup`, `biomes`, `imd` lub
`quade`. Przesyłka trafia na adres wysyłkowy zarejestrowany dla tego laboratorium. Laboratorium
bez zarejestrowanego adresu wysyłkowego zwraca `400`.

**appointment\_id** `string`

Opcjonalny UUID wizyty do powiązania z tą przesyłką w momencie utworzenia. Wizyta musi
znajdować się w kontekście dostępu twojego klucza API. Powiązanie pojawia się bezpośrednio jako wpis w tablicy
`appointments` przesyłki oraz odwrotnie jako wpis w tablicy `shipments` wizyty. Aby powiązać
dodatkowe wizyty po utworzeniu lub usunąć początkowe powiązanie, użyj [Dołącz wizyty do
przesyłki](https://docs.anivahealth.com/pl/api/shipments/attach-appointments-to-shipment.md) i [Odłącz wizyty od
przesyłki](https://docs.anivahealth.com/pl/api/shipments/detach-appointments-from-shipment.md).

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

Data odbioru w formacie `YYYY-MM-DD` (np. `2026-04-15`), interpretowana w strefie czasowej
lokalizacji nadania. Musi to być dzień roboczy (poniedziałek–piątek), dzisiaj lub w przyszłości. Odbiory tego samego dnia nie są
dostępne po 16:00 czasu Europe/Berlin.

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

Najwcześniejsza godzina odbioru w formacie `HH:MM` (np. `09:00`), interpretowana jako czas lokalny w
strefie czasowej lokalizacji nadania. Musi mieścić się między `09:00` a `19:00`.

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

Najpóźniejsza godzina odbioru w formacie `HH:MM` (np. `12:00`), interpretowana jako czas lokalny w strefie czasowej
lokalizacji nadania. Musi mieścić się między `09:00` a `19:00`. Okno (`pickup_time_till -
    pickup_time_from`) musi trwać co najmniej 2 godziny.

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

Liczba paczek. Domyślnie `1`.

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

Waga w kg. Domyślnie `0.5`.

**pickup\_remarks** `string`

Instrukcje dla kuriera przy odbiorze (uwagi nadawcy). Jeśli pominiesz to pole, użyte zostaną
zapisane uwagi dla adresu odbioru (lub brak, jeśli adres ich nie ma). Maksymalnie 128 znaków.

**contents** `string`

Dowolny opis zawartości paczki, wyświetlany kurierowi i zwracany w polu
`contents`. Maksymalnie 40 znaków (np. `Medizinisch freigestellte Probe`).

**notes** `string`

Opcjonalne notatki wewnętrzne. Maksymalnie 128 znaków.

## Odpowiedź

W przypadku powodzenia API zwraca `201 Created` z nową przesyłką.

**id** `string` *required*

Identyfikator referencyjny przesyłki (np. `P2604151234`).

**status** `string` *required*

Status cyklu życia przesyłki. Jedna z wartości: `pending`, `in_transit`, `delivered`, `fault` lub `cancelled`.

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

Dostawca logistyczny. Jedna z wartości: `go`, `dhl_parcel`, `dhl_warenpost`, `rotrunner`, `rapido`,
`ups` lub `dhl_express`. Paczka z zestawem domowym ma wartość `dhl_parcel` albo `dhl_warenpost`, gdy jest wysyłana za granicę
jako Warenpost International.

**tracking\_number** `string`

Zewnętrzny numer śledzenia od dostawcy logistycznego. Może mieć wartość `null`.

**contents** `string`

Dowolny opis tekstowy zawartości paczki podany podczas tworzenia. Może mieć wartość `null`.

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

Kto wydrukował etykietę: `aniva` lub `external`. Dla utworzonej przez ciebie przesyłki to `aniva`.

**paired\_with** `string`

Numer referencyjny drugiej paczki w przesyłce dwupaczkowej. `null` w przypadku paczki w jedną stronę.

**origin** `object`

Adres odbioru. Może mieć wartość `null`.

**obiekt adresu**

**name** `string` *required*

Nazwa odbiorcy, firmy lub lokalizacji.

**company\_name** `string`

Firma / linia c/o. Może mieć wartość `null`.

**street** `string` *required*

Nazwa ulicy bez numeru domu.

**house\_number** `string`

Numer domu. Może mieć wartość `null`.

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

Budynek, wejście lub piętro. Może mieć wartość `null`.

**city** `string` *required*

Miasto.

**state** `string`

Stan lub województwo. Może mieć wartość `null`.

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

Kod pocztowy.

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

Kod kraju ISO 3166-1 alpha-2.

**phone** `string`

Kontaktowy numer telefonu. Może mieć wartość `null`.

**email** `string`

Kontaktowy adres e-mail. Może mieć wartość `null`.

**destination** `object`

Adres dostawy. Taka sama struktura jak `origin`. Może mieć wartość `null`.

**pickup** `object`

Zaplanowane okno odbioru. Może mieć wartość `null`.

**obiekt pickup**

**from** `string` *required*

Początek okna odbioru jako znacznik czasu UTC (ISO 8601 z przyrostkiem `Z`).

**till** `string` *required*

Koniec okna odbioru jako znacznik czasu UTC (ISO 8601 z przyrostkiem `Z`).

**timezone** `string` *required*

Strefa czasowa IANA miejsca odbioru (np. `Europe/Berlin`). Użyj jej, aby wyświetlić `from` / `till` w czasie lokalnym miejsca odbioru.

**notes** `string`

Opcjonalne notatki. Może mieć wartość `null`.

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

Chronologiczne zdarzenia z cyklu życia przesyłki od dostawcy logistycznego (od najstarszych). Każdy wpis ma pola
`state`, `code`, `detail_code`, `status`, `description`, `location` i `time`. Szczegóły każdego pola znajdziesz w [Pobierz
przesyłkę](https://docs.anivahealth.com/pl/api/shipments/get-shipment.md). Pusta tablica bezpośrednio po utworzeniu.
Synchronizacja w tle dodaje zdarzenia w miarę ich zgłaszania przez dostawcę.

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

Wizyty powiązane z tą przesyłką, od najstarszego powiązania. Każdy wpis ma format `{ id, added_at }`;
każde `id` sprawdź w [Pobierz wizytę](https://docs.anivahealth.com/pl/api/appointments/get-appointment.md).
Bezpośrednio po utworzeniu zawiera wizytę przekazaną w `appointment_id` (jeśli została podana).

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

Zamówienia zestawów domowych powiązane z tą przesyłką, w tym samym formacie `{ id, added_at }`. Pusta tablica dla
przesyłki utworzonej przez ciebie.

**synced\_at** `string`

Czas ostatniego uzgodnienia stanu przesyłki z przewoźnikiem jako znacznik czasu UTC. `null` do pierwszej
synchronizacji.

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

Znacznik czasu utworzenia (ISO 8601).

**updated\_at** `string`

Znacznik czasu ostatniej aktualizacji (ISO 8601). Może mieć wartość `null`.

## Odpowiedzi z błędami

| Status | Opis |
| - | - |
| `400` | Błąd walidacji — np. nieprawidłowy format daty, data w weekend, zbyt wąskie okno odbioru lub przekroczony limit czasu na odbiór tego samego dnia. Zwracany również, gdy `destination_lab` lub lokalizacja nadania nie ma zarejestrowanego adresu. |
| `403` | Brak dostępu — twój klucz API nie ma uprawnień do tej operacji lub lokalizacja znajduje się poza twoim kontekstem dostępu. |
| `404` | Nie znaleziono lokalizacji lub jest nieaktywna, albo podano `appointment_id`, ale wizyta nie istnieje. |
| `409` | Klucz `Idempotency-Key` został już użyty z inną treścią żądania lub pierwotne żądanie jeszcze się nie zakończyło. |
| `500` | Wewnętrzny błąd serwera. |
| `502` | Dostawca logistyczny odrzucił żądanie. Zawiera komunikat błędu od dostawcy. |

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