API
Agendamentos
Serviços, equipe e agendamentos em lote para sua agenda
# 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": "[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` ```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": "[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` ```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": "[email protected]", "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.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é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 |
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.
/v1/servicescurl "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);{
"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]"
}
]
}
]
}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.
/v1/collaboratorscurl "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);{
"data": [
{
"id": "6a0f3c2e9b1d4a0012ab0001",
"name": "Geral Díaz",
"email": "[email protected]",
"role": "ADMIN",
"attends_appointments": true,
"service_ids": [
"6a0f3c2e9b1d4a0012ab34cd"
]
}
]
}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.
/v1/appointments/importcurl -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);{
"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.
/v1/appointments/importcurl -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);{
"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.