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

# Enviaments

> Com funciona la logística a l'API d'Aniva: enviaments de mostres al laboratori i paquets de kits de prova a casa, amb seguiment i estat.

Un enviament és un paquet físic: una recollida per missatgeria que porta mostres de sang d'un punt de proves a un laboratori, el kit en camí cap a un pacient amb kit de prova a casa, o la mostra que aquest pacient envia de tornada per correu. L'API d'enviaments et permet crear, seguir, modificar i cancel·lar ordres d'enviament, i llista tots els paquets en un sol lloc, independentment de qui els hagi reservat.

## Una sola llista, filtrada

`GET /api/v1/shipments` és l'única col·lecció. Un enviament és independent — té una relació de molts a molts amb les cites i pot pertànyer a una comanda de kit de prova a casa — així que no hi ha cap llista imbricada sota un recurs pare. Filtra la mateixa llista amb `?appointment_id=` o `?home_kit_order_id=`, pagina-la amb `limit` / `offset` i segueix la matriu `shipments` integrada del recurs pare (`{ id, added_at }` tant en cites com en comandes de kit de prova a casa) fins a [Obtenir un enviament](https://docs.anivahealth.com/ca/api/shipments/get-shipment.md) quan tinguis un ID.

## Contingut i qui l'ha reservat

Cada enviament inclou dues dades que no són visibles a partir de les seves adreces:

* `contents` — text lliure que descriu què hi ha dins del paquet, definit en crear-lo (`"Medizinisch freigestellte Probe"`, `"Home test kit"`) i mostrat al missatger. Només informatiu. La direcció no és un camp: si un paquet va cap a un laboratori es dedueix de `destination`.
* `booked_by` — qui ha imprès l'etiqueta: `aniva` o `external`. Només els enviaments `aniva` accepten [Actualitzar](https://docs.anivahealth.com/ca/api/shipments/update-shipment.md) i [Cancel·lar](https://docs.anivahealth.com/ca/api/shipments/cancel-shipment.md); un paquet `external` té seguiment a la mateixa llista, però retorna `501` en ambdós casos.

Un paquet que portava una etiqueta de devolució i el paquet que torna amb aquella etiqueta s'apunten mútuament mitjançant `paired_with`.

## Accés

