# Agendamentos

> Serviços, equipe e agendamentos em lote para sua agenda

- Página: https://tbit.app/pt/docs/api/appointments
- URL base: `https://rest-api.tbit.app/v1`
- Autenticação: cabeçalho `X-API-Key` com a sua chave em cada requisição (os exemplos a leem da variável de ambiente `TBIT_API_KEY`)

## Visão geral

O que você precisa para levar a agenda do seu negócio a partir de outro sistema: os serviços que são agendados com quem os atende, a equipe, e o carregamento de agendamentos em lote. É o mesmo que as tools do MCP list_services, list_collaborators e import_appointments fazem, com os mesmos nomes de campos.

## Endpoints

| Método | Rota | Descrição |
| --- | --- | --- |
| `GET` | `/v1/services` | Os serviços que são agendados, com quem os atende |
| `GET` | `/v1/collaborators` | A equipe: nome, e-mail, função e serviços que atende |
| `POST` | `/v1/appointments/import` | Carregar até 200 agendamentos em uma chamada |

## Listar serviços

Cada serviço traz id, name, duration_minutes, price, currency, location, active e collaborators (id, name e email de quem o atende). O id é o que você pede como service_id ao importar agendamentos. Os serviços que são alugados (quartos, salões, veículos) não aparecem aqui.

`GET /v1/services`

```bash
curl "https://rest-api.tbit.app/v1/services" \
  -H "X-API-Key: $TBIT_API_KEY"
```

Resposta:

```json
{
  "data": [
    {
      "id": "6a0f3c2e9b1d4a0012ab34cd",
      "name": "Endodoncia",
      "duration_minutes": 60,
      "price": 350000,
      "currency": "COP",
      "location": "Sede norte · Calle 72 # 7-41",
      "active": true,
      "collaborators": [
        {
          "id": "6a0f3c2e9b1d4a0012ab0001",
          "name": "Geral Díaz",
          "email": "geral@tuclinica.co"
        }
      ]
    }
  ]
}
```

## Listar a equipe

Cada pessoa traz id, name, email, role, attends_appointments (se atende agendamentos) e service_ids (os serviços que atende). Quando uma pessoa não tem nome cadastrado, name vem vazio: identifique-a pelo e-mail.

`GET /v1/collaborators`

```bash
curl "https://rest-api.tbit.app/v1/collaborators" \
  -H "X-API-Key: $TBIT_API_KEY"
```

Resposta:

```json
{
  "data": [
    {
      "id": "6a0f3c2e9b1d4a0012ab0001",
      "name": "Geral Díaz",
      "email": "geral@tuclinica.co",
      "role": "ADMIN",
      "attends_appointments": true,
      "service_ids": [
        "6a0f3c2e9b1d4a0012ab34cd"
      ]
    }
  ]
}
```

## Importar agendamentos

Envie até 200 agendamentos por chamada em appointments. Cada linha leva phone (com código do país, por exemplo 573001234567: o contato é buscado pelo telefone e, se não existir, é criado) ou contact_id (um contato que já existe: o agendamento vai para essa ficha mesmo sem telefone, como quem escreve com usuário de WhatsApp; se você enviar também phone, ele só é usado para avisar), contact_name e email opcionais, o serviço (service_id ou service_name, o nome exato sem diferenciar maiúsculas), quem atende (collaborator_id ou collaborator_email; se o serviço é atendido por uma só pessoa você pode omitir), start em ISO 8601 (sem fuso é lido no fuso do negócio), end opcional (por padrão start mais a duração do serviço), external_id (a chave do evento no seu sistema: importar de novo não duplica) e notes.

Opções, todas no primeiro nível do corpo: notify_customer (por padrão false: o cliente não recebe confirmação; true a envia como qualquer agendamento), send_reminders (por padrão true), release_blocks (true remove os bloqueios dessa pessoa que se cruzem com o agendamento), on_existing (skip ou update: se já existe um agendamento com o mesmo external_id, deixa como está ou o move sem avisar ninguém) e dry_run (true valida tudo e diz o que faria, sem escrever nada). Comece sempre com dry_run.

A resposta diz por linha o que aconteceu: status é created, updated, skipped ou failed (would_create ou would_update com dry_run), com appointment_id, contact_id e, se falhou, error com o motivo em palavras («Andrés não atende Endodontia; quem atende: Geral Díaz.»). Uma linha ruim não impede as outras. Guarde import_id: é o que você precisa para desfazer.

`POST /v1/appointments/import`

```bash
curl -X POST "https://rest-api.tbit.app/v1/appointments/import" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dry_run": true,
    "appointments": [
      {
        "phone": "573001234567",
        "contact_name": "Ana Pérez",
        "service_name": "Endodoncia",
        "collaborator_email": "geral@tuclinica.co",
        "start": "2026-11-20T10:00",
        "external_id": "gcal-7f3k2"
      }
    ]
  }'
```

Resposta:

```json
{
  "data": {
    "import_id": null,
    "dry_run": true,
    "created": 1,
    "updated": 0,
    "skipped": 0,
    "failed": 0,
    "results": [
      {
        "index": 0,
        "external_id": "gcal-7f3k2",
        "status": "would_create",
        "contact_id": "6a0f3c2e9b1d4a0012ab9f10"
      }
    ]
  }
}
```

## Desfazer uma importação

Envie só undo_import_id com o import_id que a importação devolveu: todos os agendamentos que essa importação criou ficam cancelados, sem avisar ninguém, e o external_id deles fica livre para importá-los de novo.

`POST /v1/appointments/import`

```bash
curl -X POST "https://rest-api.tbit.app/v1/appointments/import" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "undo_import_id": "6a1e0b7c5d4f3a0012cd5678"
  }'
```

Resposta:

```json
{
  "data": {
    "import_id": "6a1e0b7c5d4f3a0012cd5678",
    "cancelled": 198,
    "already_cancelled": 2,
    "failed": []
  }
}
```

## Regras e erros

- A pessoa precisa atender esse serviço. Se não, a linha falha e o erro diz quem atende.
- Um agendamento não pode se cruzar com outro da mesma pessoa, nem com outra linha do mesmo lote. Se se cruzar com um bloqueio de agenda, a linha falha a menos que você envie release_blocks: true.
- Um lote que não pode ser lido inteiro (vazio, mais de 200 linhas, um campo desconhecido no corpo) responde 400 VALIDATION_ERROR e não escreve nada.
- Um lote grande pode demorar: cada agendamento cria seu pedido e seu contato. Se seus lotes passarem de 100 agendamentos, divida-os em chamadas menores.
