Citas y servicios · API de Totem

Resumen

Una cita (en la API, booking) ocupa un hueco en el calendario del equipo. Su kind indica de dónde viene:

service_booking: reservada para un servicio reservable, por la IA, un cliente o alguien del equipo. service indica el servicio.
calendar_event: un evento del calendario conectado del equipo.
external_import: sincronizada desde un sistema de citas externo, o leída del correo electrónico que envía un portal externo.

status es scheduled, rescheduled, cancelled, postponed, attended, no_show o team_no_show. Solo las personas registran la asistencia. source indica quién la reservó: ai, customer u operator. meeting_type es online, in_person o phone. Los pagos no se exportan.

Una reprogramación aparece de una de dos formas. Se actualiza la misma cita cuando alguien del equipo la mueve en Totem, cuando la IA mueve una cita de un sistema de citas externo como Koibox, cuando ese sistema informa de un cambio o cuando lo hace el correo de un portal de citas: starts_at y ends_at indican la nueva hora, y la hora anterior no se exporta. Su status pasa a rescheduled, aunque un cambio que informa un sistema de citas externo puede dejar el estado como estaba. Cuando la IA reprograma cualquier otra cita, crea una nueva: la antigua queda en cancelled, con rescheduled_to apuntando a la nueva, y la nueva apunta a la antigua con rescheduled_from. Durante unos segundos tras este tipo de reprogramación, la cita antigua puede seguir indicando scheduled. Un cambio hecho directamente en Google Calendar u Outlook puede no llegar a la cita de Totem. Una cita reprogramada antes de que Totem empezara a registrar estos enlaces puede no tener ninguno de los dos, como explica Cobertura de los datos.

Un servicio reservable es algo que los clientes pueden reservar con el equipo, como una primera consulta. GET /v1/booking_services devuelve todos los servicios del equipo, cada uno con su meeting_type, en una sola respuesta que no admite limit ni cursor. Los servicios no están en el feed de cambios: lee la lista cuando empieces a sincronizar un equipo, cuando una cita indique un servicio que no conoces y al menos una vez al día. Un servicio borrado sale de la lista, pero sus citas siguen indicando su identificador: no vuelvas a leer la lista por un identificador que no resolvió la última vez y, si muestras nombres de servicio en citas anteriores, conserva el de una lectura anterior. Los servicios desactivados siguen en la lista, sin nada que indique que lo están.

Usa GET /v1/bookings y GET /v1/bookings/{id} para consultar citas; GET /v1/bookings?lead= lista las citas de un lead. Para mantener una copia, sigue el feed de cambios: lo explica Sincroniza una copia.

Lista las citas

GET /v1/bookings

Devuelve una página de citas del equipo: citas para un servicio reservable, eventos del calendario conectado y citas importadas de otros sistemas, cada una con su estado y su horario. Envía lead para obtener las citas de un lead.

Permisos: calendar:read
Límite de frecuencia: Sincronización

Parámetros de consulta

limit integer Rango 1–100 Por defecto 25
Elementos por página, de 1 a 100. Por defecto, 25.
cursor string 1–512 caracteres
El next_cursor de la página anterior. Omítelo en la primera página.
lead string Prefijo del id lead_…
Solo las citas vinculadas a este lead: el lead de cada elemento es este identificador. Un lead de otro equipo, o que no existe, no coincide con nada.

Cabeceras

Totem-Team string Condicional Prefijo del id team_…
El equipo que se lee, como identificador team_…. Omítelo si la clave lee un solo equipo; es obligatorio si lee varios (400 team_required). Si lo envías, debe indicar un equipo que la clave lee: un identificador mal formado recibe 400 invalid_request, y un equipo fuera de la clave, 404 team_not_accessible, igual que una petición sin la cabecera cuando la clave ya no lee ningún equipo.

Respuesta

Devuelve una lista de objetos Booking.

object string
Siempre list.
data Array<Booking>
Los elementos de esta página.
has_more boolean
true si hay otra página: pídela con next_cursor, aunque esta traiga menos elementos que limit.
next_cursor string Puede ser null
Cursor opaco de la página siguiente, o null en la última. No lo interpretes.

