Developers

Bukéame para desarrolladores

Pon la reserva del negocio en su propia web con una línea, con sus colores, y conecta sus sistemas con la API y los webhooks. El diseño, las llaves y los webhooks se manejan en el panel del negocio, en Conecta tu web.

La reserva en la web del negocio

Listo

Pega esta línea en la página. El diseño (botón flotante, botón en la página o reserva incrustada, colores, letra, idioma y servicios) sale de lo que el negocio guardó en su panel, así que lo puede cambiar sin tocar el código.

Para la reserva incrustada, o un botón en un lugar fijo, pon un contenedor y apúntale con data-target:

Cualquier atributo en la etiqueta gana sobre lo del panel. Así puedes tener, por ejemplo, la reserva incrustada en una página y un botón flotante en otra:

AtributoQué hace
data-modoflotante, boton o incrustado
data-textoTexto del botón (hasta 40 letras)
data-color · data-color-textoFondo y letra del botón, en #hex
data-acentoColor de la reserva por dentro, en #hex
data-temaauto, claro u oscuro
data-idiomaes o en
data-fuenteInter, Poppins, Montserrat, Lato, Nunito, DM Sans, Outfit, Playfair Display o Instrument Sans
data-redondeoEsquinas, de 0 a 28 (px)
data-posicionBotón flotante: derecha o izquierda
data-alturaAlto de la reserva incrustada, de 480 a 1400 (px)
data-servicio · data-serviciosUn servicio marcado de entrada, o solo esos servicios (ids separados por coma)
data-staffReservar con un profesional en particular
data-vistareserva (por defecto) o perfil, la página completa del negocio

Tus propios botones y eventos

Con el script en la página, cualquier enlace o botón con data-bukeame-reservar abre la reserva con el diseño del negocio, y data-servicio abre un servicio de una vez.

Desde JavaScript: Bukeame.abrir(), Bukeame.abrir({ servicio: 'ID' }) y Bukeame.cerrar(). Cuando el cliente termina una reserva, la página recibe el evento bukeame:reserva para medir conversiones. No trae el código de la cita ni datos del cliente: esos llegan por los webhooks.

Enlace directo y gift cards

Sin código: el enlace de reservas para la bio o un botón, y la página de gift cards.

API pública

Sin llave

Lo que ya es público en la página del negocio, para armar tu propia pantalla de reserva desde el navegador (CORS abierto): servicios, profesionales, horas libres y crear la cita. Las rutas empiezan con /api/public/tu-negocio.

API privada

Listo

Para conectar los sistemas del negocio (su web con servidor, su CRM, su contabilidad) con sus citas y clientes. El negocio crea la llave en Conecta tu web y escoge sus permisos. Va en el encabezado Authorization y se usa solo desde un servidor: nunca la pongas en el código de una página.

RutaPermisoQué hace
GET /api/v1/businesscualquieraDatos y horario del negocio
GET /api/v1/services · /staff · /productscualquieraServicios, profesionales y productos
GET /api/v1/availabilitycualquieraHoras libres: service_id, date y staff_id opcional
GET /api/v1/appointmentsappointments:readCitas por from y to (hasta 93 días), status, staff_id y limit; o las cambiadas desde updated_since
GET /api/v1/appointments/:idappointments:readUna cita, por id o por su código
POST /api/v1/appointmentsappointments:writeCrea la cita con las mismas reglas de la reserva en línea. confirm: true la deja confirmada aunque pida depósito; si queda pendiente, trae payment_url para que el cliente pague
PATCH /api/v1/appointments/:idappointments:writestatus (confirmed, completed, no_show o cancelled_business), start_iso para moverla y, al completar, amount_cents, tip_cents y payment_method
POST /api/v1/appointments/:id/cancelappointments:writeLa cancela y le avisa al cliente. reason es opcional
GET /api/v1/clients · /clients/:idclients:readClientes, con q para buscar, limit y offset
GET /api/v1/ordersorders:readÓrdenes de la tienda

Las respuestas son JSON; las listas vienen en data con has_more. El dinero va en centavos y las horas en ISO 8601 (UTC). Las fechas sueltas (date, from, to) son días del negocio en su zona horaria, que viene en GET /business como timezone (por ejemplo America/Puerto_Rico o America/New_York). Los errores traen error (en español) y code: invalid_key (401), plan_required (402), missing_scope (403), not_found (404), conflict (409, por ejemplo una hora que ya se tomó) y rate_limited (429). Cada llave puede hacer 120 pedidos por minuto. La API es del plan Pro en adelante.

Webhooks

Listo

Bukéame le hace un POST con JSON a la dirección https que el negocio ponga en Conecta tu web cuando pasa algo, solo de los eventos que escoja. Contesta con un 2xx en menos de 8 segundos; si no, se reintenta en 1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 24 h. Tras 50 fallos seguidos el webhook se apaga solo y el panel dice por qué.

EventoCuándo
appointment.createdCita nueva (página, widget, panel, recepcionista o API)
appointment.confirmedSe pagó el depósito o el negocio la aceptó
appointment.rescheduledLa movieron de hora (trae previous_starts_at)
appointment.cancelledLa canceló el cliente o el negocio
appointment.completed · appointment.no_showSe completó, o el cliente no llegó
payment.receivedPago recibido: depósito, saldo o propina
order.created · order.paid · order.fulfilled · order.cancelledÓrdenes de la tienda

Cada aviso trae Bukeame-Signature: t=…,v1=…: el HMAC-SHA256 de t + "." + cuerpo con el secreto del webhook (whsec_…). Compáralo antes de creer el aviso y descarta los de más de 5 minutos. Bukeame-Event trae el tipo y Bukeame-Delivery el número de entrega, que sirve para no procesar dos veces el mismo aviso.

¿Dudas, o algo que te falta? Escríbenos a hi@bukeame.com.

Hecho con Bukéame · bukeame.com