Saltar al contenido

Calendar

Tu agenda, páginas de reservas y servicios.

Abrir Calendar
Comprobado con el panel el 19 de noviembre de 2026

Calendar tiene métodos públicos para los dos lados de una reserva. Unos actúan por ti, el propietario, y toman tu clave de API: leen tu configuración y tus reservas, configuran recursos, servicios y páginas, retienen y confirman una hora, cancelan y cambian el plan. Otros son los que hace una página de reservas por un visitante. No necesitan clave, solo la clave de la página.

Compartir calendarios con otras personas, las vistas, las tareas, los eventos de día y los Ajustes del calendario se hacen en el dashboard. Hoy no tienen método público.

Envía una solicitud a un método con tu clave:

curl -s https://xuda.ai/cpi/get_calendar_setup \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY","uid":"YOUR_ACCOUNT_UID"}'
const res = await fetch('https://xuda.ai/cpi/get_calendar_setup', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    api_key: 'YOUR_API_KEY',
    uid: 'YOUR_ACCOUNT_UID',
  }),
});
const { code, data } = await res.json();
import requests

res = requests.post(
    'https://xuda.ai/cpi/get_calendar_setup',
    json={
        'api_key': 'YOUR_API_KEY',
        'uid': 'YOUR_ACCOUNT_UID',
    },
)

Una buena respuesta tiene code 1. Un cambio que tu plan no incluye se rechaza con code -62 y una frase en data, por ejemplo que las sesiones de grupo necesitan Growth o que tu plan admite un número de páginas de reservas. Para actuar sobre el calendario de una cuenta que lo compartió contigo con nivel de edición, pasa su share_id a los métodos que lo toman.

Lee tu configuración y tus reservas

  • get_calendar_setup responde en una sola llamada todo lo que dibujan las pantallas de Calendar: las personas y salas reservables con sus horas, los servicios y las páginas de reservas publicadas con sus direcciones públicas.
  • get_calendar_bookings lista reservas, las próximas por defecto. Pasa past en true para las que ya ocurrieron, las más recientes primero, y limit para cuántas. Cada fila lleva la hora en la zona del recurso, los datos del invitado y todo lo que dijo al reservar.
  • get_calendar_slots lista las horas reservables de un servicio en un recurso entre from_ts y to_ts (milisegundos de época), sin las que ya están ocupadas.

Configura lo que se puede reservar

  • save_calendar_resource crea o actualiza algo que se puede reservar: una persona, una sala, un sillón o un dispositivo. Necesita un timezone, una zona IANA como Asia/Jerusalem, y sus horas se leen en esa zona. Omite resource_id para crear uno nuevo.
  • save_calendar_service crea o actualiza lo que se puede reservar: su duración, márgenes, aviso previo, con cuánta antelación se puede reservar, plazas, dónde se realiza (meeting_kind) y, con price_cents, currency y checkout, lo que cuesta y si se paga al reservar. Más de una plaza necesita un plan que incluya sesiones de grupo, y cobrar necesita un plan que incluya pagos.
  • save_calendar_page crea o actualiza una página de reservas: su title, intro, los service_ids que ofrece, si está enabled, su color accent, show_host, si los visitantes pueden cambiar su reserva (visitor_changes, change_hours, refund_percent) y la cuenta de finanzas en la que se cobra (finance_account_id). Se rechaza crear una página que supere el límite de páginas de tu plan.
  • delete_calendar_item elimina un recurso, un servicio o una página por item_id. Las reservas nunca se eliminan así: se cancelan.

Reserva una hora tú mismo

Reservar desde tu propio código son dos pasos, para que una hora nunca se venda dos veces.

Retén la hora

hold_calendar_slot reserva una hora durante unos minutos. Pasa resource_id, service_id y start_utc (milisegundos de época). Una buena respuesta tiene data con occ_id, hold_token y expires_at. Envía una idem_key para que una repetición de la llamada devuelva la misma retención en lugar de tomar una segunda plaza.

