Ver categorias

Como Listar Horários Disponíveis para Agendamento Via API

6 minutos de leitura

Sumário
Listar Horários Disponíveis

Resumo #

A API da plataforma eAgenda permite listar horários disponíveis para agendamento, tanto para um dia específico (/api/v3/available-date-times/) quanto para horários aleatórios em um intervalo (/api/v3/available-date-times/random/). Este guia prático detalha como configurar uma requisição HTTP GET para esses endpoints, utilizando parâmetros de consulta para filtrar resultados. Para mais detalhes, consulte a documentação oficial da API da eAgenda.

Preparação do Ambiente #

Antes de começar, você precisará:

  • Chave de API: Acesse o painel da eAgenda para obter seu token Bearer.
  • Ferramenta para requisições HTTP: Use cURL, Postman ou bibliotecas como requests (Python) ou axios (JavaScript).
  • Configuração do cabeçalho: A autenticação é feita via Bearer Token. Configure o cabeçalho Authorization: Bearer <seu-token> e defina accept: application/json.

Dica: Consulte a seção de autenticação na documentação da API para configurar o token corretamente: https://eagenda.com.br/api/v3/documents/#overview.

Definição dos Parâmetros de Consulta #

Parâmetros do Endpoint /available-date-times/ #

Este endpoint lista horários disponíveis para um dia específico. Abaixo estão os parâmetros de query-string:

action_new_appointment (opcional) #

  • Descrição: Define a ação para o agendamento.
  • Valores possíveis:
    • new: Horários disponíveis sem restrições.
    • client: Horários considerando restrições para clientes.
    • waiting: Horários com lista de espera.
    • force: Encaixe em horários ocupados.
  • Impacto: Filtra horários com base na ação desejada.
  • Exemplo: new

calendar_key (obrigatório) #

  • Descrição: Chave UUID da agenda.
  • Impacto: Especifica a agenda para consultar horários.
  • Como obter: Use o endpoint de listagem de agendas (/api/v3/calendars/).
  • Exemplo: 19730681-29d0-4000-88d0-caf575494780

day (obrigatório) #

  • Descrição: Dia da agenda (formato YYYY-MM-DD).
  • Impacto: Filtra horários disponíveis para o dia especificado.
  • Exemplo: 2025-06-01

is_manual (opcional) #

  • Descrição: Indica se a data foi criada manualmente.
  • Impacto: Filtra horários criados manualmente (true) ou automaticamente (false).
  • Exemplo: true

min_vacancies_available (opcional) #

  • Descrição: Quantidade mínima de vagas disponíveis por horário.
  • Impacto: Filtra horários com pelo menos o número especificado de vagas.
  • Exemplo: 1

page (opcional) #

  • Descrição: Número da página nos resultados paginados.
  • Impacto: Navega pelas páginas de resultados.
  • Exemplo: 1

page_size (opcional) #

  • Descrição: Número de resultados por página.
  • Impacto: Define a quantidade de horários retornados por página.
  • Exemplo: 20

service_keys (opcional) #

  • Descrição: Lista de chaves UUID dos serviços.
  • Impacto: Filtra horários disponíveis para serviços específicos.
  • Como obter: Use o endpoint de listagem de serviços (/api/v3/services/).
  • Exemplo: [“19730681-2aa0-4000-84b6-2bc54b4ace01”]

Parâmetros do Endpoint /available-date-times/random/ #

Este endpoint lista horários aleatórios disponíveis em um intervalo. Abaixo estão os parâmetros de query-string:

calendar_key (obrigatório) #

  • Descrição: Chave UUID da agenda.
  • Impacto: Especifica a agenda para consultar horários.
  • Como obter: Use o endpoint de listagem de agendas (/api/v3/calendars/).
  • Exemplo: 19730681-29d0-4000-88d0-caf575494780

end_date (opcional) #

  • Descrição: Data final do agendamento (formato ISO 8601).
  • Impacto: Limita os horários até a data especificada.
  • Exemplo: 2025-06-30T23:59:59Z

min_vacancies_available (opcional) #

  • Descrição: Quantidade mínima de vagas disponíveis por horário.
  • Impacto: Filtra horários com pelo menos o número especificado de vagas.
  • Exemplo: 1

page (opcional) #

  • Descrição: Número da página nos resultados paginados.
  • Impacto: Navega pelas páginas de resultados.
  • Exemplo: 1

page_size (opcional) #

  • Descrição: Número de resultados por página.
  • Impacto: Define a quantidade de horários retornados por página.
  • Exemplo: 20

quantity (opcional) #

  • Descrição: Quantidade de horários a retornar.
  • Impacto: Define o número de horários aleatórios retornados.
  • Exemplo: 5

