Agendamentos

O que são agendamentos

Agendamentos (appointments) representam reuniões, consultas ou compromissos vinculados opcionalmente a um lead. Se a loja tiver Google Calendar ou Outlook conectado (via Nylas), toda criação, atualização ou remoção feita pela API é sincronizada automaticamente com o calendário externo — o mesmo comportamento de quem agenda pela plataforma.

Disponível a partir do plano starter. Consulte Autenticação para os tiers de cada endpoint.

Criar agendamento

curl -X POST https://api.cordialy.ai/integrations/v1/appointments \
  -H "X-API-Key: SUA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Consulta com João Silva",
    "scheduled_at": "2026-09-01T14:00:00Z",
    "duration_minutes": 30,
    "lead_id": "lead-001"
  }'

const appointment = await fetch('https://api.cordialy.ai/integrations/v1/appointments', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.CORDIALY_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    title: 'Consulta com João Silva',
    scheduled_at: '2026-09-01T14:00:00Z',
    duration_minutes: 30,
    lead_id: 'lead-001',
  }),
}).then(r => r.json());

lead_id é opcional — vincule quando o agendamento se refere a um lead existente da loja. Quando vinculado, o lead é automaticamente movido para o status converted.

Idempotência

Retry de rede em POST /appointments pode criar um agendamento duplicado — e um evento duplicado no calendário externo. Envie um header Idempotency-Key (qualquer string única por operação, ex: um UUID gerado no seu sistema) para evitar isso:

curl -X POST https://api.cordialy.ai/integrations/v1/appointments \
  -H "X-API-Key: SUA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: agendamento-pedido-4521" \
  -d '{ "title": "Consulta", "scheduled_at": "2026-09-01T14:00:00Z" }'

Se a mesma chave for reenviada para o mesmo endpoint dentro de 24h, a resposta original é retornada sem criar um novo registro (o header Idempotent-Replay: true indica um replay). O mesmo suporte existe em POST /leads, POST /sellers e POST /followups/scheduled.

Listar e filtrar agendamentos

# Agendamentos de um lead específico
curl "https://api.cordialy.ai/integrations/v1/appointments?lead_id=lead-001" \
  -H "X-API-Key: SUA_KEY"

# Agendamentos de um período
curl "https://api.cordialy.ai/integrations/v1/appointments?from=2026-09-01T00:00:00Z&to=2026-09-30T23:59:59Z" \
  -H "X-API-Key: SUA_KEY"

# Paginação
curl "https://api.cordialy.ai/integrations/v1/appointments?page=1&limit=50" \
  -H "X-API-Key: SUA_KEY"

A resposta inclui total, page e limit:

{
  "data": [...],
  "total": 34,
  "page": 1,
  "limit": 50
}

Reagendar ou cancelar

Reagendar é um PATCH trocando scheduled_at; cancelar é um PATCH de status. Ambos sincronizam com o calendário externo:

curl -X PATCH https://api.cordialy.ai/integrations/v1/appointments/APPOINTMENT_ID \
  -H "X-API-Key: SUA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduled_at": "2026-09-02T15:00:00Z"}'

curl -X PATCH https://api.cordialy.ai/integrations/v1/appointments/APPOINTMENT_ID \
  -H "X-API-Key: SUA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "cancelled"}'

Remover agendamento

curl -X DELETE https://api.cordialy.ai/integrations/v1/appointments/APPOINTMENT_ID \
  -H "X-API-Key: SUA_KEY"

Diferente de cancelar (status: cancelled), remover apaga o registro e o evento correspondente no calendário externo permanentemente. Prefira cancelar se quiser manter o histórico.

Padrões de integração

Sincronizar agenda de um sistema externo

Quando um compromisso é criado no seu CRM ou sistema de agendamento, replique na Cordialy para que apareça no calendário conectado e nos lembretes automáticos:

async function onCompromissoCriado(compromisso) {
  await fetch('https://api.cordialy.ai/integrations/v1/appointments', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.CORDIALY_API_KEY,
      'Content-Type': 'application/json',
      'Idempotency-Key': `crm-${compromisso.id}`,
    },
    body: JSON.stringify({
      title: compromisso.titulo,
      scheduled_at: compromisso.dataHora,
      duration_minutes: compromisso.duracaoMinutos,
      lead_id: compromisso.leadId,
    }),
  });
}

Confirmar agendamento junto ao lead

Após criar o agendamento, envie a confirmação diretamente no WhatsApp do lead:

const appointment = await criarAgendamento({ leadId, title, scheduledAt });
await fetch(`https://api.cordialy.ai/integrations/v1/leads/${leadId}/messages`, {
  method: 'POST',
  headers: { 'X-API-Key': process.env.CORDIALY_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: `Agendamento confirmado para ${formatarData(appointment.scheduled_at)}!`,
  }),
});

Início

Guias

Exemplos

O que são agendamentos

Criar agendamento

Idempotência

Listar e filtrar agendamentos

Reagendar ou cancelar

Remover agendamento

Padrões de integração

​O que são agendamentos

​Criar agendamento

​Idempotência

​Listar e filtrar agendamentos

​Reagendar ou cancelar

​Remover agendamento

​Padrões de integração

O que são agendamentos

Criar agendamento

Idempotência

Listar e filtrar agendamentos

Reagendar ou cancelar

Remover agendamento

Padrões de integração