Calendar
Tu agenda, páginas de reservas y servicios.
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:
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_setupresponde 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_bookingslista reservas, las próximas por defecto. Pasapastentruepara las que ya ocurrieron, las más recientes primero, ylimitpara 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_slotslista las horas reservables de un servicio en un recurso entrefrom_tsyto_ts(milisegundos de época), sin las que ya están ocupadas.
Configura lo que se puede reservar
save_calendar_resourcecrea o actualiza algo que se puede reservar: una persona, una sala, un sillón o un dispositivo. Necesita untimezone, una zona IANA comoAsia/Jerusalem, y sus horas se leen en esa zona. Omiteresource_idpara crear uno nuevo.save_calendar_servicecrea 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, conprice_cents,currencyycheckout, 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_pagecrea o actualiza una página de reservas: sutitle,intro, losservice_idsque ofrece, si estáenabled, su coloraccent,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_itemelimina un recurso, un servicio o una página poritem_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.
Cambia una reserva
cancel_calendar_bookingcancela porbooking_idy 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_guestsenvía un correo a todos los invitados a una reserva, un mensaje a cada uno, con la invitación de calendario adjunta y unmessageopcional de hasta 2000 caracteres.kindesinvitepara una cita nueva yupdatepara 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_roomcrea 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_bootstrapresponde lo que una página necesita para dibujarse: su título, sus servicios y un token antibot nuevo.get_public_booking_slotslista 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_slottoma una reserva de un visitante. Pasa elpage_key,service_id,start_utc, eltokeny elnameyemaildel visitante. Añade unaidem_keypara que una doble pulsación no reserve dos veces.company_websitees una trampa para bots: déjalo vacío.- Para un servicio que se paga al reservar,
public_start_paid_bookingretiene la hora e inicia el pago,start_booking_paymentenvía una hora retenida a Stripe, ypublic_confirm_paid_bookingyconfirm_paid_bookingla 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_bookingypublic_reschedule_bookingtoman la clave de la página y el valormanagede 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.