service_keys (opcional) #

  • Descrição: Lista de chaves UUID dos serviços.
  • Impacto: Filtra horários disponíveis para serviços específicos.
  • Como obter: Use o endpoint de listagem de serviços (/api/v3/services/).
  • Exemplo: [“19730681-2aa0-4000-84b6-2bc54b4ace01”]

start_date (opcional) #

  • Descrição: Data inicial do agendamento (formato ISO 8601).
  • Impacto: Limita os horários a partir da data especificada.
  • Exemplo: 2025-06-01T00:00:00Z

Nota: Para o endpoint /available-date-times/, calendar_key e day são obrigatórios. Para /available-date-times/random/, apenas calendar_key é obrigatório. Outros parâmetros são opcionais para maior flexibilidade.

Envio da Requisição para Listar Horários #

Para listar horários disponíveis, envie uma requisição HTTP GET para um dos endpoints:

  • Para um dia específico: https://eagenda.com.br/api/v3/available-date-times/
  • Para horários aleatórios: https://eagenda.com.br/api/v3/available-date-times/random/

Configuração da Requisição #

  • Método: GET
  • Cabeçalhos:
    • accept: application/json
    • Authorization: Bearer <seu-token>
  • Query-string: Parâmetros de filtro (ex.: ?calendar_key=19730681-29d0-4000-88d0-caf575494780&day=2025-06-01).

Exemplo de Requisição com cURL #

Para /available-date-times/ #

curl -X GET "https://eagenda.com.br/api/v3/available-date-times/?calendar_key=19730681-29d0-4000-88d0-caf575494780&day=2025-06-01&action_new_appointment=new&min_vacancies_available=1" \
-H "accept: application/json" \
-H "Authorization: Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999"

Para /available-date-times/random/ #

curl -X GET "https://eagenda.com.br/api/v3/available-date-times/random/?calendar_key=19730681-29d0-4000-88d0-caf575494780&start_date=2025-06-01T00:00:00Z&quantity=5" \
-H "accept: application/json" \
-H "Authorization: Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999"

Exemplo em Python (usando requests) #

Para /available-date-times/ #

import requests

url = "https://eagenda.com.br/api/v3/available-date-times/"
headers = {
    "accept": "application/json",
    "Authorization": "Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999"
}
params = {
    "calendar_key": "19730681-29d0-4000-88d0-caf575494780",
    "day": "2025-06-01",
    "action_new_appointment": "new",
    "min_vacancies_available": 1
}

response = requests.get(url, headers=headers, params=params)
print(response.status_code)
print(response.json())

Para /available-date-times/random/ #

import requests

url = "https://eagenda.com.br/api/v3/available-date-times/random/"
headers = {
    "accept": "application/json",
    "Authorization": "Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999"
}
params = {
    "calendar_key": "19730681-29d0-4000-88d0-caf575494780",
    "start_date": "2025-06-01T00:00:00Z",
    "quantity": 5
}

response = requests.get(url, headers=headers, params=params)
print(response.status_code)
print(response.json())

Verificação da Resposta #

A API retornará uma resposta com o status da consulta e os horários disponíveis. Verifique os seguintes pontos:

  • Código de status HTTP:
    • 200 OK: Lista de horários retornada com sucesso.
    • 400 Bad Request: Erro nos parâmetros de consulta (verifique a formatação).
    • 401 Unauthorized: Token inválido ou ausente.
  • Corpo da resposta: Contém uma lista paginada de horários, com detalhes como:{ "count": 1, "next": null, "previous": null, "results": [ { "calendar": { "calendar_key": "19730681-29d0-4000-88d0-caf575494780", "calendar_name": "Agenda Principal" }, "day": "2025-06-01", "start_date": "2025-06-01T08:00:00Z", "end_date": "2025-06-01T08:30:00Z", "booked": false, "blocked": false, "max_number_people": 10, "number_people": 0, "number_available": 10, "is_open": true } ] }

Os horários retornados respeitam os filtros aplicados. Use os campos next e previous para navegar pelas páginas de resultados.

Conclusão #

Com este tutorial, você aprendeu como listar horários disponíveis para agendamento via API da eAgenda, utilizando os endpoints /api/v3/available-date-times/ e /api/v3/available-date-times/random/. Essa integração é ideal para automatizar a consulta de horários, facilitando a criação de agendamentos. Para mais funcionalidades, como criação de agendas ou agendamentos, consulte a documentação completa da API da eAgenda.

Entre em Contato ou Saiba Mais #

Estamos à disposição para ajudar! Acesse nossos canais oficiais:

📞 WhatsApp : Clique aqui para nos enviar uma mensagem
🌐 Plataforma eAgenda : Conheça o eAgenda
🏢 Nossa Empresa : Mupi Systems – Soluções Inovadoras
📧 E-mail : contato@mupisystems.com.br
📚 Tutoriais e Documentação : Acesse nossos guias e tutoriais

Quais são seus sentimentos

Desenvolvido por BetterDocs