# 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": "geral@tuclinica.co"
        }
      ]
    }
  ]
}
```

## 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": "geral@tuclinica.co",
      "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": "geral@tuclinica.co",
        "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.
