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

# Locais

> Como funcionam os locais de análises na API da Aniva: farmácias e clínicas que fazem colheitas de sangue, horários de funcionamento, disponibilidade e preços ao público.

Um local é um centro de análises físico onde profissionais de saúde realizam colheitas de sangue. Usas o `id` de um local para agendar marcações `practitioner`.

> [!NOTE]
>
> A tua chave API só devolve locais dentro do teu contexto de acesso de parceiro. Usa `GET
>     /api/v1/locations` para listar todos os locais disponíveis para ti.

Um [webhook](https://docs.anivahealth.com/pt/concepts/webhooks.md) `location.*` avisa-te quando um local aparece, muda ou desaparece.

## Campos

**id** `string` *required*

UUID do local. Passa-o como `location_id` ao criar uma marcação.

**name** `string` *required*

Nome de apresentação do local.

**company\_name** `string`

Clínica ou empresa que opera o local. Pode ser null.

**street** `string`

Nome da rua, sem o número de porta. Pode ser null.

**house\_number** `string`

Número de porta. Pode ser null.

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

Linha de morada adicional — a/c, edifício ou andar. Pode ser null.

**city** `string`

Cidade. Pode ser null.

**state** `string`

Estado ou província (resolvido através do estado associado à cidade). Pode ser null quando a
cidade não tem estado associado.

**state\_code** `string`

Código [ISO 3166-2](https://www.iso.org/iso-3166-country-codes.html) do estado sem o
prefixo do país (por ex., `BW` para Baden-Württemberg). Pode ser nulo.

**postal\_code** `string`

Código postal ou ZIP. Pode ser nulo.

**country\_name** `string`

Nome completo do país (por ex., `Germany`). Pode ser nulo.

**country\_code** `string`

Código de país de duas letras segundo [ISO 3166-1 alpha-2](https://www.iso.org/iso-3166-country-codes.html)
(por ex., `DE`, `US`). Pode ser nulo.

**timezone** `string`

Identificador de fuso horário IANA do local (por ex., `Europe/Berlin`, `America/New_York`). Usa-o para
mostrar os horários marcados na hora local correta. Pode ser nulo.

**latitude** `number`

Latitude da morada em graus decimais (WGS 84). Pode ser nulo.

**longitude** `number`

Longitude da morada em graus decimais (WGS 84). Pode ser nulo.

**contact\_phone** `string`

Número de telefone do local. Pode ser nulo.

**email** `string`

Endereço de email do local. Pode ser nulo.

**website** `string`

URL do site do local. Pode ser nulo.

**google\_maps\_url** `string`

Ligação direta para o local no Google Maps. Pode ser nulo.

**image\_url** `string`

URL de uma fotografia do local. Pode ser nulo.

**open\_hours** `object`

Horário de funcionamento semanal do local. Cada chave de dia da semana (`monday`–`sunday`) corresponde a um array de
intervalos horários `{ open, close }` no formato `HH:MM` (24h). Um array vazio significa que o local está fechado
nesse dia. Pode ser nulo se o horário não estiver disponível para o local.

**default\_draw\_method** `string` *required*

Como o sangue é colhido numa marcação neste local, a menos que a marcação defina o seu próprio
`draw_method`: `capillary` (ponta do dedo ou parte superior do braço, para microtubos) ou
`venous` (da veia, para tubos).

**draw\_methods** `string[]` *required*

Os métodos de colheita para os quais o local tem recipientes em stock, ordenados. Uma marcação
neste local só pode definir um destes como o seu `draw_method`.

> [!TIP]
>
> Usa sempre o campo `timezone` para converter as datas e horas de `scheduled_at` para a hora local antes
> de as mostrar aos pacientes ou à equipa.

## Disponibilidade

O campo `open_hours` acima descreve o horário de funcionamento semanal estático. Para mostrar horários reais disponíveis para marcação — e evitar marcações duplicadas com marcações Aniva já existentes — chama [Obter disponibilidade](https://docs.anivahealth.com/pt/api/locations/get-availability.md) para o local e passa o intervalo de datas que queres mostrar. Esse endpoint é a fonte de verdade certa para qualquer interface de marcação: expande `open_hours` na grelha de horários do local, aplica exceções por data, subtrai as marcações já feitas e aplica a [antecedência mínima](https://docs.anivahealth.com/pt/api/appointments/create-appointment.md#antecedencia-minima).

## Preços de retalho

Uma farmácia define o seu próprio preço para cada painel, e para cada biomarcador individual, que vende a clientes sem
marcação. Só vês um preço depois de a farmácia o publicar.
[Listar preços de retalho](https://docs.anivahealth.com/pt/api/locations/list-retail-prices.md) devolve-os para cada local que podes
ler, e [Obter preços de retalho](https://docs.anivahealth.com/pt/api/locations/get-retail-prices.md) devolve-os para um local. Ambos
precisam do scope `retail_prices_view`; `locations_view` não os inclui. Pede ambos os scopes para
os mesmos locais.

Um [webhook](https://docs.anivahealth.com/pt/concepts/webhooks.md) `location.retail_prices.updated` avisa-te quando um preço muda.
`location.created` e `location.deactivated` avisam-te quando um local aparece ou desaparece. Uma alteração aos
painéis que um local oferece pode chegar-te mais tarde do que uma alteração de preço, por isso lê Listar preços de retalho
novamente uma vez por dia.

## Exemplo de local

```json theme={null}
{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "name": "Mitte Health Center",
  "company_name": "Aniva Berlin GmbH",
  "street": "Friedrichstraße",
  "house_number": "100",
  "address_line_2": null,
  "city": "Berlin",
  "state": "Berlin",
  "state_code": "BE",
  "postal_code": "10117",
  "country_name": "Germany",
  "country_code": "DE",
  "timezone": "Europe/Berlin",
  "latitude": 52.531677,
  "longitude": 13.388042,
  "contact_phone": "+493012345678",
  "email": "berlin@anivahealth.com",
  "website": "https://anivahealth.com",
  "google_maps_url": "https://maps.google.com/?q=Friedrichstra%C3%9Fe+100+Berlin",
  "image_url": "https://anivahealth.com/images/locations/berlin-mitte.jpg",
  "open_hours": {
    "monday": [{ "open": "08:00", "close": "18:00" }],
    "tuesday": [{ "open": "08:00", "close": "18:00" }],
    "wednesday": [{ "open": "08:00", "close": "18:00" }],
    "thursday": [{ "open": "08:00", "close": "18:00" }],
    "friday": [{ "open": "08:00", "close": "16:00" }],
    "saturday": [],
    "sunday": []
  },
  "default_draw_method": "venous",
  "draw_methods": ["venous"]
}
```


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