* Pots consultar un paquet quan almenys una cita o una comanda de kit de prova a casa vinculada és dins del teu context d'accés, o quan ha sortit d'una ubicació del teu context d'accés.
* `appointments` i `home_kit_orders` només llisten les cites i les comandes del teu context d'accés.
* [Actualitzar](https://docs.anivahealth.com/ca/api/shipments/update-shipment.md), [Cancel·lar](https://docs.anivahealth.com/ca/api/shipments/cancel-shipment.md), [Vincular cites](https://docs.anivahealth.com/ca/api/shipments/attach-appointments-to-shipment.md) i [Desvincular cites](https://docs.anivahealth.com/ca/api/shipments/detach-appointments-from-shipment.md) requereixen que totes les comandes de kit de prova a casa vinculades siguin dins del teu context d'accés. En cas contrari, la crida retorna `403` i només Aniva pot modificar el paquet.

## Les lectures no criden mai el transportista

Cada lectura se serveix des de la nostra base de dades. Una sincronització en segon pla concilia cada enviament amb el seu transportista (cada 10 minuts per a GO!, cada hora per a DHL) i marca `synced_at`, que indica l'antiguitat de cada resposta. No hi ha actualització forçada — DHL permet una crida de seguiment cada cinc segons, de manera que no es podria oferir una lectura que faci l'anada i tornada al transportista.

## Crear un enviament

Quan crees un enviament, indiques el `location_id` d'origen — el punt de proves on ha de fer la recollida el missatger. També indiques el laboratori de destinació amb `destination_lab`. L'enviament va a l'adreça d'enviament registrada d'aquell laboratori.

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

Opcionalment pots passar `appointment_id` per vincular l'enviament a una cita específica en el moment
de la creació. El vincle apareix integrat a tots dos costats:

* a l'enviament, com una matriu `appointments` d'entrades `{ id, added_at }`;
* a la cita, com una matriu `shipments` d'entrades `{ id, added_at }`.

Ambdues matrius ordenen primer el vincle més antic. Cada `id` remet al punt final de detall canònic
([Obtenir una cita](https://docs.anivahealth.com/ca/api/appointments/get-appointment.md) /
[Obtenir un enviament](https://docs.anivahealth.com/ca/api/shipments/get-shipment.md)) per obtenir la càrrega útil completa — els socis que vulguin
el progrés del missatger per cita segueixen cada entrada de la matriu `shipments` de la cita fins al
punt final de detall de l'enviament.

Un enviament es pot vincular a múltiples cites, i una cita es pot vincular a múltiples
enviaments. Després de crear-lo, gestiona la vinculació amb [Vincular cites a un
enviament](https://docs.anivahealth.com/ca/api/shipments/attach-appointments-to-shipment.md) /
[Desvincular cites d'un enviament](https://docs.anivahealth.com/ca/api/shipments/detach-appointments-from-shipment.md). Cada
mutació retorna la llista de cites de l'enviament posterior a la mutació.

La regla de mutació és la següent: els vincles es poden crear o eliminar quan O BÉ la cita ha passat
l'extracció de sang (`blood_drawn`), o bé l'enviament s'ha creat fa menys de 24 hores. Fora d'aquesta
finestra el vincle queda bloquejat perquè els registres històrics es mantinguin estables.

## Cicle de vida

Els enviaments passen pels estats següents:

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

| Estat | Significat |
| - | - |
| `pending` | L'ordre de missatgeria s'ha creat i espera la recollida. |
| `in_transit` | El missatger ha recollit el paquet i és en trànsit. |
| `delivered` | El paquet s'ha lliurat. |
| `fault` | Hi ha hagut un problema durant el trànsit o el transportista ha retornat el paquet al remitent. |
| `cancelled` | L'enviament s'ha cancel·lat. |

Cada canvi d'estat envia un [webhook](https://docs.anivahealth.com/ca/concepts/webhooks.md) `shipment.*`, per exemple
`shipment.delivered`. `shipment.updated` s'activa amb cada canvi que pots llegir, com ara un nou escaneig.

## Regles de l'horari de recollida

S'apliquen les regles següents en crear o actualitzar l'horari de recollida d'un enviament. `pickup_date`
(`YYYY-MM-DD`) i `pickup_time_from` / `pickup_time_till` (`HH:MM`, 24 h) són valors d'hora local
**interpretats en la zona horària IANA de la ubicació d'origen**; no hi envies cap zona horària.

| Regla | Detall |
| - | - |
| **Només dies feiners** | `pickup_date` ha de ser de dilluns a divendres. |
| **Avui o en el futur** | `pickup_date` no pot ser en el passat. |
| **Hora límit el mateix dia** | Les recollides el mateix dia es rebutgen després de les 16:00 Europe/Berlin. |
| **Rang de la franja** | `pickup_time_from` i `pickup_time_till` han d'estar entre les 09:00 i les 19:00. |
| **Franja mínima de 2 h** | La franja de recollida ha de durar com a mínim 2 hores. |

## Modificar enviaments

Pots actualitzar l'horari de recollida, el nombre de paquets, el pes i les notes d'un enviament amb `PATCH /api/v1/shipments/{id}`. Si canvia algun camp rellevant per a la logística (data de recollida, hora, nombre de paquets o pes), l'ordre logística existent es cancel·la automàticament i se'n crea una de nova. Els camps que ometis en el cos de l'actualització es conserven de l'enviament existent; per exemple, si només actualitzes `weight`, es torna a crear l'ordre amb el mateix horari de recollida. Els camps d'horari actualitzats es validen segons les mateixes [regles de l'horari de recollida](#regles-de-l-horari-de-recollida).

> [!WARNING]
>
> Els enviaments no es poden modificar després que el missatger hagi recollit el paquet. Els intents
> d'actualitzar un enviament en estat `in_transit`, `delivered` o `fault` retornen `409 Conflict`.

Si el proveïdor logístic rebutja la cancel·lació o la creació de la nova ordre durant una actualització, l'API retorna `502 Bad Gateway` amb el missatge d'error del proveïdor.

## Cancel·lar enviaments

Cancel·la un enviament amb `DELETE /api/v1/shipments/{id}`. Això crida l'API del proveïdor logístic per cancel·lar l'ordre i actualitza l'estat a `cancelled`.

> [!WARNING]
>
> Els enviaments no es poden cancel·lar després de la recollida. Els intents de cancel·lar un
> enviament que ja està en estat `in_transit`, `delivered` o `fault` retornen `409 Conflict`.
> Cancel·lar-ne un que ja és `cancelled` no té cap efecte i retorna `200` amb l'enviament; consulta
> [Idempotència](https://docs.anivahealth.com/ca/concepts/idempotency.md).

El proveïdor logístic també pot rebutjar la cancel·lació pels seus propis motius (p. ex., ha passat el termini de cancel·lació). En aquest cas, l'API retorna `502 Bad Gateway` amb el missatge d'error i el codi d'error del proveïdor.

### Etiquetes de retorn

Una etiqueta de retorn de DHL forma part de la seva ordre d'anada. DHL no pot cancel·lar l'etiqueta per separat, així que cancel·lar la fila que fa el seguiment d'una etiqueta de retorn retorna `409 Conflict`. En lloc d'això, cancel·la el paquet d'anada mentre sigui `pending`. Això també cancel·la l'etiqueta: cada fila del trajecte de retorn en `pending` del paquet d'anada passa a `cancelled` i rep una entrada `RETURN_LEG_CANCELLED` al seu `status_updates`. Un paquet de retorn que el pacient ja ha enviat per correu continua el seu curs. Un cop enviat el paquet d'anada, l'etiqueta continua sent vàlida i Aniva tanca manualment la fila del trajecte de retorn.

## ID de referència dels enviaments

Cada enviament té un ID de referència d'11 caràcters: una lletra, la data i quatre caràcters, `{letter}YYMMDDXXXX` (per exemple, `P2611194821`). La lletra indica a què pertany l'enviament, mai la seva direcció:

| Lletra | Enviament |
| - | - |
| `P` | Un enviament que crees a través d'aquesta API. |
| `M` | Un enviament que crea l'equip d'Aniva. |
| `C` | Un enviament de l'expedició diària d'Aniva. |
| `K` | Un paquet de kit a domicili. |
| `F`, `S` | Paquets d'estoc propi d'Aniva. |

Un enviament del 20 al 22 de novembre de 2026 conserva el seu ID amb una paraula al davant: `API`, `MAN`, `AUTO` o `KIT` (per exemple, `AUTO261121UWKX`). Tots dos formats continuen sent vàlids. No comprovis la longitud ni la primera lletra d'un ID. Fes servir l'ID per obtenir, actualitzar o cancel·lar l'enviament.

## Adreces dels enviaments

Els camps `origin` i `destination` de la resposta de l'enviament contenen objectes d'adreça resolts amb l'estructura següent:

```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"
}
```

Per a un paquet de consulta, l'adreça `origin` es resol a partir de la ubicació de la prova que has
indicat en el moment de la creació i `destination` és el laboratori que has especificat a
`destination_lab`. Per a un paquet de kit a domicili, l'adreça de lliurament del pacient és
`destination` del kit i `origin` del retorn de la mostra; el centre que empaqueta el kit n'és
`origin`. L'adreça no porta cap `location_id`; relaciona un paquet de consulta mitjançant la cita a
la qual està vinculat.

## Franja de recollida

El camp `pickup` de la resposta de l'enviament conté la franja de recollida programada del
missatger. Inclou les marques de temps `from` i `till` com a instants UTC (ISO 8601 amb el sufix
`Z`, p. ex. `2026-04-15T07:00:00Z`) i una cadena `timezone` (zona horària IANA de la ubicació de
recollida). Els valors d'hora local `pickup_date` / `pickup_time_*` que has enviat en crear o
actualitzar es resolen en aquests instants absoluts amb aquesta zona horària; fes servir `timezone`
per tornar a mostrar `from` / `till` en l'hora local de la ubicació de recollida. El camp és `null`
quan no s'ha programat cap franja de recollida.

## Registre d'actualitzacions d'estat

Cada enviament inclou una matriu `status_updates` amb tots els esdeveniments del cicle de vida que
ha informat el proveïdor logístic, del més antic al més recent. Cada entrada conté:

* `state` — l'esdeveniment en el vocabulari d'estats d'enviament (`pending`, `in_transit`,
  `delivered`, `fault`), perquè puguis llegir la cronologia sense conèixer els codis del
  transportista. `null` quan l'esdeveniment no comporta cap estat (creació d'etiqueta, un escaneig
  sense informació del transportista, entrades registrades abans que existís el camp). Mai
  `cancelled`: una cancel·lació és nostra, no un esdeveniment del transportista.
* `code` — l'identificador d'estat propi del transportista (`GO10`, `GO90`, `GOY001` de GO!; `VA`,
  `ZF`, `LA`, `ZU` de DHL). `null` quan el transportista no n'ha proporcionat cap. Es manté estable
  en les diferents traduccions de `status`.
* `detail_code` — l'identificador més detallat del transportista quan en té un: `statusDetailed` de
  DHL, p. ex. `CNRFC_NRQRD_ZF` (redirigit a una oficina de correus), `HLDCC_SERPT_LA` (llest per
  recollir allà), `DLVRD_SERPT_ZU` (recollit). `null` en la resta de casos.
* `status` — l'etiqueta llegible del transportista (p. ex., `"Shipment picked up"`,
  `"Die Sendung wurde abgeholt."`).
* `description` — una explicació del codi o la frase més llarga del transportista. `null` quan no
  existeix cap de les dues coses.
* `location` — on s'ha fet l'escaneig, tal com l'anomena el transportista: un dipòsit de GO!, una
  ciutat de DHL. Text lliure, no una coordenada.
* `time` — marca de temps ISO 8601 de l'esdeveniment, tal com l'ha informat el transportista (amb
  el seu desplaçament horari).

Quan el transportista retorna el paquet al remitent, la cronologia rep una entrada amb `code`
`RETURNED_TO_SENDER`. El seu camp `status` conté el motiu del transportista. L'enviament es manté
en `fault`, també després que el transportista ens retorni el paquet.

La llista pot estar buida si el transportista encara no ha informat de cap esdeveniment.

Fes servir el camp `status` de nivell superior per conèixer l'estat actual canònic. Avança en un sol
sentit —de `pending` a `in_transit` i a `delivered`—, amb `fault` superposat mentre l'esdeveniment
més recent n'informi; els transportistes no ordenen els seus esdeveniments per rellevància (DHL
afegeix un avís de redirecció amb codi `pre-transit` després de l'escaneig de lliurament), així que
l'entrada més recent per si sola no indica en quin punt es troba un paquet.

## Exemple d'enviament

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

## Exemple de paquets de kit a domicili

`GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-…` retorna el kit de camí al pacient i la mostra de tornada, aparellats:

```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
  }
]
```

La fila del trajecte de retorn existeix des del moment en què s'imprimeix l'etiqueta de retorn i es manté en `pending` fins que el pacient enviï la mostra per correu; aquest és l'estat real, no un buit.


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