# Zapini API — Calendário

**Versão:** 1.0.0
**Base URL:** `https://zapini.app/api/v1`

---

## Autenticação

Todos os endpoints requerem um Bearer Token:

```
Authorization: Bearer sk_your_api_token
Accept: application/json
Content-Type: application/json
```

Gere tokens de API no painel admin em **API Docs → Gerenciar Tokens**.

---

## API de Calendário

**Base path:** `/api/v1/calendar`
**Requisito:** Nenhuma permissão especial necessária — todos os tenants podem gerenciar agendamentos.

---

## Status dos Agendamentos

| Status | Descrição |
|--------|-----------|
| `scheduled` | Status inicial — agendamento confirmado |
| `confirmed` | Cliente confirmou presença |
| `completed` | Agendamento foi concluído |
| `cancelled` | Agendamento foi cancelado |
| `no_show` | Cliente não compareceu |

---

## Agendamentos

### Listar Agendamentos
`GET /api/v1/calendar/appointments`

| Parâmetro | Tipo | Padrão | Descrição |
|-----------|------|--------|-----------|
| start | date | Início do mês | Início do intervalo (ISO 8601) |
| end | date | Fim do mês | Fim do intervalo (ISO 8601) |
| status | string | — | Filtrar por status |
| per_page | integer | 50 | Itens por página |

```bash
curl -s -H "Authorization: Bearer sk_your_token" \
  "https://zapini.app/api/v1/calendar/appointments?start=2026-05-01&end=2026-05-31"
```

---

### Criar Agendamento
`POST /api/v1/calendar/appointments`

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| title | string | Sim | Título do agendamento |
| description | string | Não | Detalhes |
| client_name | string | Não | Nome do cliente |
| client_phone | string | Não | Telefone do cliente |
| client_email | string | Não | E-mail do cliente |
| starts_at | datetime | Sim | Hora de início (ISO 8601) |
| ends_at | datetime | Sim | Hora de fim (deve ser após starts_at) |
| all_day | boolean | Não | Evento de dia inteiro |
| location | string | Não | Local ou URL da reunião |
| color | string | Não | Código hexadecimal de cor |
| reminder_minutes | integer | Não | Minutos antes para enviar lembrete (0–10080) |

```bash
curl -s -X POST \
  -H "Authorization: Bearer sk_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Consultation with John Doe",
    "client_name": "John Doe",
    "client_phone": "5511999999999",
    "starts_at": "2026-05-01T10:00:00",
    "ends_at": "2026-05-01T11:00:00",
    "location": "Online - Google Meet",
    "reminder_minutes": 30
  }' \
  "https://zapini.app/api/v1/calendar/appointments"
```

**Resposta:**
```json
{
  "success": true,
  "data": {
    "uuid": "appt-uuid",
    "title": "Consultation with John Doe",
    "client_name": "John Doe",
    "client_phone": "5511999999999",
    "starts_at": "2026-05-01T10:00:00+00:00",
    "ends_at": "2026-05-01T11:00:00+00:00",
    "all_day": false,
    "duration_minutes": 60,
    "location": "Online - Google Meet",
    "status": "scheduled",
    "color": "#3b82f6",
    "reminder_minutes": 30,
    "created_at": "2026-01-01T00:00:00+00:00"
  }
}
```

---

### Obter Agendamento
`GET /api/v1/calendar/appointments/{uuid}`

Retorna detalhes do agendamento incluindo o usuário `created_by`.

---

### Atualizar Agendamento
`PUT /api/v1/calendar/appointments/{uuid}`

Mesmos campos do Criar. Adicionalmente suporta o campo `status`.

---

### Excluir Agendamento
`DELETE /api/v1/calendar/appointments/{uuid}`

---

### Confirmar Agendamento
`POST /api/v1/calendar/appointments/{uuid}/confirm`

Transiciona o status de `scheduled` para `confirmed`.

```bash
curl -s -X POST \
  -H "Authorization: Bearer sk_your_token" \
  "https://zapini.app/api/v1/calendar/appointments/appt-uuid/confirm"
```

---

### Concluir Agendamento
`POST /api/v1/calendar/appointments/{uuid}/complete`

Transiciona o status para `completed` e define `completed_at`.

---

### Cancelar Agendamento
`POST /api/v1/calendar/appointments/{uuid}/cancel`

Retorna `422 CANNOT_CANCEL` se o agendamento já estiver concluído ou cancelado.

---

### Converter para Lead Kanban
`POST /api/v1/calendar/appointments/{uuid}/to-kanban`

Cria um lead Kanban a partir deste agendamento. Requer `kanban_enabled` no seu tenant.

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| board_uuid | string | Não | UUID do quadro alvo (usa o quadro padrão se omitido) |

```bash
curl -s -X POST \
  -H "Authorization: Bearer sk_your_token" \
  -H "Content-Type: application/json" \
  -d '{"board_uuid": "optional-board-uuid"}' \
  "https://zapini.app/api/v1/calendar/appointments/appt-uuid/to-kanban"
```

**Resposta:**
```json
{
  "success": true,
  "data": {
    "lead_uuid": "new-lead-uuid",
    "board_uuid": "board-uuid",
    "board_name": "Sales Pipeline"
  }
}
```

---

## Códigos de Erro

| Código | HTTP | Descrição |
|--------|------|-----------|
| `NOT_FOUND` | 404 | Recurso não encontrado |
| `VALIDATION_ERROR` | 422 | Falha de validação — verifique `error.details` |
| `CANNOT_CANCEL` | 422 | Agendamento não pode ser cancelado |
| `NO_BOARD` | 422 | Nenhum quadro Kanban encontrado para o tenant |
| `UNAUTHORIZED` | 401 | Token inválido ou ausente |
| `SERVER_ERROR` | 500 | Erro interno do servidor |

---

*Gerado por Zapini — https://zapini.app*