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

# Obter disponibilidade

> Obter os horários de início disponíveis para marcação num único local

Devolve os horários de início disponíveis para reserva numa única localização ao longo do período pedido. Os horários são
gerados a partir de `open_hours` da localização, ignorando datas bloqueadas globais / por localização e
subtraindo as marcações Aniva já reservadas, para que o resultado reflita o que os teus pacientes podem
realmente reservar do lado do cliente.

Requer o scope `appointments_schedule`. A localização também tem de estar abrangida pelo contexto de acesso de grupo de localizações da tua chave de API.

> [!NOTE]
>
> Usa este endpoint em vez de deduzires a disponibilidade a partir do `open_hours` estático devolvido por [Listar
> localizações](https://docs.anivahealth.com/pt/api/locations/list-locations.md) — apenas este endpoint tem em conta reservas em tempo real,
> exceções de horário por data e o [aviso
> prévio mínimo](https://docs.anivahealth.com/pt/api/appointments/create-appointment.md#antecedencia-minima) de 12 horas nas localizações geridas pela Aniva. Todos os
> horários devolvidos aqui podem ser reservados tal como estão.

As respostas incluem `Cache-Control: private, max-age=30, stale-while-revalidate=60`, pelo que um navegador pode
servir uma resposta em cache durante até \~30 segundos — um horário reservado nesse intervalo pode continuar a aparecer
como disponível até à atualização seguinte. Apresenta também os conflitos no momento da marcação.

## Parâmetros de caminho

**id** `string` *required*

Identificador da localização (UUID). Usa o `id` obtido em [Listar localizações](https://docs.anivahealth.com/pt/api/locations/list-locations.md).

## Parâmetros de consulta

**start\_date** `string`

Início inclusivo do período em `YYYY-MM-DD` (interpretado em `timezone`). Opcional. Por predefinição é
**hoje** quando nenhuma data é fornecida, ou **`end_date − 30 days`** quando apenas `end_date` é
fornecida. Datas passadas são silenciosamente ajustadas para hoje.

**end\_date** `string`

Fim inclusivo do período em `YYYY-MM-DD` (interpretado em `timezone`). Opcional. Por predefinição é
**hoje + 30 dias** quando nenhuma data é fornecida, ou **`start_date + 30 days`** quando apenas
`start_date` é fornecida. Tem de ser igual ou posterior a `start_date` e dentro de 90 dias a partir de hoje.

**timezone** `string`

Fuso horário IANA (por ex., `Europe/Berlin`) usado para interpretar `start_date` / `end_date` e para agrupar
horários por data de calendário. Opcional — usa por predefinição o fuso horário da própria localização. As horas de início dos horários
em si são sempre devolvidas como instantes UTC (`Z`) e nunca mudam com este parâmetro — a
grelha de horários é sempre projetada a partir do fuso horário da própria localização; o parâmetro apenas afeta em que
dia de calendário cada horário é agrupado. As entradas de dias na resposta cobrem exatamente
`start_date`..`end_date` como dias de calendário neste fuso horário. Omite-o, a menos que apresentes o seletor
noutro fuso horário.

## Resposta

Em caso de sucesso, a API devolve `200 OK` com um único objeto de disponibilidade.

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

Identificador da localização repetido.

**timezone** `string` *required*

Fuso horário IANA em que a resposta é apresentada (por ex., `Europe/Berlin`) — repete o parâmetro de consulta `timezone`
quando fornecido, caso contrário o fuso horário da própria localização.

**slot\_interval\_minutes** `integer`

Intervalo em minutos entre inícios consecutivos de horários disponíveis para reserva. O passo da grelha configurado pela localização —
todos os horários em `availability` seguem esta grelha. `null` apenas quando a localização não tem configuração
de agendamento. **Não é uma janela de duração da marcação:** reservas sobrepostas com inícios diferentes não
entram em conflito; apenas colisões no mesmo início exato contam para a concorrência.

**availability** `array` *required*

Horários disponíveis para reserva por dia. Os dias sem horários disponíveis são omitidos para manter o payload leve.
Cada entrada tem:

**entrada por dia**

**date** `string` *required*

Data de calendário no `timezone` da resposta (`YYYY-MM-DD`).

**slots** `array` *required*

Inícios dos horários como instantes UTC (ISO 8601 com sufixo `Z`), ordenados de forma crescente.

## Respostas de erro

| Estado | Descrição |
| - | - |
| `400` | ID de localização inválido, formato de data ou fuso horário inválido, `end_date` anterior a `start_date` ou `end_date` mais de 90 dias no futuro. |
| `403` | Proibido — falta o scope `appointments_schedule` ou a localização está fora do teu contexto de acesso. |
| `404` | Localização não encontrada ou inativa. |
| `500` | Erro interno do servidor. |

```bash cURL theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/locations/b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b/availability?start_date=2026-05-01&end_date=2026-05-07' \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
{
  "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
  "timezone": "Europe/Berlin",
  "slot_interval_minutes": 15,
  "availability": [
    {
      "date": "2026-05-04",
      "slots": ["2026-05-04T07:00:00Z", "2026-05-04T07:15:00Z", "2026-05-04T07:30:00Z"]
    },
    {
      "date": "2026-05-05",
      "slots": ["2026-05-05T06:00:00Z", "2026-05-05T06:15:00Z"]
    }
  ]
}
```


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