# Agenda

## Tipos de agendamento

`GET /v1/c/{slug}/appointment-types` · Escopos: `appointments:read`

### Parâmetros do endereço

| Campo | Detalhes |
|---|---|
| `slug` | O identificador da empresa no DoneTalk (o mesmo da chave). |

### Exemplo de pedido

```bash
curl -X GET "https://api.donetalk.com/v1/c/demo/appointment-types" \
  -H "Authorization: Bearer $DONETALK_KEY"
```

### Resposta 200

```json
{
  "types": [
    {
      "id": "01a1228c-c58f-796a-b3aa-54a953711c71",
      "agendaId": "01a1228c-c584-73f7-b7e7-bfaa0d02fed0",
      "name": "Visita ao imóvel",
      "durationMin": 60,
      "agendaName": "Visitas aos imóveis",
      "timezone": "America/Sao_Paulo",
      "isActive": true
    }
  ]
}
```

### Erros possíveis

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Horários livres

`GET /v1/c/{slug}/appointment-types/{id}/slots` · Escopos: `appointments:read`

### Parâmetros do endereço

| Campo | Detalhes |
|---|---|
| `slug` | O identificador da empresa no DoneTalk (o mesmo da chave). |
| `id` | O id do registro. |

### Parâmetros de consulta

| Campo | Tipo | Obrigatório | Detalhes |
|---|---|---|---|
| `from` | string (date-time) | não |  |
| `to` | string (date-time) | não |  |
| `limit` | integer | não | até 500; mínimo 1; default `100` |
| `contactId` | string (uuid) | não |  |
| `memberId` | string (uuid) | não |  |
| `exclude` | string (uuid) | não |  |

### Exemplo de pedido

```bash
curl -X GET "https://api.donetalk.com/v1/c/demo/appointment-types/:id/slots" \
  -H "Authorization: Bearer $DONETALK_KEY"
```

### Resposta 200

```json
{
  "timezone": "America/Sao_Paulo",
  "durationMin": 60,
  "slots": [
    {
      "start": "2026-10-27T13:00:00.000Z",
      "end": "2026-10-27T14:00:00.000Z",
      "memberIds": [
        "01a0cac1-4a6f-7646-b5f8-c1d19090016a"
      ]
    }
  ]
}
```

### Erros possíveis

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Agendamentos

`GET /v1/c/{slug}/appointments` · Escopos: `appointments:read`

### Parâmetros do endereço

| Campo | Detalhes |
|---|---|
| `slug` | O identificador da empresa no DoneTalk (o mesmo da chave). |

### Parâmetros de consulta

| Campo | Tipo | Obrigatório | Detalhes |
|---|---|---|---|
| `from` | string (date-time) | não |  |
| `to` | string (date-time) | não |  |
| `agendaId` | string (uuid) | não |  |
| `memberId` | string (uuid) | não |  |
| `mine` | integer | não | até 1; default `0` |
| `status` | string | não |  |

### Exemplo de pedido

```bash
curl -X GET "https://api.donetalk.com/v1/c/demo/appointments" \
  -H "Authorization: Bearer $DONETALK_KEY"
```

### Resposta 200

```json
{
  "appointments": [
    {
      "id": "01a2f00d-1234-7abc-8def-0123456789ab",
      "agendaId": "01a1228c-c584-73f7-b7e7-bfaa0d02fed0",
      "agendaName": "Visitas aos imóveis",
      "typeId": "01a1228c-c58f-796a-b3aa-54a953711c71",
      "typeName": "Visita ao imóvel",
      "typeColor": "#1daa61",
      "contactId": "01a0d05a-3ee3-75bd-9db5-dc9856f079c8",
      "contactName": "Ana Souza",
      "conversationId": "01a3c0de-7a11-7b22-8c33-9d44e55f6677",
      "channelId": "01a0cccc-0000-7000-8000-000000000002",
      "memberId": "01a0cac1-4a6f-7646-b5f8-c1d19090016a",
      "memberName": "Tayomara Batista",
      "holderIds": [
        "01a0cac1-4a6f-7646-b5f8-c1d19090016a"
      ],
      "status": "booked",
      "startsAt": "2026-10-27T13:00:00.000Z",
      "endsAt": "2026-10-27T14:00:00.000Z",
      "timezone": "America/Sao_Paulo",
      "location": "Rua Bahia, 120 – Higienópolis, São Paulo",
      "locationKind": "address",
      "onlineUrl": null,
      "answers": {
        "imovel": "AP-2231"
      },
      "notes": null,
      "source": "api",
      "createdByKind": "api_key",
      "createdById": null,
      "confirmedAt": null,
      "cancelledAt": null,
      "cancelledByKind": null,
      "cancelReason": null,
      "rescheduleCount": 0,
      "previousStartsAt": null,
      "publicToken": "r3WqZ8",
      "createdAt": "2026-10-23T13:02:11.000Z"
    }
  ]
}
```

### Erros possíveis

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Marcar

`POST /v1/c/{slug}/appointments` · Escopos: `appointments:write`

### Parâmetros do endereço

| Campo | Detalhes |
|---|---|
| `slug` | O identificador da empresa no DoneTalk (o mesmo da chave). |