Confírmala

confirm_calendar_booking convierte la retención en una reserva. Pasa el occ_id y el hold_token de la retención, y el name, email, phone y note del invitado. Una retención que ya no existe ha perdido la hora y se rechaza.

curl -s https://xuda.ai/cpi/hold_calendar_slot \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY","uid":"YOUR_ACCOUNT_UID","resource_id":"RESOURCE_ID","service_id":"SERVICE_ID","start_utc":1793000000000}'
const res = await fetch('https://xuda.ai/cpi/hold_calendar_slot', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    api_key: 'YOUR_API_KEY',
    uid: 'YOUR_ACCOUNT_UID',
    resource_id: 'RESOURCE_ID',
    service_id: 'SERVICE_ID',
    start_utc: 1793000000000,
  }),
});
const { code, data } = await res.json();
import requests

res = requests.post(
    'https://xuda.ai/cpi/hold_calendar_slot',
    json={
        'api_key': 'YOUR_API_KEY',
        'uid': 'YOUR_ACCOUNT_UID',
        'resource_id': 'RESOURCE_ID',
        'service_id': 'SERVICE_ID',
        'start_utc': 1793000000000,
    },
)

Cambia una reserva

  • cancel_calendar_booking cancela por booking_id y devuelve la hora a la cuadrícula pública. Es seguro llamarlo dos veces. Solo libera la hora: no envía correo al invitado ni reembolsa un pago, que es lo que hace Cancelar cita del dashboard con un invitado que reservó a través de tu página.
  • notify_calendar_guests envía un correo a todos los invitados a una reserva, un mensaje a cada uno, con la invitación de calendario adjunta y un message opcional de hasta 2000 caracteres. kind es invite para una cita nueva y update para un cambio, que es el valor por defecto. El correo sale de tu propio buzón en un plan que lo incluye, y de la dirección de reservas de Xuda en caso contrario, con tu dirección como respuesta.
  • create_booking_room crea la sala de Xuda Meet de una reserva de vídeo confirmada que no la tiene, y envía a cada invitado el enlace.

Qué llama una página de reservas

Una página de reservas funciona con su clave de página, <uid>.<page_id>, y sin cuenta.

  • get_booking_bootstrap responde lo que una página necesita para dibujarse: su título, sus servicios y un token antibot nuevo.
  • get_public_booking_slots lista las horas que puede elegir un visitante, cada una con un inicio, un fin y un número de plazas. Nunca dice quién ocupa las demás plazas.
  • public_book_slot toma una reserva de un visitante. Pasa el page_key, service_id, start_utc, el token y el name y email del visitante. Añade una idem_key para que una doble pulsación no reserve dos veces. company_website es una trampa para bots: déjalo vacío.
  • Para un servicio que se paga al reservar, public_start_paid_booking retiene la hora e inicia el pago, start_booking_payment envía una hora retenida a Stripe, y public_confirm_paid_booking y confirm_paid_booking la reservan cuando el pago se ha completado. El pago se vuelve a leer de Stripe antes de reservar nada.
  • Un visitante gestiona una reserva desde el enlace privado de su correo. get_public_booking, public_cancel_booking y public_reschedule_booking toman la clave de la página y el valor manage de ese enlace. Siguen las reglas de la página: si los visitantes pueden cambiar una reserva y hasta cuántas horas antes de que empiece. Una reserva pagada se reembolsa primero, según el porcentaje de reembolso de la página.

El plan

get_calendar_plans responde los cuatro niveles con sus precios y lo que incluye cada uno, en qué plan estás y si Calendar está activado. calendar_set_plan lo activa, cambia el nivel o lo desactiva: pasa plan_id como calendar_free, calendar_starter, calendar_growth o calendar_business, o pon deactivate en true. Consulta Planes y facturación.

Todos los métodos

¿Qué te parece esta guía?

Última actualización: 16 de noviembre de 2026