Saltar al contenido
Menú

Buscar en el sitio

Escribe para buscar en guías, blog, API y producto.

↑ ↓ para moverte · Enter para abrir · Esc para cerrar

Referencia de la API

API

Citas

Servicios, equipo y citas en lote para tu agenda

Ver como Markdown

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étodoRutaDescripción
GET/v1/servicesLos servicios que se agendan, con quién los atiende
GET/v1/collaboratorsEl equipo: nombre, correo, rol y servicios que atiende
POST/v1/appointments/importCargar 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
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);
Respuesta
{
  "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
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);
Respuesta
{
  "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
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);
Respuesta
{
  "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
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);
Respuesta
{
  "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.