API
Citas
Servicios, equipo y citas en lote para tu agenda
# Citas > Servicios, equipo y citas en lote para tu agenda - Página: https://tbit.app/es/docs/api/appointments - URL base: `https://rest-api.tbit.app/v1` - Autenticación: encabezado `X-API-Key` con tu clave en cada solicitud (los ejemplos la leen de la variable de entorno `TBIT_API_KEY`) ## Descripción general Lo que necesitas para llevar la agenda de tu negocio desde otro sistema: los servicios que se agendan con quién los atiende, el equipo, y la carga de citas en lote. Es lo mismo que hacen las tools del MCP list_services, list_collaborators e import_appointments, con los mismos nombres de campos. ## Endpoints | Método | Ruta | Descripción | | --- | --- | --- | | `GET` | `/v1/services` | Los servicios que se agendan, con quién los atiende | | `GET` | `/v1/collaborators` | El equipo: nombre, correo, rol y servicios que atiende | | `POST` | `/v1/appointments/import` | Cargar hasta 200 citas en una llamada | ## Listar servicios Cada servicio trae id, name, duration_minutes, price, currency, location, active y collaborators (id, name y email de quienes lo atienden). El id es el que pides como service_id al importar citas. Los servicios que se rentan (habitaciones, salones, vehículos) no salen aquí. `GET /v1/services` ```bash curl "https://rest-api.tbit.app/v1/services" \ -H "X-API-Key: $TBIT_API_KEY" ``` Respuesta: ```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 el equipo Cada persona trae id, name, email, role, attends_appointments (si atiende citas) y service_ids (los servicios que atiende). Cuando una persona no tiene nombre cargado, name viene vacío: identifícala por su correo. `GET /v1/collaborators` ```bash curl "https://rest-api.tbit.app/v1/collaborators" \ -H "X-API-Key: $TBIT_API_KEY" ``` Respuesta: ```json { "data": [ { "id": "6a0f3c2e9b1d4a0012ab0001", "name": "Geral Díaz", "email": "[email protected]", "role": "ADMIN", "attends_appointments": true, "service_ids": [ "6a0f3c2e9b1d4a0012ab34cd" ] } ] } ``` ## Importar citas Manda hasta 200 citas por llamada en appointments. Cada fila lleva phone (con indicativo de país, por ejemplo 573001234567: el contacto se busca por teléfono y, si no existe, se crea) o contact_id (un contacto que ya existe: la cita va a esa ficha aunque no tenga teléfono, como quien escribe con usuario de WhatsApp; si mandas también phone, solo se usa para avisar), contact_name y email opcionales, el servicio (service_id o service_name, el nombre exacto sin importar mayúsculas), quién atiende (collaborator_id o collaborator_email; si el servicio lo atiende una sola persona puedes omitirlo), start en ISO 8601 (sin zona se lee en la zona del negocio), end opcional (por defecto start más la duración del servicio), external_id (la llave del evento en tu sistema: volver a importar no duplica) y notes. Opciones, todas en el primer nivel del cuerpo: notify_customer (por defecto false: al cliente no le llega confirmación; true la manda como cualquier cita), send_reminders (por defecto true), release_blocks (true quita los bloqueos de esa persona que se crucen con la cita), on_existing (skip o update: si ya existe una cita con el mismo external_id, la deja como está o la mueve sin avisarle a nadie) y dry_run (true valida todo y dice qué haría, sin escribir nada). Empieza siempre con dry_run. La respuesta dice por fila qué pasó: status es created, updated, skipped o failed (would_create o would_update con dry_run), con appointment_id, contact_id y, si falló, error con la razón en palabras («Andrés no atiende Endodoncia; lo atienden: Geral Díaz.»). Una fila mala no detiene las demás. Guarda import_id: es lo que necesitas para deshacer. `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" } ] }' ``` Respuesta: ```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" } ] } } ``` ## Deshacer un import Manda solo undo_import_id con el import_id que te devolvió la importación: todas las citas que creó ese import quedan canceladas, sin avisarle a nadie, y su external_id queda libre para volver a importarlas. `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" }' ``` Respuesta: ```json { "data": { "import_id": "6a1e0b7c5d4f3a0012cd5678", "cancelled": 198, "already_cancelled": 2, "failed": [] } } ``` ## Reglas y errores - La persona tiene que atender ese servicio. Si no, la fila falla y el error dice quién sí lo atiende. - Una cita no puede cruzarse con otra de la misma persona, ni con otra fila del mismo lote. Si se cruza con un bloqueo de agenda, la fila falla salvo que mandes release_blocks: true. - Un lote que no se puede leer entero (vacío, más de 200 filas, un campo desconocido en el cuerpo) responde 400 VALIDATION_ERROR y no escribe nada. - Un lote grande puede tardar: cada cita crea su pedido y su contacto. Si tus lotes pasan de 100 citas, pártelos en llamadas más chicas.Lo que necesitas para llevar la agenda de tu negocio desde otro sistema: los servicios que se agendan con quién los atiende, el equipo, y la carga de citas en lote. Es lo mismo que hacen las tools del MCP list_services, list_collaborators e import_appointments, con los mismos nombres de campos.
| Método | Ruta | Descripción |
|---|---|---|
| GET | /v1/services | Los servicios que se agendan, con quién los atiende |
| GET | /v1/collaborators | El equipo: nombre, correo, rol y servicios que atiende |
| POST | /v1/appointments/import | Cargar hasta 200 citas en una llamada |
Cada servicio trae id, name, duration_minutes, price, currency, location, active y collaborators (id, name y email de quienes lo atienden). El id es el que pides como service_id al importar citas. Los servicios que se rentan (habitaciones, salones, vehículos) no salen aquí.
/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 persona trae id, name, email, role, attends_appointments (si atiende citas) y service_ids (los servicios que atiende). Cuando una persona no tiene nombre cargado, name viene vacío: identifícala por su correo.
/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"
]
}
]
}Manda hasta 200 citas por llamada en appointments. Cada fila lleva phone (con indicativo de país, por ejemplo 573001234567: el contacto se busca por teléfono y, si no existe, se crea) o contact_id (un contacto que ya existe: la cita va a esa ficha aunque no tenga teléfono, como quien escribe con usuario de WhatsApp; si mandas también phone, solo se usa para avisar), contact_name y email opcionales, el servicio (service_id o service_name, el nombre exacto sin importar mayúsculas), quién atiende (collaborator_id o collaborator_email; si el servicio lo atiende una sola persona puedes omitirlo), start en ISO 8601 (sin zona se lee en la zona del negocio), end opcional (por defecto start más la duración del servicio), external_id (la llave del evento en tu sistema: volver a importar no duplica) y notes.
Opciones, todas en el primer nivel del cuerpo: notify_customer (por defecto false: al cliente no le llega confirmación; true la manda como cualquier cita), send_reminders (por defecto true), release_blocks (true quita los bloqueos de esa persona que se crucen con la cita), on_existing (skip o update: si ya existe una cita con el mismo external_id, la deja como está o la mueve sin avisarle a nadie) y dry_run (true valida todo y dice qué haría, sin escribir nada). Empieza siempre con dry_run.
La respuesta dice por fila qué pasó: status es created, updated, skipped o failed (would_create o would_update con dry_run), con appointment_id, contact_id y, si falló, error con la razón en palabras («Andrés no atiende Endodoncia; lo atienden: Geral Díaz.»). Una fila mala no detiene las demás. Guarda import_id: es lo que necesitas para deshacer.
/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"
}
]
}
}Manda solo undo_import_id con el import_id que te devolvió la importación: todas las citas que creó ese import quedan canceladas, sin avisarle a nadie, y su external_id queda libre para volver a importarlas.
/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 tiene que atender ese servicio. Si no, la fila falla y el error dice quién sí lo atiende.
- Una cita no puede cruzarse con otra de la misma persona, ni con otra fila del mismo lote. Si se cruza con un bloqueo de agenda, la fila falla salvo que mandes release_blocks: true.
- Un lote que no se puede leer entero (vacío, más de 200 filas, un campo desconocido en el cuerpo) responde 400 VALIDATION_ERROR y no escribe nada.
- Un lote grande puede tardar: cada cita crea su pedido y su contacto. Si tus lotes pasan de 100 citas, pártelos en llamadas más chicas.