Integrar la cita online en la web del taller con la agenda real

Para integrar la cita online en la web del taller sin duplicar agendas, tu web tiene que preguntar los huecos libres a la agenda real del programa y, cuando el cliente elige uno, crear la cita allí mismo. Con la API de Programa Taller eso son dos llamadas: GET /appointments/availability devuelve los huecos teniendo en cuenta el horario, los boxes, la hora de comer, los festivos y las citas ya puestas, y POST /appointments guarda la cita como propuesta que confirmas tú o como reserva en firme, según cómo trabaje tu taller.

La diferencia con un formulario de contacto o con un calendario de reservas genérico es que no hay una segunda agenda que mantener. Si el martes a las 10:00 ya está ocupado en el programa, la web no lo ofrece. Lo que sigue sirve para dos personas: el gerente, que decide cómo quiere recibir las citas, y quien le hace la web, que encontrará las peticiones y los errores que tiene que controlar.

¿Qué formas hay de poner cita online en la web de un taller?

Antes de hablar de API conviene ver las alternativas, porque no todos los talleres la necesitan.

Si no tienes web propia o no quieres pagar desarrollo, el propio programa ya ofrece al cliente cita con huecos reales desde la página de seguimiento de su presupuesto. Lo cuenta el artículo sobre cita previa online con los huecos reales del taller. La API tiene sentido cuando quieres que la reserva empiece en tu web, con tu diseño, antes de que exista ningún presupuesto.

¿La cita entra en firme o la tengo que confirmar yo?

Es la primera decisión, y es del gerente. El programa guarda un modo de reserva por taller (booking_mode), que tu web puede leer con GET /workshop o en la propia respuesta de huecos libres.

• Modo «proponer» (propose). La web crea una propuesta (status=proposed). El hueco queda bloqueado para que nadie más lo coja, pero la cita no es definitiva hasta que alguien del taller la confirma. Si la web intenta reservar en firme, la API responde 403 booking_mode_propose_only.
• Modo «reservar» (book). La cita queda confirmada en la agenda en el momento (status=confirmed). Aun así, la web puede pedir una propuesta si le conviene, enviando mode=propose.

¿Cuál elegir? Depende de lo que te cueste equivocarte. Si una cita mal puesta te descuadra el día (un cambio de embrague en un hueco de una hora, un coche que no cabe en el elevador libre), empieza en modo propuesta: revisas, confirmas y la web se entera. Si casi todo lo que entra por la web son revisiones y cambios de aceite de duración conocida, el modo reserva quita una tarea al equipo y el cliente sale con la cita cerrada.

Cómo lo vive el cliente: una reserva un domingo por la noche

Domingo, 22:40. Nerea Vidal ha visto el testigo del aceite encendido al volver de un viaje y no quiere esperar al lunes para llamar. Entra en la web del taller desde el móvil.

1. Elige el servicio «Cambio de aceite y filtro» en una lista. La web ha leído esa lista y su precio de la tarifa del taller, así que lo que ve es lo mismo que le diría el mostrador.
2. Ve los huecos de los próximos días: martes 9:00, martes 9:30, miércoles 16:00… Ninguno a menos de una hora vista y ninguno en festivo.
3. Escribe su nombre, su móvil y la matrícula, 7391 LMR. El email es opcional.
4. Pulsa «Pedir cita» para el martes a las 9:00.
5. La web le contesta: «Hemos recibido tu cita para el martes a las 9:00. El taller la confirmará a primera hora del lunes». El taller trabaja en modo propuesta.

El lunes a las 8:05, la persona del mostrador ve la propuesta en la agenda, comprueba que el box está libre y la confirma. La web recibe el aviso y manda a Nerea su confirmación. Nadie ha tenido que llamar a nadie, y el hueco de las 9:00 del martes estuvo bloqueado desde el domingo, así que no se lo dieron a otro por teléfono.

Para el taller el cambio es de escala. Atender por teléfono veinte peticiones de cita a la semana son veinte conversaciones; recibirlas por la web son veinte clics de confirmación, a cualquier hora y sin que el teléfono suene mientras estás con un cliente delante.

Cómo se hace, paso a paso (para quien programa la web)

Esta parte es para tu informático o tu agencia. Todo está en la referencia de la API; aquí va el recorrido mínimo. La URL base es la del dominio del taller, con la forma https://<su-dominio>/api/v1; en los ejemplos usamos tu-taller.example.

1. Una clave con los permisos justos

La gerencia crea la clave en «Desarrolladores / API», con un nombre («Web de citas»), la finalidad y estos permisos: clients:write, vehicles:write, budgets:write, appointments:read y appointments:write. Si quieres mostrar el catálogo con precios, añade catalog:read. Escribir datos exige el plan de API Developer o superior; los planes están en la portada de la API.

2. Pedir los huecos libres

Detalles que conviene saber: los inicios van cada 30 minutos y siempre al menos una hora desde ahora; por defecto devuelve 7 días y como máximo 31; la duración admite de 15 a 720 minutos. Las horas vienen en UTC: la web tiene que pasarlas a hora peninsular antes de enseñarlas (la zona horaria del taller está en GET /workshop). Las propuestas pendientes también bloquean su hueco, así que no se ofrecen.

3. Cliente, vehículo y presupuesto

En el programa una cita cuelga siempre de un presupuesto (budget_id). Por eso, antes de la cita, la web crea o recupera tres cosas:

• POST /clients?on_conflict=return_existing con nombre, teléfono y, si lo hay, email. Si ese teléfono o email ya está en una ficha, recibes ese cliente en vez de un duplicado.
• POST /vehicles?on_conflict=return_existing con el client_id y la matrícula. Si la matrícula está a nombre de otro cliente, la API responde 409 vehicle_belongs_to_other_client: no lo fuerces, deja que el taller lo resuelva y di al cliente que le llamarán.
• POST /budgets con el cliente, el vehículo y la partida del servicio elegido. Entra en estado «Pendiente» con canal «API», igual que un alta desde el programa.

Cada POST lleva la cabecera Idempotency-Key con un identificador nuevo por operación. Si el móvil del cliente pierde la cobertura justo al pulsar y tu servidor reintenta, el programa reconoce la operación y no crea un segundo cliente ni un segundo presupuesto.

4. Crear la cita

La respuesta trae la cita con su status (proposed o confirmed), el cliente, el vehículo y el box. Con eso tu web ya puede pintar la pantalla de «cita recibida».

5. Enterarte de la confirmación

Si trabajas en modo propuesta, suscribe un webhook a appointment.confirmed: cuando el taller confirma, tu servidor recibe el aviso y manda el email o el mensaje de confirmación al cliente. Si el taller la anula, llega appointment.cancelled; si la mueve, appointment.updated. Los webhooks van firmados con HMAC-SHA256 y forman parte del plan Developer.

¿Qué pasa si dos clientes quieren el mismo hueco?

Pasa más de lo que parece: dos personas miran la web a la vez, o alguien coge por teléfono el hueco que un cliente tiene abierto en el móvil desde hace diez minutos. La API valida el hueco en el momento de crear la cita con la misma lógica que la consulta de disponibilidad. Si ya no está libre, responde 409 slot_unavailable y en error.alternatives trae hasta tres huecos alternativos.

Una web bien hecha no enseña un error: enseña esas alternativas. «Las 9:00 se acaban de ocupar. ¿Te va bien a las 9:30, a las 10:00 o el miércoles a las 16:00?» El cliente elige y sigue. Tu informático solo tiene que tratar ese código de respuesta como un caso normal, no como un fallo.

¿Quién avisa al cliente: la web o el programa?

Por defecto, crear una cita por API no avisa al cliente: lo hace tu web, con su propio email o mensaje. Si prefieres que lo mande el programa, la cita y el presupuesto admiten notify_client=true, que exige el permiso communications:send. El envío de email y SMS por API forma parte del plan Business.

Ten en cuenta una cosa: el enlace de seguimiento del presupuesto, el que el cliente usa para ver fases, fotos y aceptar, no sale por la API. Lo envía el taller desde el programa. Si quieres que el cliente lo reciba nada más reservar, crea el presupuesto con notify_client=true (también con communications:send): el programa le manda el acuse con su enlace de seguimiento.

Y el idioma: si tu web está en varios idiomas, guarda el que elija el cliente en su ficha (preferred_language). Así los avisos posteriores del taller le llegan en su idioma sin que nadie lo deduzca por el apellido.

Errores que vemos al conectar una web de citas

• Consultar huecos en cada visita. Cada clave admite 60 peticiones por minuto, y el plan tiene un cupo diario (20.000 en Developer). Una web con tráfico debe guardar la respuesta un par de minutos y volver a validar solo al reservar, que es cuando importa.
• Olvidar la zona horaria. Si la web muestra las horas en UTC, la cita de las 9:00 aparece a las 7:00. Pasa todo a la zona del taller antes de pintar.
• Una duración igual para todo. Si la web pide 30 minutos para un cambio de distribución, ofrecerá huecos que no caben. Asocia a cada servicio su duración.
• Reintentar sin Idempotency-Key. Sin ella, un doble clic puede dejar dos presupuestos. La API la exige en todo POST y responde 400 idempotency_key_required si falta.
• Probar con datos reales. Las claves pt_test_ de tu taller leen datos pero no escriben. Para probar el ciclo entero, con citas y webhooks, usa el entorno de pruebas público con datos ficticios.

Lo que la integración no resuelve

La API pone los huecos y guarda la cita; no diseña tu web. Alguien tiene que hacer el formulario, la pantalla de alternativas y los avisos, y eso son horas de desarrollo que conviene presupuestar antes. Si tu web es una plantilla que nadie toca desde hace años, quizá te compense más mandar al cliente a la cita de la página de seguimiento que ya tiene el programa.

Tampoco sustituye el criterio del taller. La agenda sabe qué huecos hay libres, pero no sabe si ese coche en concreto necesita dos horas en vez de una, ni si la pieza llegará a tiempo. Por eso el modo propuesta existe. Y una cita online no diagnostica: si el cliente escribe «hace un ruido raro», lo honesto es una propuesta que alguien revisa y una llamada, no una hora cerrada.

Lo que sí cambia es dónde pasa tu tiempo. En lugar de cuadrar horas por teléfono, el equipo confirma o ajusta, y el gerente puede mirar la agenda de la semana y decidir cuántos boxes abre, en vez de pelearse con ella. Si quieres ver cómo reparte el programa el trabajo entre boxes una vez el coche entra, tienes la guía sobre organizar boxes y mecánicos. Y para todas las integraciones posibles, la página de la API para talleres.

Preguntas frecuentes