Consultar a disponibilidade de horários é uma das operações mais comuns ao integrar com a API do eAgenda. Este tutorial cobre todos os cenários de consulta.

Endpoint principal

GET /api/v3/available-date-times/

Parâmetros obrigatórios

Parâmetro	Tipo	Descrição
`calendar_key`	UUID	Chave da agenda
`day`	date	Data no formato `YYYY-MM-DD`

Parâmetros opcionais

Parâmetro	Tipo	Descrição
`service_keys`	UUID[]	Filtrar por serviços específicos
`action_new_appointment`	string	Tipo de ação (ver tabela abaixo)
`min_vacancies_available`	number	Mínimo de vagas disponíveis (padrão: 1)
`is_manual`	boolean	Incluir apenas horários criados manualmente

Valores de `action_new_appointment`

Valor	Descrição
`new`	Horários disponíveis sem restrições
`client`	Horários considerando restrições para clientes
`waiting`	Horários com lista de espera
`force`	Agendamento em horários já ocupados

Consulta básica

curl -X GET "https://eagenda.com.br/api/v3/available-date-times/?calendar_key=abc12345-...&day=2026-06-10" \
  -H "Authorization: Basic SEU_TOKEN"

Resposta:

{
  "count": 10,
  "results": [
    {
      "start_date": "2026-06-10T08:00:00-03:00",
      "end_date": "2026-06-10T08:30:00-03:00",
      "vacancies_available": 3
    },
    {
      "start_date": "2026-06-10T08:30:00-03:00",
      "end_date": "2026-06-10T09:00:00-03:00",
      "vacancies_available": 2
    }
  ]
}

Filtrar por serviço

Para ver horários compatíveis com serviços específicos:

curl -X GET "https://eagenda.com.br/api/v3/available-date-times/?calendar_key=abc12345-...&day=2026-06-10&service_keys=srv12345-..." \
  -H "Authorization: Basic SEU_TOKEN"

Você pode filtrar por múltiplos serviços repetindo o parâmetro:

?service_keys=srv-1&service_keys=srv-2

Consultar vários dias

A API retorna horários de um dia por vez. Para consultar uma semana, faça múltiplas requisições:

import requests
from datetime import date, timedelta

BASE_URL = "https://eagenda.com.br/api/v3"
AUTH = ("meu@email.com", "minha_senha")
CALENDAR_KEY = "abc12345-1234-5678-9abc-def012345678"

start = date(2026, 6, 10)
available_slots = []

for i in range(7):
    day = start + timedelta(days=i)
    response = requests.get(
        f"{BASE_URL}/available-date-times/",
        auth=AUTH,
        params={
            "calendar_key": CALENDAR_KEY,
            "day": day.isoformat(),
        }
    ).json()

    for slot in response["results"]:
        available_slots.append(slot)
        print(f"{slot['start_date']} — {slot['vacancies_available']} vaga(s)")

Horários aleatórios

Para cenários onde o cliente aceita qualquer horário disponível (ex: próxima vaga):

GET /api/v3/available-date-times/random/

curl -X GET "https://eagenda.com.br/api/v3/available-date-times/random/?calendar_key=abc12345-...&quantity=3" \
  -H "Authorization: Basic SEU_TOKEN"

Parâmetros específicos

Parâmetro	Tipo	Descrição
`quantity`	number	Quantidade de horários a retornar (padrão: 1)
`start_date`	datetime	Data/hora mínima
`end_date`	datetime	Data/hora máxima

Consultar dias com disponibilidade

Para saber quais dias do mês têm horários disponíveis:

GET /api/v3/days/

curl -X GET "https://eagenda.com.br/api/v3/days/?calendar_key=abc12345-...&start_date=2026-06-01&end_date=2026-06-30" \
  -H "Authorization: Basic SEU_TOKEN"

Use este endpoint para montar um calendário visual mostrando ao usuário quais dias estão disponíveis antes de consultar os horários específicos.

Dicas de implementação

Cache moderado — Horários mudam frequentemente. Não faça cache por mais de 1-2 minutos
Verifique antes de agendar — Sempre confirme a disponibilidade logo antes de criar o agendamento, pois outro cliente pode ter reservado o horário
Use action_new_appointment=client — Para respeitar as regras de agendamento configuradas pelo administrador
Paginação — Para agendas com muitos horários, use page e page_size para paginar os resultados