Na integração de sistemas de agendamento, como a plataforma eAgenda, duas abordagens comuns para sincronização de dados são Webhooks e Polling. Este artigo explora as diferenças entre essas tecnologias, suas vantagens, desvantagens e como aplicá-las no contexto do eAgenda para listar agendamentos de forma eficiente usando a API v3.
O que é Polling?
Polling é o processo de consultar periodicamente a API do eAgenda para verificar novos agendamentos ou atualizações. Por exemplo, um sistema pode chamar o endpoint GET /api/v3/appointments/ a cada 5 minutos para buscar novos dados.
Vantagens do Polling
- Simplicidade: Fácil de implementar, ideal para integrações básicas.
- Controle: Permite definir a frequência das verificações.
- Independência: Não exige configurações adicionais no servidor do eAgenda.
Desvantagens do Polling
- Ineficiência: Consome recursos com requisições frequentes, mesmo sem novas informações.
- Latência: Atualizações só são detectadas no próximo ciclo, causando atrasos.
- Escalabilidade: Pode sobrecarregar o servidor em sistemas com alto volume de dados.
O que são Webhooks?
Webhooks são notificações HTTP enviadas automaticamente pelo eAgenda quando um evento ocorre, como a criação ou atualização de um agendamento. Um webhook pode notificar instantaneamente um sistema sobre novos agendamentos, eliminando a necessidade de consultas periódicas.
Vantagens dos Webhooks
- Eficiência: Envia dados apenas quando há eventos, reduzindo a carga no servidor.
- Tempo real: Garante sincronização imediata, ideal para notificações críticas.
- Escalabilidade: Suporta grandes volumes de eventos sem requisições desnecessárias.
Desvantagens dos Webhooks
- Complexidade: Requer configuração de endpoints no sistema receptor.
- Disponibilidade: O sistema integrado deve estar acessível para receber notificações.
- Segurança: Exige autenticação (ex.: tokens ou assinaturas HMAC) para proteger os dados.
Comparação no Contexto do eAgenda
No eAgenda, a escolha entre Webhooks e Polling impacta diretamente a performance e a experiência do usuário ao listar agendamentos. A tabela abaixo resume as principais diferenças:
| Critério | Polling | Webhooks |
|---|---|---|
| Latência | Depende do intervalo (ex.: 5 min) | Quase instantânea |
| Uso de Recursos | Alto (requisições constantes) | Baixo (só quando há eventos) |
| Complexidade | Baixa (implementação simples) | Média (requer endpoints) |
| Escalabilidade | Limitada | Alta |
| Casos de Uso no eAgenda | Sincronizações periódicas menos críticas | Notificações em tempo real |
Quando Usar Cada Um no eAgenda?
- Polling: Indicado para integrações simples, como sincronização de relatórios diários ou dados históricos, onde a latência não é crítica. Exemplo: consultar a API do eAgenda a cada hora para atualizar relatórios.
- Webhooks: Ideal para atualizações em tempo real, como notificar clientes sobre novos agendamentos ou integrar com sistemas de CRM. Exemplo: configurar um endpoint para receber notificações instantâneas do eAgenda.
Como Configurar no eAgenda?
Configurando Polling
- Programe requisições periódicas ao endpoint GET /api/v3/appointments/ usando um agendador (ex.: cron jobs).
- Use um cliente HTTP (ex.: cURL ou bibliotecas como Requests em Python) para consultar os endpoints.
- Processe os dados recebidos e atualize o sistema integrado.
Exemplo de Código (Python):
import requests
import schedule
import time
def fetch_eagenda_appointments():
url = "https://eagenda.com.br/api/v3/appointments/"
headers = {
"Authorization": "Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999",
"Content-Type": "application/json"
}
params = {
"account_slug": "minha-conta",
"status": "CONFIRMED",
"start_date": "2025-06-01T00:00:00Z",
"end_date": "2025-06-30T23:59:59Z",
"page_size": 10
}
response = requests.get(url, headers=headers, params=params)
if response.status_code == 200:
data = response.json()
print("Agendamentos:", data["results"])
else:
print("Erro:", response.status_code)
schedule.every(5).minutes.do(fetch_eagenda_appointments)
while True:
schedule.run_pending()
time.sleep(60)Configurando Webhooks
- Crie um endpoint HTTP no seu sistema para receber notificações do eAgenda.
- Registre o endpoint na interface de administração do eAgenda.
- Valide as requisições (ex.: com um token) e processe os eventos recebidos.
Exemplo de Código (Node.js):
const express = require('express');
const app = express();
app.use(express.json());
app.post('/eagenda-webhook', (req, res) => {
const event = req.body;
// Validar token e processar evento
console.log('Evento recebido:', event);
res.status(200).send('OK');
});
app.listen(3000, () => console.log('Webhook rodando na porta 3000'));Exemplo de Payload do Webhook
{
"appointment_key": "191e1237-0240-4000-8ac1-60bcc5ae8701",
"status": "ATTENDED",
"calendar": {
"calendar_key": "191e1237-0240-4000-85e4-6430bf42cf01",
"calendar_name": "Agenda Principal"
},
"service_list": [
{
"service_key": "191e1237-0240-4000-81be-0e5d361a8501",
"service_name": "Consulta Médica"
}
],
"tag_list": [
{
"tag_key": "191e1237-0240-4000-8921-719af633b401",
"label": "Urgente"
}
],
"attendees": [
{
"person_key": "191e1237-0240-4000-8ed4-9fac97c84d01",
"name": "João Silva",
"email": "joao.silva@example.com",
"phone": "+5511999999999"
}
],
"owner_user": {
"email": "admin@example.com",
"full_name": "Dr. Maria Souza"
},
"start": {
"dateTime": "2025-06-01T10:00:00Z",
"timeZone": "UTC"
},
"end": {
"dateTime": "2025-06-01T10:30:00Z",
"timeZone": "UTC"
},
"created_at": {
"dateTime": "2025-06-01T09:58:00Z",
"timeZone": "UTC"
},
"location": "Clínica Central",
"conference_data": {
"provider": "zoom",
"url": "http://example.com",
"label": "Reunião Online",
"pin": "123456",
"access_code": "7890",
"meeting_code": "123456789",
"passcode": "abc123"
},
"event": "appointment.created"
}Conclusão
Para a maioria dos casos no eAgenda, Webhooks são a melhor escolha devido à sua eficiência e capacidade de fornecer atualizações em tempo real, essenciais para uma experiência de agendamento fluida. No entanto, Polling pode ser uma alternativa viável para integrações mais simples ou sistemas legados. Avalie as necessidades do seu projeto e a infraestrutura disponível para tomar a melhor decisão.
Entre em Contato ou Saiba Mais
📞 WhatsApp: Clique aqui para nos enviar uma mensagem
🌐 Plataforma eAgenda: Conheça a ferramenta
🏢 Nossa Empresa: Mupi Systems – Soluções Inovadoras
📧 E-mail: contato@mupisystems.com.br
📚 Tutoriais e Documentação: Acesse nossos guias e tutoriais