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

# Creează o expediere

> Creează o comandă de expediere logistică cu originea și destinația specificate

Creează o comandă de expediere din locația de origine specificată. Indici laboratorul de destinație prin `destination_lab`. Expedierea ajunge la adresa de livrare înregistrată a acelui laborator.

Necesită scope-ul `shipments_manage`.

Trimite un antet opțional `Idempotency-Key` pentru ca această creare să poată fi reîncercată în siguranță — repetarea aceleiași chei returnează răspunsul inițial în loc să creeze încă una. Vezi [Idempotență](https://docs.anivahealth.com/ro/concepts/idempotency.md).

## Cerere

### Parametri de corp

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

UUID-ul locației de testare de origine. Locația trebuie să fie activă și în contextul de acces al cheii tale API.
Folosește [Listează locațiile](https://docs.anivahealth.com/ro/api/locations/list-locations.md) pentru a găsi ID-urile locațiilor disponibile.

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

Laboratorul de destinație. Una dintre valorile `zotzklimas`, `labclinic`, `nordicgroup`, `biomes`, `imd` sau
`quade`. Expedierea ajunge la adresa de livrare înregistrată pentru acest laborator. Un laborator
fără o adresă de livrare înregistrată returnează `400`.

**appointment\_id** `string`

UUID opțional al programării pe care o asociezi cu această expediere la creare. Programarea trebuie să fie
în contextul de acces al cheii tale API. Asocierea apare direct ca o intrare în lista
`appointments` a expedierii și, reciproc, ca o intrare în lista `shipments` a programării. Pentru a asocia
programări suplimentare după creare sau pentru a elimina asocierea inițială, folosește [Atașează programări la
expediere](https://docs.anivahealth.com/ro/api/shipments/attach-appointments-to-shipment.md) și [Detașează programări de la
expediere](https://docs.anivahealth.com/ro/api/shipments/detach-appointments-from-shipment.md).

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

Data ridicării în format `YYYY-MM-DD` (de ex., `2026-04-15`), interpretată în fusul orar al locației
de origine. Trebuie să fie o zi lucrătoare (luni–vineri), azi sau în viitor. Ridicările în aceeași zi nu sunt
disponibile după 16:00 Europe/Berlin.

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

Cea mai devreme oră de ridicare în format `HH:MM` (de ex., `09:00`), interpretată ca oră locală în
fusul orar al locației de origine. Trebuie să fie între `09:00` și `19:00`.

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

Cea mai târzie oră de ridicare în format `HH:MM` (de ex., `12:00`), interpretată ca oră locală în fusul
orar al locației de origine. Trebuie să fie între `09:00` și `19:00`. Intervalul (`pickup_time_till -
    pickup_time_from`) trebuie să fie de cel puțin 2 ore.

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

Numărul de colete. Valoare implicită: `1`.

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

Greutatea în kg. Valoare implicită: `0.5`.

**pickup\_remarks** `string`

Instrucțiuni pentru curier la ridicare (mențiuni ale expeditorului). Dacă lipsesc, se folosesc
mențiunile salvate ale adresei de ridicare (sau niciuna, dacă adresa nu are). Maximum 128 de caractere.

**contents** `string`

Descriere în text liber a conținutului coletului, afișată curierului și returnată ca
`contents`. Maximum 40 de caractere (de ex., `Medizinisch freigestellte Probe`).

**notes** `string`

Note interne opționale. Maximum 128 de caractere.

## Răspuns

În caz de succes, API-ul returnează `201 Created` împreună cu noua expediere.

**id** `string` *required*

Identificatorul de referință al expedierii (de ex., `P2604151234`).

**status** `string` *required*

Starea expedierii în ciclul de viață. Una dintre valorile `pending`, `in_transit`, `delivered`, `fault` sau `cancelled`.

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

Furnizorul de logistică. Una dintre valorile `go`, `dhl_parcel`, `dhl_warenpost`, `rotrunner`, `rapido`,
`ups` sau `dhl_express`. Un colet cu kit pentru acasă folosește `dhl_parcel` sau `dhl_warenpost` când pleacă în străinătate
ca Warenpost International.

**tracking\_number** `string`

Numărul extern de urmărire de la furnizorul de logistică. Poate fi `null`.

**contents** `string`

Descriere în text liber a conținutului coletului, așa cum a fost furnizată la creare. Poate fi `null`.

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

Cine a tipărit eticheta: `aniva` sau `external`. O expediere pe care o creezi este `aniva`.

**paired\_with** `string`

Referința celuilalt colet dintr-o expediere cu două colete. `null` pentru un colet într-un singur sens.

**origin** `object`

Adresa de ridicare. Poate fi `null`.

**obiect adresă**

**name** `string` *required*

Numele destinatarului, al companiei sau al locației.

**company\_name** `string`

Linie companie / c/o. Poate fi `null`.

**street** `string` *required*

Numele străzii, fără numărul casei.

**house\_number** `string`

Numărul casei. Poate fi `null`.

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

Bloc, scară sau etaj. Poate fi `null`.

**city** `string` *required*

Oraș.

**state** `string`

Stat sau provincie. Poate fi `null`.

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

Cod poștal.

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

Cod de țară ISO 3166-1 alpha-2.

**phone** `string`

Număr de telefon de contact. Poate fi `null`.

**email** `string`

E-mail de contact. Poate fi `null`.

**destination** `object`

Adresa de livrare. Aceeași structură ca `origin`. Poate fi `null`.

**pickup** `object`

Intervalul programat de ridicare. Poate fi `null`.

**Obiectul pickup**

**from** `string` *required*

Începutul intervalului de ridicare ca moment UTC (ISO 8601 cu sufixul `Z`).

**till** `string` *required*

Sfârșitul intervalului de ridicare ca moment UTC (ISO 8601 cu sufixul `Z`).

**timezone** `string` *required*

Fusul orar IANA al locației de ridicare (de ex., `Europe/Berlin`). Folosește-l pentru a afișa `from` / `till` în ora locală a locației de ridicare.

**notes** `string`

Note opționale. Poate fi `null`.

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

Evenimente cronologice din ciclul de viață de la furnizorul de logistică (cele mai vechi primele). Fiecare intrare are
`state`, `code`, `detail_code`, `status`, `description`, `location` și `time`. Vezi [Obține
expedierea](https://docs.anivahealth.com/ro/api/shipments/get-shipment.md) pentru fiecare câmp. Listă goală imediat după creare.
Sincronizarea în fundal adaugă evenimente pe măsură ce furnizorul le raportează.

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

Programările asociate cu această expediere, de la cea mai veche asociere. Fiecare intrare are forma `{ id, added_at }`;
verifică fiecare `id` prin [Obține programarea](https://docs.anivahealth.com/ro/api/appointments/get-appointment.md).
Conține programarea transmisă prin `appointment_id` (dacă există) imediat după creare.

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

Comenzile de kituri pentru acasă asociate cu această expediere, în aceeași formă `{ id, added_at }`. Listă goală pentru o
expediere pe care o creezi.

**synced\_at** `string`

Momentul ultimei sincronizări a expedierii cu transportatorul, ca moment UTC. `null` până la prima
sincronizare.

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

Data și ora creării (ISO 8601).

**updated\_at** `string`

Data și ora ultimei actualizări (ISO 8601). Poate fi `null`.

## Răspunsuri de eroare

| Status | Descriere |
| - | - |
| `400` | Eroare de validare — de ex., format de dată invalid, dată din weekend, interval de ridicare prea scurt, oră-limită depășită pentru aceeași zi. Returnată și când `destination_lab` sau locația de origine nu are o adresă înregistrată. |
| `403` | Interzis — cheia ta API nu are acces la această operațiune sau locația se află în afara contextului tău de acces. |
| `404` | Locația nu a fost găsită sau este inactivă, ori a fost furnizat `appointment_id`, dar programarea nu există. |
| `409` | `Idempotency-Key` a fost deja folosită cu un alt corp de cerere sau cererea inițială nu s-a încheiat încă. |
| `500` | Eroare internă de server. |
| `502` | Furnizorul de logistică a respins cererea. Include mesajul de eroare al furnizorului. |

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