### Corpo do pedido

| Campo | Tipo | Obrigatório | Detalhes |
|---|---|---|---|
| `typeId` | string (uuid) | sim |  |
| `contactId` | string (uuid) | sim |  |
| `startsAt` | string (date-time) | sim |  |
| `conversationId` | string (uuid) | não | null |
| `memberId` | string (uuid) | não | null |
| `answers` | object | não |  |
| `notes` | string | não | até 2000 caracteres; null |
| `force` | boolean | não |  |
| `confirm` | boolean | não |  |

### Exemplo de pedido

```bash
curl -X POST "https://api.donetalk.com/v1/c/demo/appointments" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "typeId": "01a1228c-c58f-796a-b3aa-54a953711c71",
  "contactId": "01a0d05a-3ee3-75bd-9db5-dc9856f079c8",
  "startsAt": "2026-10-27T13:00:00.000Z",
  "answers": {
    "imovel": "AP-2231"
  }
}'
```

### Resposta 201

```json
{
  "appointment": {
    "id": "01a2f00d-1234-7abc-8def-0123456789ab",
    "agendaId": "01a1228c-c584-73f7-b7e7-bfaa0d02fed0",
    "agendaName": "Visitas aos imóveis",
    "typeId": "01a1228c-c58f-796a-b3aa-54a953711c71",
    "typeName": "Visita ao imóvel",
    "typeColor": "#1daa61",
    "contactId": "01a0d05a-3ee3-75bd-9db5-dc9856f079c8",
    "contactName": "Ana Souza",
    "conversationId": "01a3c0de-7a11-7b22-8c33-9d44e55f6677",
    "channelId": "01a0cccc-0000-7000-8000-000000000002",
    "memberId": "01a0cac1-4a6f-7646-b5f8-c1d19090016a",
    "memberName": "Tayomara Batista",
    "holderIds": [
      "01a0cac1-4a6f-7646-b5f8-c1d19090016a"
    ],
    "status": "booked",
    "startsAt": "2026-10-27T13:00:00.000Z",
    "endsAt": "2026-10-27T14:00:00.000Z",
    "timezone": "America/Sao_Paulo",
    "location": "Rua Bahia, 120 – Higienópolis, São Paulo",
    "locationKind": "address",
    "onlineUrl": null,
    "answers": {
      "imovel": "AP-2231"
    },
    "notes": null,
    "source": "api",
    "createdByKind": "api_key",
    "createdById": null,
    "confirmedAt": null,
    "cancelledAt": null,
    "cancelledByKind": null,
    "cancelReason": null,
    "rescheduleCount": 0,
    "previousStartsAt": null,
    "publicToken": "r3WqZ8",
    "createdAt": "2026-10-23T13:02:11.000Z"
  }
}
```

### Erros possíveis

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Ver um agendamento

`GET /v1/c/{slug}/appointments/{id}` · Escopos: `appointments:read`

### Parâmetros do endereço

| Campo | Detalhes |
|---|---|
| `slug` | O identificador da empresa no DoneTalk (o mesmo da chave). |
| `id` | O id do registro. |

### Exemplo de pedido

```bash
curl -X GET "https://api.donetalk.com/v1/c/demo/appointments/:id" \
  -H "Authorization: Bearer $DONETALK_KEY"
```

### Resposta 200

```json
{
  "appointment": {
    "id": "01a2f00d-1234-7abc-8def-0123456789ab",
    "agendaId": "01a1228c-c584-73f7-b7e7-bfaa0d02fed0",
    "agendaName": "Visitas aos imóveis",
    "typeId": "01a1228c-c58f-796a-b3aa-54a953711c71",
    "typeName": "Visita ao imóvel",
    "typeColor": "#1daa61",
    "contactId": "01a0d05a-3ee3-75bd-9db5-dc9856f079c8",
    "contactName": "Ana Souza",
    "conversationId": "01a3c0de-7a11-7b22-8c33-9d44e55f6677",
    "channelId": "01a0cccc-0000-7000-8000-000000000002",
    "memberId": "01a0cac1-4a6f-7646-b5f8-c1d19090016a",
    "memberName": "Tayomara Batista",
    "holderIds": [
      "01a0cac1-4a6f-7646-b5f8-c1d19090016a"
    ],
    "status": "booked",
    "startsAt": "2026-10-27T13:00:00.000Z",
    "endsAt": "2026-10-27T14:00:00.000Z",
    "timezone": "America/Sao_Paulo",
    "location": "Rua Bahia, 120 – Higienópolis, São Paulo",
    "locationKind": "address",
    "onlineUrl": null,
    "answers": {
      "imovel": "AP-2231"
    },
    "notes": null,
    "source": "api",
    "createdByKind": "api_key",
    "createdById": null,
    "confirmedAt": null,
    "cancelledAt": null,
    "cancelledByKind": null,
    "cancelReason": null,
    "rescheduleCount": 0,
    "previousStartsAt": null,
    "publicToken": "r3WqZ8",
    "createdAt": "2026-10-23T13:02:11.000Z"
  },
  "notices": [],
  "events": [],
  "history": []
}
```

