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

# Envios

> Como funciona a logística na API da Aniva: envios de amostras para o laboratório e encomendas de kits de teste em casa, com seguimento e estado.

Um envio é uma encomenda física: uma recolha por estafeta que transporta amostras de sangue de um local de teste para um laboratório, o kit a caminho de um paciente de kit de teste em casa ou a amostra que esse paciente envia de volta por correio. A API de Envios permite-te criar, seguir, modificar e cancelar pedidos de envio, e lista todas as encomendas num só lugar, independentemente de quem as reservou.

## Uma lista, filtrada

`GET /api/v1/shipments` é a única coleção. Um envio existe de forma independente — tem uma relação muitos-para-muitos com marcações e pode pertencer a um pedido de kit de teste em casa — pelo que não existe nenhuma lista aninhada sob um recurso pai. Filtra a mesma lista com `?appointment_id=` ou `?home_kit_order_id=`, pagina-a com `limit` / `offset` e segue o array `shipments` inline de um recurso pai (`{ id, added_at }` tanto em marcações como em pedidos de kit de teste em casa) até [Obter envio](https://docs.anivahealth.com/pt/api/shipments/get-shipment.md) quando tiveres um ID.

## Conteúdo e quem reservou

Cada envio contém dois dados que não são visíveis a partir das suas moradas:

* `contents` — texto livre que descreve o que está na encomenda, definido na criação (`"Medizinisch freigestellte Probe"`, `"Home test kit"`) e mostrado ao estafeta. Apenas informativo. A direção não é um campo: se uma encomenda segue para um laboratório, isso lê-se em `destination`.
* `booked_by` — quem imprimiu a etiqueta: `aniva` ou `external`. Apenas os envios `aniva` aceitam [Atualizar](https://docs.anivahealth.com/pt/api/shipments/update-shipment.md) e [Cancelar](https://docs.anivahealth.com/pt/api/shipments/cancel-shipment.md); uma encomenda `external` é seguida na mesma lista, mas devolve `501` em ambos os casos.

Uma encomenda que levou uma etiqueta de devolução e a encomenda que essa etiqueta traz de volta apontam uma para a outra através de `paired_with`.

## Acesso

* Podes ler uma encomenda quando pelo menos uma marcação ou um pedido de kit de teste em casa associado está no teu contexto de acesso, ou quando partiu de um local no teu contexto de acesso.
* `appointments` e `home_kit_orders` listam apenas as marcações e os pedidos no teu contexto de acesso.
* [Atualizar](https://docs.anivahealth.com/pt/api/shipments/update-shipment.md), [Cancelar](https://docs.anivahealth.com/pt/api/shipments/cancel-shipment.md), [Associar marcações](https://docs.anivahealth.com/pt/api/shipments/attach-appointments-to-shipment.md) e [Desassociar marcações](https://docs.anivahealth.com/pt/api/shipments/detach-appointments-from-shipment.md) requerem que todos os pedidos de kit de teste em casa associados estejam no teu contexto de acesso. Caso contrário, a chamada devolve `403` e apenas a Aniva pode alterar a encomenda.

## As leituras nunca chamam a transportadora

Cada leitura é servida a partir da nossa base de dados. Uma sincronização em segundo plano reconcilia cada envio com a respetiva transportadora (a cada 10 minutos para a GO!, de hora a hora para a DHL) e regista `synced_at`, que indica a antiguidade de qualquer resposta. Não existe atualização forçada — a DHL permite uma chamada de seguimento a cada cinco segundos, pelo que não seria possível oferecer uma leitura com consulta direta à transportadora.

## Criar um envio

Ao criar um envio, especificas o `location_id` de origem — o local de teste onde o estafeta deve fazer a recolha. Também indicas o laboratório de destino com `destination_lab`. O envio segue para a morada de envio registada desse laboratório.

O local tem de estar dentro do contexto de acesso da tua chave de API. Usa [Listar locais](https://docs.anivahealth.com/pt/api/locations/list-locations.md) para encontrar os IDs de local disponíveis.

Podes opcionalmente passar `appointment_id` para associar o envio a uma marcação específica no
momento da criação. A associação aparece inline em ambos os lados:

* no envio, como um array `appointments` de entradas `{ id, added_at }`;
* na marcação, como um array `shipments` de entradas `{ id, added_at }`.

Ambos os arrays estão ordenados da associação mais antiga para a mais recente. Cada `id` remete para o endpoint de detalhes canónico
([Obter marcação](https://docs.anivahealth.com/pt/api/appointments/get-appointment.md) /
[Obter envio](https://docs.anivahealth.com/pt/api/shipments/get-shipment.md)) para obter o payload completo — os parceiros que pretendam
acompanhar a evolução do estafeta por marcação seguem cada entrada no array `shipments` da marcação até
ao endpoint de detalhes do envio.

Um envio pode ser associado a várias marcações, e uma marcação pode ser associada a vários
envios. Após a criação, gere a associação com [Associar marcações a
envio](https://docs.anivahealth.com/pt/api/shipments/attach-appointments-to-shipment.md) /
[Desassociar marcações de envio](https://docs.anivahealth.com/pt/api/shipments/detach-appointments-from-shipment.md). Cada
mutação devolve a lista de marcações do envio após a mutação.

A regra de mutação é: as associações podem ser criadas ou removidas quando OU a marcação já passou a
colheita de sangue (`blood_drawn`), ou o envio foi criado há menos de 24 horas. Fora dessa
janela, a associação fica bloqueada para que os registos históricos permaneçam estáveis.

## Ciclo de vida

Os envios passam pelos seguintes estados:

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

| Estado | Significado |
| - | - |
| `pending` | O pedido ao estafeta foi feito e aguarda recolha. |
| `in_transit` | O estafeta recolheu a encomenda e esta está em trânsito. |
| `delivered` | A encomenda foi entregue. |
| `fault` | Ocorreu um problema durante o trânsito, ou a transportadora devolveu a encomenda ao remetente. |
| `cancelled` | O envio foi cancelado. |

Cada alteração de estado envia um [webhook](https://docs.anivahealth.com/pt/concepts/webhooks.md) `shipment.*`, por exemplo
`shipment.delivered`. `shipment.updated` dispara em cada alteração que podes ler, como uma nova leitura.

## Regras de agendamento de recolha

As seguintes regras aplicam-se ao criar ou atualizar o agendamento de recolha de um envio. `pickup_date`
(`YYYY-MM-DD`) e `pickup_time_from` / `pickup_time_till` (`HH:MM`, 24 h) são valores de hora local
**interpretados no fuso horário IANA do local de origem** — não envias um fuso horário com eles.

| Regra | Detalhe |
| - | - |
| **Apenas dias úteis** | `pickup_date` tem de ser de segunda a sexta-feira. |
| **Hoje ou futuro** | `pickup_date` não pode estar no passado. |
| **Limite no próprio dia** | Recolhas no próprio dia são rejeitadas após as 16:00 Europe/Berlin. |
| **Intervalo da janela** | `pickup_time_from` e `pickup_time_till` têm de estar entre as 09:00 e as 19:00. |
| **Janela mínima de 2 h** | A janela de recolha tem de ter pelo menos 2 horas de duração. |

## Modificar envios

Podes atualizar o agendamento de recolha, o número de volumes, o peso e as notas de um envio usando `PATCH /api/v1/shipments/{id}`. Se algum campo relevante para a logística mudar (data de recolha, hora, número de volumes ou peso), o pedido logístico existente é cancelado automaticamente e é criado um novo. Os campos que omites no corpo da atualização são mantidos do envio existente — por exemplo, atualizar apenas `weight` volta a criar o pedido com o mesmo agendamento de recolha. Os campos de agendamento atualizados são validados com as mesmas [regras de agendamento de recolha](#regras-de-agendamento-de-recolha).

> [!WARNING]
>
> Os envios não podem ser modificados depois de o estafeta recolher a encomenda. Tentativas de atualizar um
> envio nos estados `in_transit`, `delivered` ou `fault` devolvem `409 Conflict`.

Se o operador logístico rejeitar o cancelamento ou a nova criação durante uma atualização, a API devolve `502 Bad Gateway` com a mensagem de erro do operador.

## Cancelar envios

Cancela um envio usando `DELETE /api/v1/shipments/{id}`. Isto chama a API do operador logístico para cancelar o pedido e atualiza o estado para `cancelled`.

> [!WARNING]
>
> Os envios não podem ser cancelados após a recolha. Tentativas de cancelar um envio que já está
> em `in_transit`, `delivered` ou `fault` devolvem `409 Conflict`. Cancelar um que já está
> `cancelled` não tem efeito e devolve `200` com o envio — vê
> [Idempotência](https://docs.anivahealth.com/pt/concepts/idempotency.md).

O operador logístico pode também rejeitar o cancelamento por motivos próprios (por exemplo, o prazo de cancelamento já passou). Nesse caso, a API devolve `502 Bad Gateway` com a mensagem de erro e o código de erro do operador.

### Etiquetas de devolução

Uma etiqueta de devolução da DHL faz parte do respetivo pedido de ida. A DHL não pode cancelar a etiqueta isoladamente, pelo que cancelar a linha que acompanha uma etiqueta de devolução devolve `409 Conflict`. Em vez disso, cancela a encomenda de ida enquanto estiver em `pending`. Isso cancela a etiqueta em conjunto: cada linha do trajeto de devolução em `pending` da encomenda de ida passa a `cancelled` e recebe uma entrada `RETURN_LEG_CANCELLED` no seu `status_updates`. Uma encomenda de devolução que o paciente já enviou pelo correio continua o percurso. Depois de a encomenda de ida ser expedida, a etiqueta mantém-se válida e a Aniva fecha manualmente a linha do trajeto de devolução.

## IDs de referência de envio

Cada envio tem um ID de referência de 11 caracteres: uma letra, a data e quatro caracteres, `{letter}YYMMDDXXXX` (por exemplo, `P2611194821`). A letra indica a que pertence o envio, nunca a sua direção:

| Letra | Envio |
| - | - |
| `P` | Um envio que crias através desta API. |
| `M` | Um envio que a equipa da Aniva cria. |
| `C` | Um envio da expedição diária da Aniva. |
| `K` | Uma encomenda de kit para casa. |
| `F`, `S` | Encomendas de stock próprio da Aniva. |

Um envio de 20 a 22 de novembro de 2026 mantém o seu ID com uma palavra no início: `API`, `MAN`, `AUTO` ou `KIT` (por exemplo, `AUTO261121UWKX`). Ambos os formatos continuam válidos. Não verifiques o comprimento nem a primeira letra de um ID. Usa o ID para obter, atualizar ou cancelar o envio.

## Moradas de envio

Os campos `origin` e `destination` na resposta do envio contêm objetos de morada resolvidos com a seguinte estrutura:

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

Para uma encomenda de clínica, a morada `origin` é resolvida a partir do local de análise que indicaste na
criação e `destination` é o laboratório que indicaste em `destination_lab`.
Para uma encomenda de kit para casa, a morada de entrega do paciente é o `destination` do kit e o
`origin` da devolução da amostra; o local que embala o kit é o seu `origin`. A
morada não inclui `location_id` — relaciona uma encomenda de clínica através da marcação à qual está
associada.

## Janela de recolha

O campo `pickup` na resposta do envio contém a janela de recolha agendada para o estafeta. Inclui
os timestamps `from` e `till` como instantes UTC (ISO 8601 com sufixo `Z`, por exemplo
`2026-04-15T07:00:00Z`) e uma string `timezone` (fuso horário IANA do local de recolha). Os valores de
hora local `pickup_date` / `pickup_time_*` que enviaste na criação ou atualização são resolvidos nestes
instantes absolutos com esse fuso horário — usa `timezone` para apresentar `from` / `till` de volta na
hora local do local de recolha. O campo é `null` quando não foi agendada nenhuma janela de recolha.

## Registo de atualizações de estado

Cada envio inclui um array `status_updates` — todos os eventos do ciclo de vida que o operador logístico
comunicou, do mais antigo para o mais recente. Cada entrada contém:

* `state` — o evento no vocabulário de estados de envio (`pending`, `in_transit`, `delivered`,
  `fault`), para que possas ler uma linha temporal sem conhecer os códigos da transportadora. `null` quando o evento
  não tem estado (criação de etiqueta, uma leitura sem informação da transportadora, entradas registadas antes de o
  campo existir). Nunca `cancelled` — um cancelamento é nosso, não um evento da transportadora.
* `code` — o próprio código de estado da transportadora (`GO10`, `GO90`, `GOY001` da GO!; `VA`, `ZF`,
  `LA`, `ZU` da DHL). `null` quando a transportadora não forneceu nenhum. Estável independentemente da tradução de
  `status`.
* `detail_code` — o código mais detalhado da transportadora quando existe: `statusDetailed` da DHL, por exemplo
  `CNRFC_NRQRD_ZF` (redirecionada para um posto de correios), `HLDCC_SERPT_LA` (pronta para levantamento aí),
  `DLVRD_SERPT_ZU` (levantada). `null` nos restantes casos.
* `status` — o texto legível da transportadora (por exemplo `"Shipment picked up"`,
  `"Die Sendung wurde abgeholt."`).
* `description` — uma explicação do código, ou a frase mais longa da transportadora. `null` quando
  nenhuma existe.
* `location` — onde ocorreu a leitura, conforme o nome dado pela transportadora: um depósito da GO!, uma cidade da DHL. Texto
  livre, não uma coordenada.
* `time` — timestamp ISO 8601 do evento, conforme comunicado pela transportadora (com o respetivo offset).

Quando a transportadora devolve a encomenda ao remetente, a linha temporal recebe uma entrada com `code`
`RETURNED_TO_SENDER`. O respetivo `status` contém o motivo da transportadora. O envio mantém-se então em `fault`, mesmo
depois de a transportadora nos devolver a encomenda.

A lista pode estar vazia se a transportadora ainda não comunicou nenhum evento.

Usa o campo `status` de topo para o estado atual canónico. Avança num só sentido — de `pending`
para `in_transit` e para `delivered` — com `fault` sobreposto enquanto o evento mais recente indicar um problema;
as transportadoras não ordenam os eventos por relevância (a DHL acrescenta um aviso de redirecionamento
com código `pre-transit` após a leitura de entrega), pelo que a entrada mais recente por si só não indica onde está a encomenda.

## Exemplo de envio

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

## Exemplo de encomendas de kit para casa

`GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-…` devolve o kit a caminho do paciente e a amostra a caminho de volta, em par:

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

A linha do trajeto de devolução existe desde o momento em que a etiqueta de devolução é impressa e mantém-se em `pending` até o paciente enviar a amostra pelo correio — esse é o estado real, não uma falha.


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