Pular para o conteúdo
Menu

Buscar no site

Digite para buscar em guias, blog, API e produto.

↑ ↓ para navegar · Enter para abrir · Esc para fechar

Referência da API

API

Agendamentos

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

Ver como Markdown

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.

MétodoRotaDescrição
GET/v1/servicesOs serviços que são agendados, com quem os atende
GET/v1/collaboratorsA equipe: nome, e-mail, função e serviços que atende
POST/v1/appointments/importCarregar 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
curl "https://rest-api.tbit.app/v1/services" \
  -H "X-API-Key: $TBIT_API_KEY"
const response = await fetch('https://rest-api.tbit.app/v1/services', {
  headers: {
    'X-API-Key': process.env.TBIT_API_KEY,
  },
});
const data = await response.json();
import axios from 'axios';

const { data } = await axios.get(
  'https://rest-api.tbit.app/v1/services',
  {
    headers: {
      'X-API-Key': process.env.TBIT_API_KEY,
    },
  },
);
import os
import requests

response = requests.get(
    'https://rest-api.tbit.app/v1/services',
    headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()
<?php
$ch = curl_init('https://rest-api.tbit.app/v1/services');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('TBIT_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
Resposta
{
  "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": "[email protected]"
        }
      ]
    }
  ]
}

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
curl "https://rest-api.tbit.app/v1/collaborators" \
  -H "X-API-Key: $TBIT_API_KEY"
const response = await fetch('https://rest-api.tbit.app/v1/collaborators', {
  headers: {
    'X-API-Key': process.env.TBIT_API_KEY,
  },
});
const data = await response.json();
import axios from 'axios';

const { data } = await axios.get(
  'https://rest-api.tbit.app/v1/collaborators',
  {
    headers: {
      'X-API-Key': process.env.TBIT_API_KEY,
    },
  },
);
import os
import requests

response = requests.get(
    'https://rest-api.tbit.app/v1/collaborators',
    headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()
<?php
$ch = curl_init('https://rest-api.tbit.app/v1/collaborators');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('TBIT_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
Resposta
{
  "data": [
    {
      "id": "6a0f3c2e9b1d4a0012ab0001",
      "name": "Geral Díaz",
      "email": "[email protected]",
      "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
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": "[email protected]",
        "start": "2026-11-20T10:00",
        "external_id": "gcal-7f3k2"
      }
    ]
  }'
const response = await fetch('https://rest-api.tbit.app/v1/appointments/import', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.TBIT_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    dry_run: true,
    appointments: [
      {
        phone: '573001234567',
        contact_name: 'Ana Pérez',
        service_name: 'Endodoncia',
        collaborator_email: '[email protected]',
        start: '2026-11-20T10:00',
        external_id: 'gcal-7f3k2',
      },
    ],
  }),
});
const data = await response.json();
import axios from 'axios';

const { data } = await axios.post(
  'https://rest-api.tbit.app/v1/appointments/import',
  {
    dry_run: true,
    appointments: [
      {
        phone: '573001234567',
        contact_name: 'Ana Pérez',
        service_name: 'Endodoncia',
        collaborator_email: '[email protected]',
        start: '2026-11-20T10:00',
        external_id: 'gcal-7f3k2',
      },
    ],
  },
  {
    headers: {
      'X-API-Key': process.env.TBIT_API_KEY,
    },
  },
);
import os
import requests

response = requests.post(
    'https://rest-api.tbit.app/v1/appointments/import',
    headers={'X-API-Key': os.environ['TBIT_API_KEY']},
    json={
        'dry_run': True,
        'appointments': [
            {
                'phone': '573001234567',
                'contact_name': 'Ana Pérez',
                'service_name': 'Endodoncia',
                'collaborator_email': '[email protected]',
                'start': '2026-11-20T10:00',
                'external_id': 'gcal-7f3k2',
            },
        ],
    },
)
data = response.json()
<?php
$ch = curl_init('https://rest-api.tbit.app/v1/appointments/import');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('TBIT_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'dry_run' => true,
        'appointments' => [
            [
                'phone' => '573001234567',
                'contact_name' => 'Ana Pérez',
                'service_name' => 'Endodoncia',
                'collaborator_email' => '[email protected]',
                'start' => '2026-11-20T10:00',
                'external_id' => 'gcal-7f3k2',
            ],
        ],
    ]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
Resposta
{
  "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"
      }
    ]
  }
}

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
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"
  }'
const response = await fetch('https://rest-api.tbit.app/v1/appointments/import', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.TBIT_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    undo_import_id: '6a1e0b7c5d4f3a0012cd5678',
  }),
});
const data = await response.json();
import axios from 'axios';

const { data } = await axios.post(
  'https://rest-api.tbit.app/v1/appointments/import',
  {
    undo_import_id: '6a1e0b7c5d4f3a0012cd5678',
  },
  {
    headers: {
      'X-API-Key': process.env.TBIT_API_KEY,
    },
  },
);
import os
import requests

response = requests.post(
    'https://rest-api.tbit.app/v1/appointments/import',
    headers={'X-API-Key': os.environ['TBIT_API_KEY']},
    json={
        'undo_import_id': '6a1e0b7c5d4f3a0012cd5678',
    },
)
data = response.json()
<?php
$ch = curl_init('https://rest-api.tbit.app/v1/appointments/import');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('TBIT_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'undo_import_id' => '6a1e0b7c5d4f3a0012cd5678',
    ]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
Resposta
{
  "data": {
    "import_id": "6a1e0b7c5d4f3a0012cd5678",
    "cancelled": 198,
    "already_cancelled": 2,
    "failed": []
  }
}
  • 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.