Errores

400 team_required Falta el equipo
403 team_state_restricted Equipo restringido
403 sector_restricted Sector restringido
404 team_not_accessible Equipo no accesible
409 capture_not_ready Los datos del equipo aún se están preparando
429 quota_exceeded Cuota diaria superada

+ 12 errores comunes

curl 'https://api.totemstudio.ai/v1/bookings?limit=25' \
  -H "Authorization: Bearer $TOTEM_API_KEY" \
  -H "Totem-Team: $TOTEM_TEAM_ID"

{
  "object": "list",
  "data": [
    {
      "id": "bkg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3ttMKHRR9ADk3N7Cr3NSuY0",
      "object": "booking",
      "livemode": false,
      "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
      "lead": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
      "kind": "service_booking",
      "service": "svc_h42kgwwJGPzsm2Zoy1A1RBv1KIrX5",
      "status": "scheduled",
      "starts_at": "2026-10-06T15:00:00.000Z",
      "ends_at": "2026-10-06T15:30:00.000Z",
      "meeting_type": "in_person",
      "source": "ai",
      "rescheduled_from": null,
      "rescheduled_to": null,
      "created_at": "2026-10-01T09:01:00.000Z",
      "version": 1,
      "updated_at": "2026-10-01T09:01:02.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Obtén una cita

GET /v1/bookings/{id}

Devuelve una cita por su identificador. Una cita que esta clave no puede leer, o que se eliminó, responde 404 resource_missing.

Permisos: calendar:read
Límite de frecuencia: Lectura

Parámetros de ruta

id string Obligatorio Prefijo del id bkg_…
El identificador público de la cita.

Respuesta

Devuelve un objeto Booking.

id string Prefijo del id bkg_…
Identificador público del registro.
object string
Siempre booking.
livemode boolean
true en datos reales; false en los datos de ejemplo.
team string Prefijo del id team_…
El equipo al que pertenece este registro.
lead string Puede ser null Prefijo del id lead_…
El lead al que pertenece la cita, o null si la cita no tiene lead o el lead ya no existe. El nombre y los datos de contacto solo aparecen en el lead.
kind string
service_booking (una cita de un servicio reservable, creada por la IA, un cliente o una persona), calendar_event (un evento del calendario conectado) o external_import (sincronizada desde un sistema de citas externo o leída de un correo electrónico de un portal). Una cita de un origen que esta versión no conoce aparece como calendar_event.
Valores posibles
- service_booking
- calendar_event
- external_import
service string Puede ser null Prefijo del id svc_…
El servicio de la cita (ver /booking_services) en una service_booking; null en otro caso.
status string Puede ser null
scheduled, rescheduled, cancelled, postponed, attended, no_show o team_no_show (la asistencia solo la registran personas); null si es un valor que esta versión no conoce. rescheduled significa que la cita se movió sin cambiar de registro y sus horas son las nuevas; una cita que la IA sustituyó por otra queda en cancelled, con rescheduled_to.
Valores posibles
- scheduled
- rescheduled
- cancelled
- postponed
- attended
- no_show
- team_no_show
starts_at string Puede ser null Formato date-time
Cuándo empieza la cita (UTC).
ends_at string Puede ser null Formato date-time
Cuándo termina la cita (UTC).
meeting_type string Puede ser null
online, in_person o phone; null si no está guardado.
Valores posibles
- online
- in_person
- phone
source string Puede ser null
Quién creó la cita: ai, customer u operator; null si no está registrado.
Valores posibles
- ai
- customer
- operator
rescheduled_from string Puede ser null Prefijo del id bkg_…
La cita a la que esta sustituyó al reprogramar, o null. Durante unos segundos la cita sustituida puede seguir en scheduled; las citas reprogramadas antes de que Totem empezara a registrar este enlace pueden no tenerlo.
rescheduled_to string Puede ser null Prefijo del id bkg_…
La cita que sustituyó a esta al reprogramar, o null. Cuando está indicada, esta cita queda en cancelled.
created_at string Puede ser null Formato date-time
Cuándo se registró la cita en Totem (UTC).
version integer Rango ≥ 1
Aumenta cada vez que cambia alguno de los campos exportados del registro. Aplica un cambio solo si su versión es mayor que la que guardas.
updated_at string Formato date-time
Cuándo registró Totem esta versión (UTC). No es la hora en que ocurrió el hecho.

Errores

403 team_state_restricted Equipo restringido
403 sector_restricted Sector restringido
404 resource_missing Recurso no encontrado
409 capture_not_ready Los datos del equipo aún se están preparando

+ 12 errores comunes

curl 'https://api.totemstudio.ai/v1/bookings/bkg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3ttMKHRR9ADk3N7Cr3NSuY0' \
  -H "Authorization: Bearer $TOTEM_API_KEY"

{
  "id": "bkg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3ttMKHRR9ADk3N7Cr3NSuY0",
  "object": "booking",
  "livemode": false,
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "lead": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
  "kind": "service_booking",
  "service": "svc_h42kgwwJGPzsm2Zoy1A1RBv1KIrX5",
  "status": "scheduled",
  "starts_at": "2026-10-06T15:00:00.000Z",
  "ends_at": "2026-10-06T15:30:00.000Z",
  "meeting_type": "in_person",
  "source": "ai",
  "rescheduled_from": null,
  "rescheduled_to": null,
  "created_at": "2026-10-01T09:01:00.000Z",
  "version": 1,
  "updated_at": "2026-10-01T09:01:02.000Z"
}

Lista los servicios reservables

GET /v1/booking_services

Lista todos los servicios reservables del equipo en una sola respuesta, que nunca se pagina y no admite limit ni cursor. Los servicios reservables no llegan por el feed de cambios: lee esta lista al empezar a sincronizar un equipo, de nuevo cuando una cita indique un servicio que no conoces y, como mínimo, una vez al día. Un servicio borrado sale de la lista, pero sus citas siguen indicando su identificador, así que conserva de una lectura anterior el nombre de servicio que necesites.

Permisos: calendar:read
Límite de frecuencia: Sincronización

Cabeceras

Totem-Team string Condicional Prefijo del id team_…
El equipo que se lee, como identificador team_…. Omítelo si la clave lee un solo equipo; es obligatorio si lee varios (400 team_required). Si lo envías, debe indicar un equipo que la clave lee: un identificador mal formado recibe 400 invalid_request, y un equipo fuera de la clave, 404 team_not_accessible, igual que una petición sin la cabecera cuando la clave ya no lee ningún equipo.

Respuesta

Devuelve una lista de objetos BookingService.

object string
Siempre list.
data Array<BookingService>
Todos los servicios reservables del equipo.
has_more boolean
Siempre false: esta lista nunca se pagina.
next_cursor null Puede ser null
Siempre null: no hay página siguiente.

Errores

400 team_required Falta el equipo
403 team_state_restricted Equipo restringido
403 sector_restricted Sector restringido
404 team_not_accessible Equipo no accesible
409 capture_not_ready Los datos del equipo aún se están preparando
429 quota_exceeded Cuota diaria superada

+ 12 errores comunes

curl 'https://api.totemstudio.ai/v1/booking_services' \
  -H "Authorization: Bearer $TOTEM_API_KEY" \
  -H "Totem-Team: $TOTEM_TEAM_ID"

{
  "object": "list",
  "data": [
    {
      "id": "svc_h42kgwwJGPzsm2Zoy1A1RBv1KIrX5",
      "object": "booking_service",
      "livemode": false,
      "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
      "name": "First visit",
      "meeting_type": "in_person"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

El objeto `Booking`

Una cita y su tipo (kind): para un servicio reservable, un evento del calendario conectado o una cita importada de otro sistema.

Atributos

id string Prefijo del id bkg_…
Identificador público del registro.
object string
Siempre booking.
livemode boolean
true en datos reales; false en los datos de ejemplo.
team string Prefijo del id team_…
El equipo al que pertenece este registro.
lead string Puede ser null Prefijo del id lead_…
El lead al que pertenece la cita, o null si la cita no tiene lead o el lead ya no existe. El nombre y los datos de contacto solo aparecen en el lead.
kind string
service_booking (una cita de un servicio reservable, creada por la IA, un cliente o una persona), calendar_event (un evento del calendario conectado) o external_import (sincronizada desde un sistema de citas externo o leída de un correo electrónico de un portal). Una cita de un origen que esta versión no conoce aparece como calendar_event.
Valores posibles
- service_booking
- calendar_event
- external_import
service string Puede ser null Prefijo del id svc_…
El servicio de la cita (ver /booking_services) en una service_booking; null en otro caso.
status string Puede ser null
scheduled, rescheduled, cancelled, postponed, attended, no_show o team_no_show (la asistencia solo la registran personas); null si es un valor que esta versión no conoce. rescheduled significa que la cita se movió sin cambiar de registro y sus horas son las nuevas; una cita que la IA sustituyó por otra queda en cancelled, con rescheduled_to.
Valores posibles
- scheduled
- rescheduled
- cancelled
- postponed
- attended
- no_show
- team_no_show
starts_at string Puede ser null Formato date-time
Cuándo empieza la cita (UTC).
ends_at string Puede ser null Formato date-time
Cuándo termina la cita (UTC).
meeting_type string Puede ser null
online, in_person o phone; null si no está guardado.
Valores posibles
- online
- in_person
- phone
source string Puede ser null
Quién creó la cita: ai, customer u operator; null si no está registrado.
Valores posibles
- ai
- customer
- operator
rescheduled_from string Puede ser null Prefijo del id bkg_…
La cita a la que esta sustituyó al reprogramar, o null. Durante unos segundos la cita sustituida puede seguir en scheduled; las citas reprogramadas antes de que Totem empezara a registrar este enlace pueden no tenerlo.
rescheduled_to string Puede ser null Prefijo del id bkg_…
La cita que sustituyó a esta al reprogramar, o null. Cuando está indicada, esta cita queda en cancelled.
created_at string Puede ser null Formato date-time
Cuándo se registró la cita en Totem (UTC).
version integer Rango ≥ 1
Aumenta cada vez que cambia alguno de los campos exportados del registro. Aplica un cambio solo si su versión es mayor que la que guardas.
updated_at string Formato date-time
Cuándo registró Totem esta versión (UTC). No es la hora en que ocurrió el hecho.

{
  "id": "bkg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3ttMKHRR9ADk3N7Cr3NSuY0",
  "object": "booking",
  "livemode": false,
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "lead": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
  "kind": "service_booking",
  "service": "svc_h42kgwwJGPzsm2Zoy1A1RBv1KIrX5",
  "status": "scheduled",
  "starts_at": "2026-10-06T15:00:00.000Z",
  "ends_at": "2026-10-06T15:30:00.000Z",
  "meeting_type": "in_person",
  "source": "ai",
  "rescheduled_from": null,
  "rescheduled_to": null,
  "created_at": "2026-10-01T09:01:00.000Z",
  "version": 1,
  "updated_at": "2026-10-01T09:01:02.000Z"
}

El objeto `BookingService`

Un servicio que los clientes pueden reservar, con su tipo de reunión.

Atributos

id string Prefijo del id svc_…
Identificador público del registro.
object string
Siempre booking_service.
livemode boolean
true en datos reales; false en los datos de ejemplo.
team string Prefijo del id team_…
El equipo al que pertenece este registro.
name string Puede ser null ≥ 1 caracteres
El nombre del servicio, o null si no hay ninguno guardado.
meeting_type string
Cómo se presta el servicio: online (el valor por defecto si no hay ninguno guardado), in_person o phone.
Valores posibles
- online
- in_person
- phone

{
  "id": "svc_h42kgwwJGPzsm2Zoy1A1RBv1KIrX5",
  "object": "booking_service",
  "livemode": false,
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "name": "First visit",
  "meeting_type": "in_person"
}

Resumen

Parámetros de consulta

Cabeceras

Respuesta

Errores

Parámetros de ruta

Respuesta

Errores

Cabeceras

Respuesta

Errores

El objeto Booking

Atributos

El objeto BookingService

Atributos

El objeto `Booking`

El objeto `BookingService`