API
Appuntamenti
Servizi, team e appuntamenti in blocco per la tua agenda
# Appuntamenti > Servizi, team e appuntamenti in blocco per la tua agenda - Pagina: https://tbit.app/it/docs/api/appointments - URL base: `https://rest-api.tbit.app/v1` - Autenticazione: header `X-API-Key` con la tua chiave in ogni richiesta (gli esempi la leggono dalla variabile d'ambiente `TBIT_API_KEY`) ## Panoramica Ciò che ti serve per gestire l'agenda della tua attività da un altro sistema: i servizi che si prenotano con chi li eroga, il team, e il caricamento di appuntamenti in blocco. È lo stesso che fanno le tool del MCP list_services, list_collaborators e import_appointments, con gli stessi nomi dei campi. ## Endpoint | Metodo | Percorso | Descrizione | | --- | --- | --- | | `GET` | `/v1/services` | I servizi che si prenotano, con chi li eroga | | `GET` | `/v1/collaborators` | Il team: nome, email, ruolo e servizi che eroga | | `POST` | `/v1/appointments/import` | Carica fino a 200 appuntamenti in una chiamata | ## Elenca i servizi Ogni servizio porta id, name, duration_minutes, price, currency, location, active e collaborators (id, name ed email di chi lo eroga). L'id è quello che richiedi come service_id quando importi gli appuntamenti. I servizi che si affittano (camere, sale, veicoli) non compaiono qui. `GET /v1/services` ```bash curl "https://rest-api.tbit.app/v1/services" \ -H "X-API-Key: $TBIT_API_KEY" ``` Risposta: ```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]" } ] } ] } ``` ## Elenca il team Ogni persona porta id, name, email, role, attends_appointments (se eroga appuntamenti) e service_ids (i servizi che eroga). Quando una persona non ha un nome caricato, name arriva vuoto: identificala con la sua email. `GET /v1/collaborators` ```bash curl "https://rest-api.tbit.app/v1/collaborators" \ -H "X-API-Key: $TBIT_API_KEY" ``` Risposta: ```json { "data": [ { "id": "6a0f3c2e9b1d4a0012ab0001", "name": "Geral Díaz", "email": "[email protected]", "role": "ADMIN", "attends_appointments": true, "service_ids": [ "6a0f3c2e9b1d4a0012ab34cd" ] } ] } ``` ## Importa appuntamenti Invia fino a 200 appuntamenti per chiamata in appointments. Ogni riga porta phone (con prefisso internazionale, per esempio 573001234567: il contatto si cerca per telefono e, se non esiste, viene creato) o contact_id (un contatto che esiste già: l'appuntamento va su quella scheda anche se non ha telefono, come chi scrive con un utente di WhatsApp; se invii anche phone, viene usato solo per avvisare), contact_name ed email opzionali, il servizio (service_id o service_name, il nome esatto senza badare alle maiuscole), chi lo gestisce (collaborator_id o collaborator_email; se il servizio lo gestisce una sola persona puoi ometterlo), start in ISO 8601 (senza fuso viene letto nel fuso dell'attività), end opzionale (per impostazione predefinita start più la durata del servizio), external_id (la chiave dell'evento nel tuo sistema: reimportare non duplica) e notes. Opzioni, tutte al primo livello del corpo: notify_customer (per impostazione predefinita false: al cliente non arriva la conferma; true la invia come per qualsiasi appuntamento), send_reminders (per impostazione predefinita true), release_blocks (true rimuove i blocchi di quella persona che si incrociano con l'appuntamento), on_existing (skip o update: se esiste già un appuntamento con lo stesso external_id, lo lascia com'è o lo sposta senza avvisare nessuno) e dry_run (true valida tutto e dice cosa farebbe, senza scrivere nulla). Inizia sempre con dry_run. La risposta dice per riga cosa è successo: status è created, updated, skipped o failed (would_create o would_update con dry_run), con appointment_id, contact_id e, se ha fallito, error con il motivo a parole («Andrés non eroga Endodonzia; la eroga: Geral Díaz.»). Una riga sbagliata non ferma le altre. Salva import_id: è quello che ti serve per annullare. `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" } ] }' ``` Risposta: ```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" } ] } } ``` ## Annulla un import Invia solo undo_import_id con l'import_id che ti ha restituito l'importazione: tutti gli appuntamenti che quell'import ha creato restano annullati, senza avvisare nessuno, e il loro external_id resta libero per reimportarli. `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" }' ``` Risposta: ```json { "data": { "import_id": "6a1e0b7c5d4f3a0012cd5678", "cancelled": 198, "already_cancelled": 2, "failed": [] } } ``` ## Regole ed errori - La persona deve erogare quel servizio. Altrimenti la riga fallisce e l'errore dice chi lo eroga. - Un appuntamento non può incrociarsi con un altro della stessa persona, né con un'altra riga dello stesso lotto. Se si incrocia con un blocco di agenda, la riga fallisce a meno che tu non invii release_blocks: true. - Un lotto che non si può leggere interamente (vuoto, più di 200 righe, un campo sconosciuto nel corpo) risponde 400 VALIDATION_ERROR e non scrive nulla. - Un lotto grande può richiedere tempo: ogni appuntamento crea il suo ordine e il suo contatto. Se i tuoi lotti superano i 100 appuntamenti, dividili in chiamate più piccole.Ciò che ti serve per gestire l'agenda della tua attività da un altro sistema: i servizi che si prenotano con chi li eroga, il team, e il caricamento di appuntamenti in blocco. È lo stesso che fanno le tool del MCP list_services, list_collaborators e import_appointments, con gli stessi nomi dei campi.
| Metodo | Percorso | Descrizione |
|---|---|---|
| GET | /v1/services | I servizi che si prenotano, con chi li eroga |
| GET | /v1/collaborators | Il team: nome, email, ruolo e servizi che eroga |
| POST | /v1/appointments/import | Carica fino a 200 appuntamenti in una chiamata |
Ogni servizio porta id, name, duration_minutes, price, currency, location, active e collaborators (id, name ed email di chi lo eroga). L'id è quello che richiedi come service_id quando importi gli appuntamenti. I servizi che si affittano (camere, sale, veicoli) non compaiono qui.
/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]"
}
]
}
]
}Ogni persona porta id, name, email, role, attends_appointments (se eroga appuntamenti) e service_ids (i servizi che eroga). Quando una persona non ha un nome caricato, name arriva vuoto: identificala con la sua email.
/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"
]
}
]
}Invia fino a 200 appuntamenti per chiamata in appointments. Ogni riga porta phone (con prefisso internazionale, per esempio 573001234567: il contatto si cerca per telefono e, se non esiste, viene creato) o contact_id (un contatto che esiste già: l'appuntamento va su quella scheda anche se non ha telefono, come chi scrive con un utente di WhatsApp; se invii anche phone, viene usato solo per avvisare), contact_name ed email opzionali, il servizio (service_id o service_name, il nome esatto senza badare alle maiuscole), chi lo gestisce (collaborator_id o collaborator_email; se il servizio lo gestisce una sola persona puoi ometterlo), start in ISO 8601 (senza fuso viene letto nel fuso dell'attività), end opzionale (per impostazione predefinita start più la durata del servizio), external_id (la chiave dell'evento nel tuo sistema: reimportare non duplica) e notes.
Opzioni, tutte al primo livello del corpo: notify_customer (per impostazione predefinita false: al cliente non arriva la conferma; true la invia come per qualsiasi appuntamento), send_reminders (per impostazione predefinita true), release_blocks (true rimuove i blocchi di quella persona che si incrociano con l'appuntamento), on_existing (skip o update: se esiste già un appuntamento con lo stesso external_id, lo lascia com'è o lo sposta senza avvisare nessuno) e dry_run (true valida tutto e dice cosa farebbe, senza scrivere nulla). Inizia sempre con dry_run.
La risposta dice per riga cosa è successo: status è created, updated, skipped o failed (would_create o would_update con dry_run), con appointment_id, contact_id e, se ha fallito, error con il motivo a parole («Andrés non eroga Endodonzia; la eroga: Geral Díaz.»). Una riga sbagliata non ferma le altre. Salva import_id: è quello che ti serve per annullare.
/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"
}
]
}
}Invia solo undo_import_id con l'import_id che ti ha restituito l'importazione: tutti gli appuntamenti che quell'import ha creato restano annullati, senza avvisare nessuno, e il loro external_id resta libero per reimportarli.
/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": []
}
}- La persona deve erogare quel servizio. Altrimenti la riga fallisce e l'errore dice chi lo eroga.
- Un appuntamento non può incrociarsi con un altro della stessa persona, né con un'altra riga dello stesso lotto. Se si incrocia con un blocco di agenda, la riga fallisce a meno che tu non invii release_blocks: true.
- Un lotto che non si può leggere interamente (vuoto, più di 200 righe, un campo sconosciuto nel corpo) risponde 400 VALIDATION_ERROR e non scrive nulla.
- Un lotto grande può richiedere tempo: ogni appuntamento crea il suo ordine e il suo contatto. Se i tuoi lotti superano i 100 appuntamenti, dividili in chiamate più piccole.