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

# Sūtījumi

> Kā darbojas loģistika Aniva API: paraugu sūtījumi uz laboratoriju un mājas testa komplektu pakas ar izsekošanu un statusu.

Sūtījums ir viena fiziska paka: kurjera savākts sūtījums ar asins paraugiem no testēšanas vietas uz laboratoriju, komplekts ceļā pie mājas testa komplekta pacienta vai paraugs, ko šis pacients nosūta atpakaļ. Sūtījumu API ļauj tev izveidot, izsekot, mainīt un atcelt sūtījumu pasūtījumus un vienuviet uzskaita visas pakas neatkarīgi no tā, kas tās pieteicis.

## Viens saraksts, filtrēts

`GET /api/v1/shipments` ir vienīgā kolekcija. Sūtījums ir patstāvīga vienība — tam ir daudzi-pret-daudziem saistība ar pierakstiem, un tas var piederēt mājas testa komplekta pasūtījumam —, tāpēc nevienam vecākobjektam nav pakārtota saraksta. Sašaurini to pašu sarakstu ar `?appointment_id=` vai `?home_kit_order_id=`, sadali lapās ar `limit` / `offset` un izmanto vecākobjektā iekļauto masīvu `shipments` (`{ id, added_at }` gan pierakstos, gan mājas testa komplektu pasūtījumos), lai atvērtu [Iegūt sūtījumu](https://docs.anivahealth.com/lv/api/shipments/get-shipment.md), kad tev ir viens ID.

## Saturs un pasūtītājs

Katram sūtījumam ir divi fakti, kas nav redzami no tā adresēm:

* `contents` — brīvs teksts, kas apraksta pakas saturu, iestatīts izveides brīdī (`"Medizinisch freigestellte Probe"`, `"Home test kit"`) un rādīts kurjeram. Tikai informatīvs. Virziens nav atsevišķs lauks: to, vai paka dodas uz laboratoriju, var nolasīt laukā `destination`.
* `booked_by` — kas izdrukāja uzlīmi: `aniva` vai `external`. Tikai `aniva` sūtījumiem darbojas [Atjaunināt](https://docs.anivahealth.com/lv/api/shipments/update-shipment.md) un [Atcelt](https://docs.anivahealth.com/lv/api/shipments/cancel-shipment.md); `external` paka tiek izsekota tajā pašā sarakstā, bet abos gadījumos atgriež `501`.

Paka, kurā bija iekļauta atgriešanas uzlīme, un paka, ko šī uzlīme nogādā atpakaļ, savstarpēji norāda viena uz otru laukā `paired_with`.

## Piekļuve

* Tu vari lasīt paku, ja vismaz viens piesaistīts pieraksts vai mājas testa komplekta pasūtījums ir tavā piekļuves kontekstā vai ja tā nosūtīta no atrašanās vietas tavā piekļuves kontekstā.
* `appointments` un `home_kit_orders` uzskaita tikai pierakstus un pasūtījumus tavā piekļuves kontekstā.
* Darbībām [Atjaunināt](https://docs.anivahealth.com/lv/api/shipments/update-shipment.md), [Atcelt](https://docs.anivahealth.com/lv/api/shipments/cancel-shipment.md), [Piesaistīt pierakstus](https://docs.anivahealth.com/lv/api/shipments/attach-appointments-to-shipment.md) un [Atsaistīt pierakstus](https://docs.anivahealth.com/lv/api/shipments/detach-appointments-from-shipment.md) nepieciešams, lai visi piesaistītie mājas testa komplektu pasūtījumi būtu tavā piekļuves kontekstā. Pretējā gadījumā izsaukums atgriež `403`, un paku var mainīt tikai Aniva.

## Lasīšana nekad neizsauc pārvadātāju

Katrs lasīšanas pieprasījums tiek apkalpots no mūsu datubāzes. Fona sinhronizācija salīdzina katru sūtījumu ar tā pārvadātāju (ik pēc 10 minūtēm GO!, reizi stundā DHL) un iestata `synced_at`, kas parāda atbildes vecumu. Piespiedu atsvaidzināšanas nav — DHL atļauj vienu izsekošanas izsaukumu ik pēc piecām sekundēm, tāpēc lasīšanu ar tiešu pieprasījumu pārvadātājam nevar piedāvāt.

## Sūtījuma izveide

Izveidojot sūtījumu, tu norādi sākumpunktu `location_id` — testēšanas vietu, kur kurjeram tas jāpaņem. Tu norādi arī galamērķa laboratoriju laukā `destination_lab`. Sūtījums tiek nosūtīts uz šīs laboratorijas reģistrēto piegādes adresi.

Atrašanās vietai jābūt tavas API atslēgas piekļuves kontekstā. Izmanto [Skatīt atrašanās vietas](https://docs.anivahealth.com/lv/api/locations/list-locations.md), lai atrastu pieejamos atrašanās vietu ID.

Pēc izvēles vari norādīt `appointment_id`, lai izveides brīdī piesaistītu sūtījumu konkrētam pierakstam.
Saistība parādās abās pusēs:

* sūtījumā kā `appointments` masīvs ar `{ id, added_at }` ierakstiem;
* pierakstā kā `shipments` masīvs ar `{ id, added_at }` ierakstiem.

Abos masīvos vispirms ir vecākā saistība. Katrs `id` norāda uz kanonisko detalizētās informācijas galapunktu
([Iegūt pierakstu](https://docs.anivahealth.com/lv/api/appointments/get-appointment.md) /
[Iegūt sūtījumu](https://docs.anivahealth.com/lv/api/shipments/get-shipment.md)), lai saņemtu pilnus datus — partneri, kuri vēlas
sekot kurjera gaitai katram pierakstam, seko katram ierakstam pieraksta `shipments` masīvā līdz
sūtījuma detalizētās informācijas galapunktam.

Sūtījumu var piesaistīt vairākiem pierakstiem, un pierakstu var piesaistīt vairākiem
sūtījumiem. Pēc izveides pārvaldi saistību ar [Piesaistīt pierakstus
sūtījumam](https://docs.anivahealth.com/lv/api/shipments/attach-appointments-to-shipment.md) /
[Atsaistīt pierakstus no sūtījuma](https://docs.anivahealth.com/lv/api/shipments/detach-appointments-from-shipment.md). Katra
izmaiņa atgriež sūtījuma pierakstu sarakstu pēc izmaiņas.

Izmaiņu noteikums ir šāds: saistības var izveidot vai noņemt, ja VAI NU pierakstam jau ir notikusi
asins paņemšana (`blood_drawn`), vai arī sūtījums tika izveidots pirms mazāk nekā 24 stundām. Ārpus šī
laika loga saistība ir bloķēta, lai vēsturiskie ieraksti paliktu nemainīgi.

## Dzīves cikls

Sūtījumi iziet cauri šādiem statusiem:

```text theme={null}
pending → in_transit → delivered
              ↓
            fault
    ↓
 cancelled
```

| Statuss | Nozīme |
| - | - |
| `pending` | Kurjera pasūtījums ir veikts un gaida paņemšanu. |
| `in_transit` | Kurjers ir paņēmis paku, un tā ir ceļā. |
| `delivered` | Paka ir piegādāta. |
| `fault` | Pārvadājuma laikā radās problēma, vai pārvadātājs nosūtīja paku atpakaļ sūtītājam. |
| `cancelled` | Sūtījums ir atcelts. |

Katra statusa maiņa nosūta `shipment.*` [tīmekļa āķi](https://docs.anivahealth.com/lv/concepts/webhooks.md), piemēram,
`shipment.delivered`. `shipment.updated` nostrādā pie katras izmaiņas, ko vari nolasīt, piemēram, jauna skenējuma.

## Paņemšanas grafika noteikumi

Izveidojot vai atjauninot sūtījuma paņemšanas grafiku, ir spēkā šādi noteikumi. `pickup_date`
(`YYYY-MM-DD`) un `pickup_time_from` / `pickup_time_till` (`HH:MM`, 24 h) ir vietējā pulksteņa vērtības,
kas **tiek interpretētas izsūtīšanas vietas IANA laika joslā** — laika joslu tām līdzi nesūti.

| Noteikums | Detaļas |
| - | - |
| **Tikai darba dienas** | `pickup_date` jābūt no pirmdienas līdz piektdienai. |
| **Šodien vai nākotnē** | `pickup_date` nedrīkst būt pagātnē. |
| **Tās pašas dienas robežlaiks** | Tās pašas dienas paņemšana tiek noraidīta pēc 16:00 Europe/Berlin. |
| **Laika loga diapazons** | `pickup_time_from` un `pickup_time_till` jābūt diapazonā 09:00–19:00. |
| **Vismaz 2 h logs** | Paņemšanas logam jābūt vismaz 2 stundas garam. |

## Sūtījumu mainīšana

Sūtījuma paņemšanas grafiku, paku skaitu, svaru un piezīmes vari atjaunināt ar `PATCH /api/v1/shipments/{id}`. Ja mainās kāds loģistikai būtisks lauks (paņemšanas datums, laiks, paku skaits vai svars), esošais loģistikas pasūtījums tiek automātiski atcelts un tiek izveidots jauns. Lauki, kurus izlaid atjauninājuma saturā, tiek saglabāti no esošā sūtījuma — piemēram, atjauninot tikai `weight`, pasūtījums tiks izveidots no jauna ar to pašu paņemšanas grafiku. Atjauninātie grafika lauki tiek pārbaudīti pēc tiem pašiem [paņemšanas grafika noteikumiem](#panemsanas-grafika-noteikumi).

> [!WARNING]
>
> Sūtījumus nevar mainīt pēc tam, kad kurjers ir paņēmis paku. Mēģinājums atjaunināt
> sūtījumu statusā `in_transit`, `delivered` vai `fault` atgriež `409 Conflict`.

Ja loģistikas pakalpojumu sniedzējs atjaunināšanas laikā noraida atcelšanu vai atkārtotu izveidi, API atgriež `502 Bad Gateway` ar sniedzēja kļūdas ziņojumu.

## Sūtījumu atcelšana

Atcel sūtījumu, izmantojot `DELETE /api/v1/shipments/{id}`. Tas izsauc loģistikas pakalpojumu sniedzēja API, lai atceltu pasūtījumu, un atjaunina statusu uz `cancelled`.

> [!WARNING]
>
> Sūtījumus nevar atcelt pēc paņemšanas. Mēģinājums atcelt sūtījumu, kas jau ir statusā
> `in_transit`, `delivered` vai `fault`, atgriež `409 Conflict`. Jau `cancelled` statusā esoša
> sūtījuma atcelšana neveic nekādas izmaiņas un atgriež `200` ar pašu sūtījumu — skati
> [Idempotence](https://docs.anivahealth.com/lv/concepts/idempotency.md).

Loģistikas pakalpojumu sniedzējs var noraidīt atcelšanu arī savu iemeslu dēļ (piemēram, ir pagājis atcelšanas termiņš). Šādā gadījumā API atgriež `502 Bad Gateway` ar sniedzēja kļūdas ziņojumu un kļūdas kodu.

### Atpakaļsūtīšanas uzlīmes

DHL atpakaļsūtīšanas uzlīme ir daļa no izejošā pasūtījuma. DHL nevar atcelt uzlīmi atsevišķi, tāpēc tās rindas atcelšana, kas izseko atpakaļsūtīšanas uzlīmi, atgriež `409 Conflict`. Tā vietā atcel izejošo paku, kamēr tā ir statusā `pending`. Tas vienlaikus atceļ arī uzlīmi: katra izejošās pakas atpakaļsūtīšanas rinda statusā `pending` kļūst par `cancelled` un saņem `RETURN_LEG_CANCELLED` ierakstu laukā `status_updates`. Atpakaļsūtāmā paka, ko pacients jau ir nosūtījis, turpina ceļu. Kad izejošā paka ir izsūtīta, uzlīme paliek derīga, un Aniva aizver atpakaļsūtīšanas rindu manuāli.

## Sūtījumu atsauces ID

Katram sūtījumam ir 11 rakstzīmju atsauces ID: burts, datums un četras rakstzīmes, `{letter}YYMMDDXXXX` (piemēram, `P2611194821`). Burts norāda, kam sūtījums pieder, bet nekad nenorāda tā virzienu:

| Burts | Sūtījums |
| - | - |
| `P` | Sūtījums, ko tu izveido ar šo API. |
| `M` | Sūtījums, ko izveido Aniva komanda. |
| `C` | Sūtījums no Aniva ikdienas izsūtīšanas. |
| `K` | Mājas komplekta paka. |
| `F`, `S` | Aniva pašas krājumu pakas. |

Sūtījums no 2026. gada 20. līdz 22. novembrim saglabā savu ID ar vārdu priekšā: `API`, `MAN`, `AUTO` vai `KIT` (piemēram, `AUTO261121UWKX`). Abas formas paliek derīgas. Nepārbaudi ID garumu vai pirmo burtu. Izmanto šo ID, lai izgūtu, atjauninātu vai atceltu sūtījumu.

## Sūtījumu adreses

Sūtījuma atbildes lauki `origin` un `destination` satur atrisinātus adrešu objektus ar šādu struktūru:

```json theme={null}
{
  "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"
}
```

Prakses pakai `origin` adrese tiek iegūta no analīžu vietas, ko norādīji izveides
laikā, bet `destination` ir laboratorija, ko norādīji laukā `destination_lab`.
Mājas komplekta pakai pacienta piegādes adrese ir komplekta `destination` un
parauga atpakaļsūtīšanas `origin`; vieta, kur komplektu iepako, ir tā `origin`. Adresē
nav `location_id` — prakses paku sasaisti pēc pieraksta, kuram tā ir
piesaistīta.

## Paņemšanas logs

Sūtījuma atbildes lauks `pickup` satur ieplānoto kurjera paņemšanas logu. Tas
ietver `from` un `till` laikspiedolus kā UTC laika punktus (ISO 8601 ar `Z` sufiksu, piemēram,
`2026-04-15T07:00:00Z`) un `timezone` virkni (paņemšanas vietas IANA laika joslu). Vietējā
pulksteņa vērtības `pickup_date` / `pickup_time_*`, ko nosūtīji izveides vai atjaunināšanas laikā, tiek pārveidotas par šiem
absolūtajiem laika punktiem, izmantojot šo laika joslu — izmanto `timezone`, lai attēlotu `from` / `till` atpakaļ
paņemšanas vietas vietējā laikā. Lauks ir `null`, ja paņemšanas logs nav ieplānots.

## Statusa atjauninājumu žurnāls

Katram sūtījumam ir `status_updates` masīvs — visi aprites cikla notikumi, par kuriem loģistikas pakalpojumu sniedzējs
ir ziņojis, sākot ar vecāko. Katrs ieraksts satur:

* `state` — notikums sūtījumu statusu vārdnīcā (`pending`, `in_transit`, `delivered`,
  `fault`), lai tu varētu lasīt laika skalu, nezinot pārvadātāja kodus. `null`, ja notikumam
  nav statusa (uzlīmes izveide, pārvadātāja skenējums bez informācijas, ieraksti, kas saglabāti pirms šī
  lauka ieviešanas). Nekad nav `cancelled` — atcelšana ir mūsu, nevis pārvadātāja notikums.
* `code` — paša pārvadātāja statusa kods (GO! `GO10`, `GO90`, `GOY001`; DHL `VA`, `ZF`,
  `LA`, `ZU`). `null`, ja pārvadātājs to nenorādīja. Nemainās dažādos `status` valodu
  tulkojumos.
* `detail_code` — pārvadātāja detalizētāks kods, ja tāds pastāv: DHL `statusDetailed`, piemēram,
  `CNRFC_NRQRD_ZF` (novirzīts uz pasta nodaļu), `HLDCC_SERPT_LA` (gatavs saņemšanai tur),
  `DLVRD_SERPT_ZU` (izņemts). Citur — `null`.
* `status` — cilvēkam lasāms pārvadātāja apzīmējums (piemēram, `"Shipment picked up"`,
  `"Die Sendung wurde abgeholt."`).
* `description` — koda skaidrojums vai pārvadātāja garāks teikums. `null`, ja
  nav neviena no tiem.
* `location` — vieta, kur notika skenēšana, kā to nosauc pārvadātājs: GO! depo, DHL pilsēta. Brīvs
  teksts, nevis koordinātas.
* `time` — notikuma ISO 8601 laikspiedols, kā to ziņojis pārvadātājs (ar tā nobīdi).

Kad pārvadātājs nosūta paku atpakaļ sūtītājam, laika skalā parādās viens ieraksts ar `code`
`RETURNED_TO_SENDER`. Tā `status` satur pārvadātāja norādīto iemeslu. Sūtījums pēc tam paliek statusā `fault` arī
pēc tam, kad pārvadātājs paku ir piegādājis atpakaļ mums.

Saraksts var būt tukšs, ja pārvadātājs vēl nav ziņojis ne par vienu notikumu.

Pašreizējam kanoniskajam stāvoklim izmanto augstākā līmeņa lauku `status`. Tas virzās vienā virzienā — no `pending`
uz `in_transit` un `delivered` — ar pārklātu `fault`, kamēr jaunākais notikums par tādu ziņo;
pārvadātāji nesakārto notikumus pēc nozīmīguma (DHL pēc nodošanas skenējuma pievieno pāradresācijas paziņojumu
ar kodu `pre-transit`), tāpēc jaunākais ieraksts viens pats nepasaka, kādā posmā paka atrodas.

## Sūtījuma piemērs

```json 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-03T14:30:00Z"
    }
  ],
  "home_kit_orders": [],
  "synced_at": null,
  "created_at": "2026-04-03T14:30:00Z",
  "updated_at": null
}
```

## Mājas komplekta paku piemērs

`GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-…` atgriež komplektu ceļā pie pacienta un paraugu atpakaļceļā kā pāri:

```json theme={null}
[
  {
    "id": "K2609041FQ7",
    "status": "in_transit",
    "logistics_provider": "dhl_parcel",
    "tracking_number": "00340434779457841299",
    "contents": "Home test kit",
    "booked_by": "aniva",
    "paired_with": "K260904P3XD",
    "origin": { "name": "Aniva Health", "street": "Wilhelmstraße", "house_number": "118", "postal_code": "10963", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "destination": { "name": "Jane Doe", "street": "Friedrichstraße", "house_number": "123", "postal_code": "10117", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "pickup": null,
    "notes": null,
    "status_updates": [
      {
        "state": "pending",
        "code": "VA",
        "detail_code": "PARCV_NRQRD_VA",
        "status": "Die Auftragsdaten zu dieser Sendung wurden vom Absender elektronisch an DHL übermittelt.",
        "description": "Electronic advice from DHL — not a parcel scan",
        "location": null,
        "time": "2026-09-02T18:17:00+02:00"
      },
      {
        "state": "in_transit",
        "code": "ES",
        "detail_code": "SHRCU_SERPT_ES",
        "status": "Die Sendung wurde in der Filiale eingeliefert.",
        "description": "Shipment in transit",
        "location": "Berlin",
        "time": "2026-09-04T18:13:00+02:00"
      }
    ],
    "appointments": [],
    "home_kit_orders": [{ "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a", "added_at": "2026-09-02T18:20:00Z" }],
    "synced_at": "2026-09-05T10:00:00Z",
    "created_at": "2026-09-02T18:20:00Z",
    "updated_at": "2026-09-05T10:00:00Z"
  },
  {
    "id": "K260904P3XD",
    "status": "pending",
    "logistics_provider": "dhl_parcel",
    "tracking_number": "00340434850359000004",
    "contents": "Sample return to lab",
    "booked_by": "aniva",
    "paired_with": "K2609041FQ7",
    "origin": { "name": "Jane Doe", "street": "Friedrichstraße", "house_number": "123", "postal_code": "10117", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "destination": { "name": "Labor Quade", "street": "Laborstraße", "house_number": "10", "postal_code": "50667", "city": "Köln", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "pickup": null,
    "notes": null,
    "status_updates": [],
    "appointments": [],
    "home_kit_orders": [{ "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a", "added_at": "2026-09-02T18:20:00Z" }],
    "synced_at": "2026-09-05T10:00:00Z",
    "created_at": "2026-09-02T18:20:00Z",
    "updated_at": null
  }
]
```

Atpakaļsūtīšanas rinda pastāv no brīža, kad tiek izdrukāta atpakaļsūtīšanas uzlīme, un paliek statusā `pending`, līdz pacients nosūta paraugu — tas ir patiess stāvoklis, nevis iztrūkums.


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