API
Termine
Leistungen, Team und Termine im Stapel für deinen Kalender
# Termine > Leistungen, Team und Termine im Stapel für deinen Kalender - Seite: https://tbit.app/de/docs/api/appointments - Basis-URL: `https://rest-api.tbit.app/v1` - Authentifizierung: Header `X-API-Key` mit deinem Schlüssel in jeder Anfrage (die Beispiele lesen ihn aus der Umgebungsvariable `TBIT_API_KEY`) ## Übersicht Was du brauchst, um den Kalender deines Geschäfts aus einem anderen System zu führen: die Leistungen, die mit ihren Betreuern gebucht werden, das Team und das Hochladen von Terminen im Stapel. Das ist dasselbe, was die MCP-Tools list_services, list_collaborators und import_appointments tun, mit denselben Feldnamen. ## Endpunkte | Methode | Route | Beschreibung | | --- | --- | --- | | `GET` | `/v1/services` | Die Services, die gebucht werden, mit wem sie betreut werden | | `GET` | `/v1/collaborators` | Das Team: Name, E-Mail, Rolle und betreute Services | | `POST` | `/v1/appointments/import` | Bis zu 200 Termine in einem Aufruf laden | ## Services auflisten Jeder Service bringt id, name, duration_minutes, price, currency, location, active und collaborators (id, name und email der Betreuenden). Die id ist die, die du beim Importieren von Terminen als service_id angibst. Services, die vermietet werden (Zimmer, Säle, Fahrzeuge), erscheinen hier nicht. `GET /v1/services` ```bash curl "https://rest-api.tbit.app/v1/services" \ -H "X-API-Key: $TBIT_API_KEY" ``` Antwort: ```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]" } ] } ] } ``` ## Das Team auflisten Jede Person bringt id, name, email, role, attends_appointments (ob sie Termine betreut) und service_ids (die betreuten Services). Wenn bei einer Person kein Name hinterlegt ist, kommt name leer: identifiziere sie über ihre E-Mail. `GET /v1/collaborators` ```bash curl "https://rest-api.tbit.app/v1/collaborators" \ -H "X-API-Key: $TBIT_API_KEY" ``` Antwort: ```json { "data": [ { "id": "6a0f3c2e9b1d4a0012ab0001", "name": "Geral Díaz", "email": "[email protected]", "role": "ADMIN", "attends_appointments": true, "service_ids": [ "6a0f3c2e9b1d4a0012ab34cd" ] } ] } ``` ## Termine importieren Sende bis zu 200 Termine pro Aufruf in appointments. Jede Zeile enthält phone (mit Ländervorwahl, zum Beispiel 573001234567: der Kontakt wird über die Telefonnummer gesucht und, falls er nicht existiert, angelegt) oder contact_id (ein bereits existierender Kontakt: der Termin geht an diesen Eintrag, auch ohne Telefonnummer, wie jemand, der mit einem WhatsApp-Benutzer schreibt; wenn du auch phone sendest, wird es nur zur Benachrichtigung genutzt), contact_name und email optional, den Service (service_id oder service_name, der exakte Name unabhängig von Groß- und Kleinschreibung), wer betreut (collaborator_id oder collaborator_email; wenn nur eine Person den Service betreut, kannst du es weglassen), start in ISO 8601 (ohne Zeitzone wird es in der Zeitzone des Betriebs gelesen), end optional (standardmäßig start plus die Dauer des Service), external_id (der Schlüssel des Events in deinem System: erneutes Importieren erzeugt keine Dublette) und notes. Optionen, alle auf der ersten Ebene des Bodys: notify_customer (standardmäßig false: der Kunde erhält keine Bestätigung; true sendet sie wie bei jedem Termin), send_reminders (standardmäßig true), release_blocks (true entfernt die Sperren dieser Person, die sich mit dem Termin überschneiden), on_existing (skip oder update: existiert bereits ein Termin mit derselben external_id, lässt er ihn wie er ist oder verschiebt ihn, ohne jemanden zu benachrichtigen) und dry_run (true prüft alles und sagt, was es tun würde, ohne etwas zu schreiben). Beginne immer mit dry_run. Die Antwort sagt pro Zeile, was passiert ist: status ist created, updated, skipped oder failed (would_create oder would_update mit dry_run), mit appointment_id, contact_id und, falls fehlgeschlagen, error mit dem Grund in Worten („Andrés betreut Endodoncia nicht; es wird betreut von: Geral Díaz.“). Eine schlechte Zeile hält die anderen nicht auf. Speichere import_id: das brauchst du zum Rückgängigmachen. `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" } ] }' ``` Antwort: ```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" } ] } } ``` ## Einen Import rückgängig machen Sende nur undo_import_id mit der import_id, die der Import zurückgegeben hat: alle Termine, die dieser Import erstellt hat, werden storniert, ohne jemanden zu benachrichtigen, und ihre external_id wird frei, um sie erneut zu importieren. `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" }' ``` Antwort: ```json { "data": { "import_id": "6a1e0b7c5d4f3a0012cd5678", "cancelled": 198, "already_cancelled": 2, "failed": [] } } ``` ## Regeln und Fehler - Die Person muss diesen Service betreuen. Wenn nicht, schlägt die Zeile fehl und der Fehler sagt, wer ihn betreut. - Ein Termin darf sich nicht mit einem anderen derselben Person überschneiden, auch nicht mit einer anderen Zeile desselben Batches. Überschneidet er sich mit einer Kalendersperre, schlägt die Zeile fehl, außer du sendest release_blocks: true. - Ein Batch, der nicht vollständig gelesen werden kann (leer, mehr als 200 Zeilen, ein unbekanntes Feld im Body), antwortet mit 400 VALIDATION_ERROR und schreibt nichts. - Ein großer Batch kann dauern: jeder Termin erstellt seine Bestellung und seinen Kontakt. Wenn deine Batches über 100 Termine gehen, teile sie in kleinere Aufrufe.Was du brauchst, um den Kalender deines Geschäfts aus einem anderen System zu führen: die Leistungen, die mit ihren Betreuern gebucht werden, das Team und das Hochladen von Terminen im Stapel. Das ist dasselbe, was die MCP-Tools list_services, list_collaborators und import_appointments tun, mit denselben Feldnamen.
| Methode | Route | Beschreibung |
|---|---|---|
| GET | /v1/services | Die Services, die gebucht werden, mit wem sie betreut werden |
| GET | /v1/collaborators | Das Team: Name, E-Mail, Rolle und betreute Services |
| POST | /v1/appointments/import | Bis zu 200 Termine in einem Aufruf laden |
Jeder Service bringt id, name, duration_minutes, price, currency, location, active und collaborators (id, name und email der Betreuenden). Die id ist die, die du beim Importieren von Terminen als service_id angibst. Services, die vermietet werden (Zimmer, Säle, Fahrzeuge), erscheinen hier nicht.
/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]"
}
]
}
]
}Jede Person bringt id, name, email, role, attends_appointments (ob sie Termine betreut) und service_ids (die betreuten Services). Wenn bei einer Person kein Name hinterlegt ist, kommt name leer: identifiziere sie über ihre 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"
]
}
]
}Sende bis zu 200 Termine pro Aufruf in appointments. Jede Zeile enthält phone (mit Ländervorwahl, zum Beispiel 573001234567: der Kontakt wird über die Telefonnummer gesucht und, falls er nicht existiert, angelegt) oder contact_id (ein bereits existierender Kontakt: der Termin geht an diesen Eintrag, auch ohne Telefonnummer, wie jemand, der mit einem WhatsApp-Benutzer schreibt; wenn du auch phone sendest, wird es nur zur Benachrichtigung genutzt), contact_name und email optional, den Service (service_id oder service_name, der exakte Name unabhängig von Groß- und Kleinschreibung), wer betreut (collaborator_id oder collaborator_email; wenn nur eine Person den Service betreut, kannst du es weglassen), start in ISO 8601 (ohne Zeitzone wird es in der Zeitzone des Betriebs gelesen), end optional (standardmäßig start plus die Dauer des Service), external_id (der Schlüssel des Events in deinem System: erneutes Importieren erzeugt keine Dublette) und notes.
Optionen, alle auf der ersten Ebene des Bodys: notify_customer (standardmäßig false: der Kunde erhält keine Bestätigung; true sendet sie wie bei jedem Termin), send_reminders (standardmäßig true), release_blocks (true entfernt die Sperren dieser Person, die sich mit dem Termin überschneiden), on_existing (skip oder update: existiert bereits ein Termin mit derselben external_id, lässt er ihn wie er ist oder verschiebt ihn, ohne jemanden zu benachrichtigen) und dry_run (true prüft alles und sagt, was es tun würde, ohne etwas zu schreiben). Beginne immer mit dry_run.
Die Antwort sagt pro Zeile, was passiert ist: status ist created, updated, skipped oder failed (would_create oder would_update mit dry_run), mit appointment_id, contact_id und, falls fehlgeschlagen, error mit dem Grund in Worten („Andrés betreut Endodoncia nicht; es wird betreut von: Geral Díaz.“). Eine schlechte Zeile hält die anderen nicht auf. Speichere import_id: das brauchst du zum Rückgängigmachen.
/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"
}
]
}
}Sende nur undo_import_id mit der import_id, die der Import zurückgegeben hat: alle Termine, die dieser Import erstellt hat, werden storniert, ohne jemanden zu benachrichtigen, und ihre external_id wird frei, um sie erneut zu importieren.
/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": []
}
}- Die Person muss diesen Service betreuen. Wenn nicht, schlägt die Zeile fehl und der Fehler sagt, wer ihn betreut.
- Ein Termin darf sich nicht mit einem anderen derselben Person überschneiden, auch nicht mit einer anderen Zeile desselben Batches. Überschneidet er sich mit einer Kalendersperre, schlägt die Zeile fehl, außer du sendest release_blocks: true.
- Ein Batch, der nicht vollständig gelesen werden kann (leer, mehr als 200 Zeilen, ein unbekanntes Feld im Body), antwortet mit 400 VALIDATION_ERROR und schreibt nichts.
- Ein großer Batch kann dauern: jeder Termin erstellt seine Bestellung und seinen Kontakt. Wenn deine Batches über 100 Termine gehen, teile sie in kleinere Aufrufe.