Listar Horarios Disponibles

Resumen

La API de la plataforma eAgenda permite listar horarios disponibles para programación, tanto para un día específico (/api/v3/available-date-times/) como para horarios aleatorios en un intervalo (/api/v3/available-date-times/random/). Esta guía práctica detalla cómo configurar una solicitud HTTP GET para estos endpoints, utilizando parámetros de consulta para filtrar resultados. Para más detalles, consulte la documentación oficial de la API de eAgenda.

Preparación del Entorno

Antes de comenzar, necesitará:

Clave de API: Acceda al panel de eAgenda para obtener su token Bearer.
Herramienta para solicitudes HTTP: Use cURL, Postman o bibliotecas como requests (Python) o axios (JavaScript).
Configuración del encabezado: La autenticación se realiza mediante Bearer Token. Configure el encabezado Authorization: Bearer y defina accept: application/json.

Consejo: Consulte la sección de autenticación en la documentación de la API para configurar el token correctamente: https://eagenda.com.br/api/v3/documents/#overview.

Definición de los Parámetros de Consulta

Parámetros del Endpoint /available-date-times/

Este endpoint lista horarios disponibles para un día específico. A continuación se presentan los parámetros de query-string:

action_new_appointment (opcional)

Descripción: Define la acción para la cita.
Valores posibles:
- new: Horarios disponibles sin restricciones.
- client: Horarios considerando restricciones para clientes.
- waiting: Horarios con lista de espera.
- force: Encaje en horarios ocupados.
Impacto: Filtra horarios según la acción deseada.
Ejemplo: new

calendar_key (obligatorio)

Descripción: Clave UUID de la agenda.
Impacto: Especifica la agenda para consultar horarios.
Cómo obtener: Use el endpoint de listado de agendas (/api/v3/calendars/).
Ejemplo: 19730681-29d0-4000-88d0-caf575494780

day (obligatorio)

Descripción: Día de la agenda (formato YYYY-MM-DD).
Impacto: Filtra horarios disponibles para el día especificado.
Ejemplo: 2025-06-01

is_manual (opcional)

Descripción: Indica si la fecha fue creada manualmente.
Impacto: Filtra horarios creados manualmente (true) o automáticamente (false).
Ejemplo: true

min_vacancies_available (opcional)

Descripción: Cantidad mínima de vacantes disponibles por horario.
Impacto: Filtra horarios con al menos el número especificado de vacantes.
Ejemplo: 1

page (opcional)

Descripción: Número de página en los resultados paginados.
Impacto: Navega por las páginas de resultados.
Ejemplo: 1

page_size (opcional)

Descripción: Número de resultados por página.
Impacto: Define la cantidad de horarios devueltos por página.
Ejemplo: 20

service_keys (opcional)

Descripción: Lista de claves UUID de los servicios.
Impacto: Filtra horarios disponibles para servicios específicos.
Cómo obtener: Use el endpoint de listado de servicios (/api/v3/services/).
Ejemplo: [“19730681-2aa0-4000-84b6-2bc54b4ace01”]

Parámetros del Endpoint /available-date-times/random/

Este endpoint lista horarios aleatorios disponibles en un intervalo. A continuación se presentan los parámetros de query-string:

calendar_key (obligatorio)

Descripción: Clave UUID de la agenda.
Impacto: Especifica la agenda para consultar horarios.
Cómo obtener: Use el endpoint de listado de agendas (/api/v3/calendars/).
Ejemplo: 19730681-29d0-4000-88d0-caf575494780

end_date (opcional)

Descripción: Fecha final de la cita (formato ISO 8601).
Impacto: Limita los horarios hasta la fecha especificada.
Ejemplo: 2025-06-30T23:59:59Z

min_vacancies_available (opcional)

Descripción: Cantidad mínima de vacantes disponibles por horario.
Impacto: Filtra horarios con al menos el número especificado de vacantes.
Ejemplo: 1

page (opcional)

Descripción: Número de página en los resultados paginados.
Impacto: Navega por las páginas de resultados.
Ejemplo: 1

page_size (opcional)

Descripción: Número de resultados por página.
Impacto: Define la cantidad de horarios devueltos por página.
Ejemplo: 20

quantity (opcional)

Descripción: Cantidad de horarios a devolver.
Impacto: Define el número de horarios aleatorios devueltos.
Ejemplo: 5

service_keys (opcional)

Descripción: Lista de claves UUID de los servicios.
Impacto: Filtra horarios disponibles para servicios específicos.
Cómo obtener: Use el endpoint de listado de servicios (/api/v3/services/).
Ejemplo: [“19730681-2aa0-4000-84b6-2bc54b4ace01”]

start_date (opcional)

Descripción: Fecha inicial de la cita (formato ISO 8601).
Impacto: Limita los horarios a partir de la fecha especificada.
Ejemplo: 2025-06-01T00:00:00Z

Nota: Para el endpoint /available-date-times/, calendar_key y day son obligatorios. Para /available-date-times/random/, solo calendar_key es obligatorio. Los demás parámetros son opcionales para mayor flexibilidad.

Envío de la Solicitud para Listar Horarios

Para listar horarios disponibles, envíe una solicitud HTTP GET a uno de los endpoints:

Para un día específico: https://eagenda.com.br/api/v3/available-date-times/
Para horarios aleatorios: https://eagenda.com.br/api/v3/available-date-times/random/

Configuración de la Solicitud

Método: GET
Encabezados:
- accept: application/json
- Authorization: Bearer
Query-string: Parámetros de filtro (ej.: ?calendar_key=19730681-29d0-4000-88d0-caf575494780&day=2025-06-01).

Ejemplo de Solicitud con 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"

Ejemplo en 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())

Verificación de la Respuesta

La API devolverá una respuesta con el estado de la consulta y los horarios disponibles. Verifique los siguientes puntos:

Código de estado HTTP:
- 200 OK: Lista de horarios devuelta con éxito.
- 400 Bad Request: Error en los parámetros de consulta (verifique el formato).
- 401 Unauthorized: Token inválido o ausente.
Cuerpo de la respuesta: Contiene una lista paginada de horarios, con detalles 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 } ] }

Los horarios devueltos respetan los filtros aplicados. Use los campos next y previous para navegar por las páginas de resultados.

Conclusión

Con este tutorial, aprendió cómo listar horarios disponibles para programación vía API de eAgenda, utilizando los endpoints /api/v3/available-date-times/ y /api/v3/available-date-times/random/. Esta integración es ideal para automatizar la consulta de horarios, facilitando la creación de citas. Para más funcionalidades, como creación de agendas o citas, consulte la documentación completa de la API de eAgenda.

Contáctenos o Conozca Más

Estamos a su disposición para ayudarle. Acceda a nuestros canales oficiales:

📞 WhatsApp : Haga clic aquí para enviarnos un mensaje 🌐 Plataforma eAgenda : Conozca eAgenda 🏢 Nuestra Empresa : Mupi Systems – Soluciones Innovadoras 📧 Correo electrónico : contato@mupisystems.com.br 📚 Tutoriales y Documentación : Acceda a nuestras guías y tutoriales