Listar y Filtrar Citas

Resumen

La API de la plataforma eAgenda permite listar y filtrar citas de forma programática, posibilitando la consulta de detalles como estado, servicios, fechas y participantes. Esta guía práctica detalla cómo configurar una solicitud HTTP GET al endpoint /api/v3/appointments/ con 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 documentación de autenticación de eAgenda para configurar el token correctamente.

Definición de los Parámetros de Consulta

Para listar o filtrar citas, envíe parámetros en la query-string de la solicitud GET. Todos los parámetros son opcionales, lo que permite flexibilidad en la consulta. A continuación se detallan los parámetros disponibles:

account_slug (opcional)

Descripción: Slug de la cuenta o subcuenta.
Impacto: Filtra citas de una cuenta específica.
Cómo obtenerlo: Use el endpoint de listado de cuentas de eAgenda.
Ejemplo: minha-conta

calendar_key (opcional)

Descripción: Clave UUID de la agenda.
Impacto: Filtra citas de una agenda específica.
Cómo obtenerla: Use el endpoint de listado de agendas.
Ejemplo: 550e8400-e29b-41d4-a716-446655440000

client_key (opcional)

Descripción: Clave UUID del cliente.
Impacto: Filtra citas asociadas a un cliente específico.
Cómo obtenerla: Use el endpoint de listado de clientes.
Ejemplo: 123e4567-e89b-12d3-a456-426614174000

created_at (opcional)

Descripción: Fecha de creación de la cita (formato ISO 8601).
Impacto: Filtra citas creadas en una fecha específica.
Ejemplo: 2025-06-01T10:00:00Z

email (opcional)

Descripción: Correo electrónico del participante.
Impacto: Filtra citas asociadas a un correo electrónico.
Ejemplo: joao.silva@example.com

end_date (opcional)

Descripción: Fecha máxima de inicio de la cita (formato ISO 8601).
Impacto: Filtra citas que comienzan antes de esta fecha.
Ejemplo: 2025-06-30T23:59:59Z

identification_code (opcional)

Descripción: Número de identificación fiscal del participante (ej.: CPF).
Impacto: Filtra citas por documento de identificación.
Ejemplo: 123.456.789-00

is_cancelled (opcional)

Descripción: Indica si la cita fue cancelada.
Impacto: Filtra citas canceladas (true) o activas (false).
Ejemplo: true

name (opcional)

Descripción: Nombre del participante.
Impacto: Filtra citas por nombre de la persona.
Ejemplo: João Silva

owner_user (opcional)

Descripción: Correo electrónico del usuario responsable de la cita.
Impacto: Filtra citas por responsable.
Ejemplo: responsavel@example.com

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 citas devueltas por página.
Ejemplo: 20

phone (opcional)

Descripción: Teléfono del participante (formato E.164).
Impacto: Filtra citas por número de teléfono.
Ejemplo: +5511999999999

service_keys (opcional)

Descripción: Lista de claves UUID de los servicios.
Impacto: Filtra citas asociadas a servicios específicos.
Cómo obtenerlas: Use el endpoint de listado de servicios.
Ejemplo: [“19730681-2aa0-4000-84b6-2bc54b4ace01”]

start_date (opcional)

Descripción: Fecha mínima de inicio de la cita (formato ISO 8601).
Impacto: Filtra citas que comienzan después de esta fecha.
Ejemplo: 2025-06-01T00:00:00Z

status (opcional)

Descripción: Estado de la cita.
Valores posibles: ATTENDED, CANCELED, CANCELED_CLIENT, CANCELED_GOOGLE, CONFIRMED, IN_PROGRESS, NO_SHOW, PENDING, PENDING_COMPANIONS, PENDING_FORM, PENDING_PAYMENT.
Impacto: Filtra citas por estado.
Ejemplo: CONFIRMED

tag_keys (opcional)

Descripción: Lista de claves UUID de las etiquetas.
Impacto: Filtra citas asociadas a etiquetas específicas.
Cómo obtenerlas: Use el endpoint de listado de etiquetas.
Ejemplo: [“a1b2c3d4-e5f6-7890-1234-567890abcdef”]

Nota: Todos los parámetros son opcionales. Combínelos para filtrar resultados específicos.

Envío de la Solicitud para Listar/Filtrar Citas

Para listar o filtrar citas, envíe una solicitud HTTP GET al endpoint:

https://eagenda.com.br/api/v3/appointments/

Configuración de la Solicitud

Método: GET
Encabezados:
- accept: application/json
- Authorization: Bearer
Query-string: Parámetros de filtro (ej.: ?account_slug=minha-conta&status=CONFIRMED).

Ejemplo de Solicitud con cURL

curl -X GET "https://eagenda.com.br/api/v3/appointments/?account_slug=minha-conta&status=CONFIRMED&start_date=2025-06-01T00:00:00Z" \
-H "accept: application/json" \
-H "Authorization: Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999"

Ejemplo en Python (usando requests)

import requests

url = "https://eagenda.com.br/api/v3/appointments/"
headers = {
    "accept": "application/json",
    "Authorization": "Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999"
}
params = {
    "account_slug": "minha-conta",
    "status": "CONFIRMED",
    "start_date": "2025-06-01T00:00:00Z"
}

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 las citas filtradas. Verifique los siguientes puntos:

Código de estado HTTP:
- 200 OK: Lista de citas 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 citas, con detalles como:{ "count": 1, "next": null, "previous": null, "results": [ { "appointment_key": "550e8400-e29b-41d4-a716-446655440000", "search_code": "A001", "status": "CONFIRMED", "calendar": { "calendar_key": "123e4567-e89b-12d3-a456-426614174000", "calendar_name": "Agenda Principal" }, "service_list": [ { "service_key": "19730681-2aa0-4000-84b6-2bc54b4ace01", "service_name": "Consulta Médica" } ], "tag_list": [ { "tag_key": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "label": "Urgente" } ], "attendees": [ { "person_key": "789abcde-f123-4567-89ab-cdef12345678", "name": "João Silva", "email": "joao.silva@example.com", "phone": "+5511999999999", "identification_code": "123.456.789-00", "identification_type": "br_cpf" } ], "owner_user": { "email": "responsavel@example.com", "full_name": "Maria Souza" }, "start": { "dateTime": "2025-06-01T10:00:00Z", "timeZone": "America/Sao_Paulo" }, "end": { "dateTime": "2025-06-01T10:30:00Z", "timeZone": "America/Sao_Paulo" }, "description": "Consulta de rotina", "location": "Clínica Central", "conference_data": { "provider": "meet", "url": "https://meet.google.com/abc-defg-hij", "label": "Reunião Virtual" }, "account_slug": "minha-conta" } ] }

Las citas devueltas 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 y filtrar citas vía API de eAgenda, utilizando parámetros de consulta para obtener resultados específicos. Esta integración es ideal para gestionar citas, monitorear estados e integrar con sistemas externos. Para más funcionalidades, como creación o edición de 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