### Erros possíveis

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Remarcar

`POST /v1/c/{slug}/appointments/{id}/reschedule` · Escopos: `appointments:write`

### Parâmetros do endereço

| Campo | Detalhes |
|---|---|
| `slug` | O identificador da empresa no DoneTalk (o mesmo da chave). |
| `id` | O id do registro. |

### Corpo do pedido

| Campo | Tipo | Obrigatório | Detalhes |
|---|---|---|---|
| `startsAt` | string (date-time) | sim |  |
| `memberId` | string (uuid) | não | null |
| `force` | boolean | não |  |

### Exemplo de pedido

```bash
curl -X POST "https://api.donetalk.com/v1/c/demo/appointments/:id/reschedule" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "startsAt": "2026-10-28T13:00:00.000Z"
}'
```

### Resposta 200

```json
{
  "appointment": {
    "id": "01a2f00d-1234-7abc-8def-0123456789ab",
    "agendaId": "01a1228c-c584-73f7-b7e7-bfaa0d02fed0",
    "agendaName": "Visitas aos imóveis",
    "typeId": "01a1228c-c58f-796a-b3aa-54a953711c71",
    "typeName": "Visita ao imóvel",
    "typeColor": "#1daa61",
    "contactId": "01a0d05a-3ee3-75bd-9db5-dc9856f079c8",
    "contactName": "Ana Souza",
    "conversationId": "01a3c0de-7a11-7b22-8c33-9d44e55f6677",
    "channelId": "01a0cccc-0000-7000-8000-000000000002",
    "memberId": "01a0cac1-4a6f-7646-b5f8-c1d19090016a",
    "memberName": "Tayomara Batista",
    "holderIds": [
      "01a0cac1-4a6f-7646-b5f8-c1d19090016a"
    ],
    "status": "booked",
    "startsAt": "2026-10-27T13:00:00.000Z",
    "endsAt": "2026-10-27T14:00:00.000Z",
    "timezone": "America/Sao_Paulo",
    "location": "Rua Bahia, 120 – Higienópolis, São Paulo",
    "locationKind": "address",
    "onlineUrl": null,
    "answers": {
      "imovel": "AP-2231"
    },
    "notes": null,
    "source": "api",
    "createdByKind": "api_key",
    "createdById": null,
    "confirmedAt": null,
    "cancelledAt": null,
    "cancelledByKind": null,
    "cancelReason": null,
    "rescheduleCount": 0,
    "previousStartsAt": null,
    "publicToken": "r3WqZ8",
    "createdAt": "2026-10-23T13:02:11.000Z"
  }
}
```

### Erros possíveis

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Cancelar

`POST /v1/c/{slug}/appointments/{id}/cancel` · Escopos: `appointments:write`

### Parâmetros do endereço

| Campo | Detalhes |
|---|---|
| `slug` | O identificador da empresa no DoneTalk (o mesmo da chave). |
| `id` | O id do registro. |

### Corpo do pedido

| Campo | Tipo | Obrigatório | Detalhes |
|---|---|---|---|
| `reason` | string | não | até 300 caracteres; null |
| `notify` | boolean | não | default `true` |

### Exemplo de pedido

```bash
curl -X POST "https://api.donetalk.com/v1/c/demo/appointments/:id/cancel" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Cliente pediu"
}'
```

### Resposta 200

```json
{
  "appointment": {
    "id": "01a2f00d-1234-7abc-8def-0123456789ab",
    "agendaId": "01a1228c-c584-73f7-b7e7-bfaa0d02fed0",
    "agendaName": "Visitas aos imóveis",
    "typeId": "01a1228c-c58f-796a-b3aa-54a953711c71",
    "typeName": "Visita ao imóvel",
    "typeColor": "#1daa61",
    "contactId": "01a0d05a-3ee3-75bd-9db5-dc9856f079c8",
    "contactName": "Ana Souza",
    "conversationId": "01a3c0de-7a11-7b22-8c33-9d44e55f6677",
    "channelId": "01a0cccc-0000-7000-8000-000000000002",
    "memberId": "01a0cac1-4a6f-7646-b5f8-c1d19090016a",
    "memberName": "Tayomara Batista",
    "holderIds": [
      "01a0cac1-4a6f-7646-b5f8-c1d19090016a"
    ],
    "status": "cancelled",
    "startsAt": "2026-10-27T13:00:00.000Z",
    "endsAt": "2026-10-27T14:00:00.000Z",
    "timezone": "America/Sao_Paulo",
    "location": "Rua Bahia, 120 – Higienópolis, São Paulo",
    "locationKind": "address",
    "onlineUrl": null,
    "answers": {
      "imovel": "AP-2231"
    },
    "notes": null,
    "source": "api",
    "createdByKind": "api_key",
    "createdById": null,
    "confirmedAt": null,
    "cancelledAt": null,
    "cancelledByKind": null,
    "cancelReason": null,
    "rescheduleCount": 0,
    "previousStartsAt": null,
    "publicToken": "r3WqZ8",
    "createdAt": "2026-10-23T13:02:11.000Z"
  }
}
```

### Erros possíveis

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`