> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cordialy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agendamentos

> Como criar, consultar e sincronizar agendamentos via API

## 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.

<Info>
  Disponível a partir do plano `starter`. Consulte [Autenticação](/authentication) para os tiers de cada endpoint.
</Info>

## Criar agendamento

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```typescript Node.js theme={null}
  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());
  ```
</CodeGroup>

`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:

```bash theme={null}
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

```bash theme={null}
# 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`:

```json theme={null}
{
  "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:

<CodeGroup>
  ```bash Reagendar theme={null}
  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"}'
  ```

  ```bash Cancelar theme={null}
  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"}'
  ```
</CodeGroup>

## Remover agendamento

```bash theme={null}
curl -X DELETE https://api.cordialy.ai/integrations/v1/appointments/APPOINTMENT_ID \
  -H "X-API-Key: SUA_KEY"
```

<Warning>
  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.
</Warning>

## Padrões de integração

<AccordionGroup>
  <Accordion title="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:

    ```typescript theme={null}
    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,
        }),
      });
    }
    ```
  </Accordion>

  <Accordion title="Confirmar agendamento junto ao lead">
    Após criar o agendamento, envie a confirmação diretamente no WhatsApp do lead:

    ```typescript theme={null}
    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)}!`,
      }),
    });
    ```
  </Accordion>
</AccordionGroup>