Como Listar e Filtrar Agendamentos Via API

Resumo #

A API da plataforma eAgenda permite listar e filtrar agendamentos de forma programática, possibilitando a consulta de detalhes como status, serviços, datas e participantes. Este guia prático detalha como configurar uma requisição HTTP GET para o endpoint /api/v3/appointments/ com 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 documentação de autenticação da eAgenda para configurar o token corretamente.

Definição dos Parâmetros de Consulta #

Para listar ou filtrar agendamentos, envie parâmetros na query-string da requisição GET. Todos os parâmetros são opcionais, permitindo flexibilidade na consulta. Abaixo estão os parâmetros disponíveis:

account_slug (opcional) #

• Descrição: Slug da conta ou subconta.
• Impacto: Filtra agendamentos de uma conta específica.
• Como obter: Use o endpoint de listagem de contas da eAgenda.
• Exemplo: minha-conta

calendar_key (opcional) #

• Descrição: Chave UUID da agenda.
• Impacto: Filtra agendamentos de uma agenda específica.
• Como obter: Use o endpoint de listagem de agendas.
• Exemplo: 550e8400-e29b-41d4-a716-446655440000

client_key (opcional) #

• Descrição: Chave UUID do cliente.
• Impacto: Filtra agendamentos associados a um cliente específico.
• Como obter: Use o endpoint de listagem de clientes.
• Exemplo: 123e4567-e89b-12d3-a456-426614174000

created_at (opcional) #

• Descrição: Data de criação do agendamento (formato ISO 8601).
• Impacto: Filtra agendamentos criados em uma data específica.
• Exemplo: 2025-06-01T10:00:00Z

email (opcional) #

• Descrição: E-mail do participante.
• Impacto: Filtra agendamentos associados a um e-mail.
• Exemplo: joao.silva@example.com

end_date (opcional) #

• Descrição: Data máxima de início do agendamento (formato ISO 8601).
• Impacto: Filtra agendamentos que começam antes desta data.
• Exemplo: 2025-06-30T23:59:59Z

identification_code (opcional) #

• Descrição: Número de identificação fiscal do participante (ex.: CPF).
• Impacto: Filtra agendamentos por documento de identificação.
• Exemplo: 123.456.789-00

is_cancelled (opcional) #

• Descrição: Indica se o agendamento foi cancelado.
• Impacto: Filtra agendamentos cancelados (true) ou ativos (false).
• Exemplo: true

name (opcional) #

• Descrição: Nome do participante.
• Impacto: Filtra agendamentos por nome da pessoa.
• Exemplo: João Silva

owner_user (opcional) #

• Descrição: E-mail do usuário responsável pelo agendamento.
• Impacto: Filtra agendamentos por responsável.
• Exemplo: responsavel@example.com

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 agendamentos retornados por página.
• Exemplo: 20

phone (opcional) #

• Descrição: Telefone do participante (formato E.164).
• Impacto: Filtra agendamentos por número de telefone.
• Exemplo: +5511999999999

service_keys (opcional) #

• Descrição: Lista de chaves UUID dos serviços.
• Impacto: Filtra agendamentos associados a serviços específicos.
• Como obter: Use o endpoint de listagem de serviços.
• Exemplo: [“19730681-2aa0-4000-84b6-2bc54b4ace01”]

start_date (opcional) #

• Descrição: Data mínima de início do agendamento (formato ISO 8601).
• Impacto: Filtra agendamentos que começam após esta data.
• Exemplo: 2025-06-01T00:00:00Z

status (opcional) #

• Descrição: Status do agendamento.
• Valores possíveis: ATTENDED, CANCELED, CANCELED_CLIENT, CANCELED_GOOGLE, CONFIRMED, IN_PROGRESS, NO_SHOW, PENDING, PENDING_COMPANIONS, PENDING_FORM, PENDING_PAYMENT.
• Impacto: Filtra agendamentos por status.
• Exemplo: CONFIRMED

tag_keys (opcional) #

• Descrição: Lista de chaves UUID das tags.
• Impacto: Filtra agendamentos associados a tags específicas.
• Como obter: Use o endpoint de listagem de tags.
• Exemplo: [“a1b2c3d4-e5f6-7890-1234-567890abcdef”]

Nota: Todos os parâmetros são opcionais. Combine-os para filtrar resultados específicos.

Envio da Requisição para Listar/Filtrar Agendamentos #

Para listar ou filtrar agendamentos, envie uma requisição HTTP GET para o endpoint:

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

Configuração da Requisição #

• Método: GET
• Cabeçalhos:
  • accept: application/json
  • Authorization: Bearer <seu-token>
• Query-string: Parâmetros de filtro (ex.: ?account_slug=minha-conta&status=CONFIRMED).

Exemplo de Requisição com 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"

Exemplo em 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())

Verificação da Resposta #

A API retornará uma resposta com o status da consulta e os agendamentos filtrados. Verifique os seguintes pontos:

• Código de status HTTP:
  • 200 OK: Lista de agendamentos 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 agendamentos, com detalhes 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" } ] }

Os agendamentos 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 e filtrar agendamentos via API da eAgenda, utilizando parâmetros de consulta para obter resultados específicos. Essa integração é ideal para gerenciar agendamentos, monitorar status e integrar com sistemas externos. Para mais funcionalidades, como criação ou edição de 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