Ayuda · Consultorio, citas y portal del gestor

Vitrina comprador (modo CS)

Las tiendas tipo consultorio / SPA usan el prefijo de URL /CS/{slug} (por ejemplo /CS/mi-spa). La API valida que el tipo de tienda coincida con la URL; si no, puede devolver error y redirigir al prefijo correcto.

El cliente elige experto / gestor (cuando el servicio no es “asignación automática”) y un horario en la agenda.
Para reservar el hueco en carrito hace falta iniciar sesión con una cuenta de comprador en Vende Fácil; el sistema aparta el intervalo unos minutos (configurables en el panel del dueño: Apartado temporal en carrito, típicamente 5 min).
En el carrito puede aparecer Verificar disponibilidad para renovar o comprobar el apartado antes de pagar.
Tras el pago, el recibo puede mostrar un bloque con fecha, hora, gestor y estado de la cita.

Apartado temporal (`POST /api/appointments/lock`)

Evita que dos compradores confirmen el mismo hueco al mismo tiempo. El token de apartado viaja en la línea del carrito y se valida al crear el pedido.

Solo aplica a tiendas tipo consultorio (CS).
Requiere JWT de comprador (no de gestor ni de dueño).
Si el apartado caduca o otro usuario tiene el hueco, el checkout puede responder con conflicto; en ese caso elija otro horario o vuelva a apartar.

Portal del gestor (orden de trabajo · OT)

El gestor accede con usuario y contraseña definidos por el dueño en Agentes. La URL de la cita suele incluir el segmento OT y el id de la cita.

Patrones de URL habituales

Recomendado (canónico): /{T|TR|RE|CS}/{slug}/OT/{idCita} — en consultorio: /CS/ALFA/OT/12345 (coincide con el prefijo de la vitrina).
Compatibilidad: /{slug}/OT/{idCita} — ejemplo /ALFA/OT/12345; el servidor también sirve el portal en esta forma.

El dueño puede generar o reenviar el enlace desde el detalle de la cita en la agenda del panel (compartir acceso al portal). Mantenga abrir el enlace en el mismo dominio donde opera la tienda (producción vs pruebas).

Qué puede hacer el gestor en el portal

Ver datos del cliente, fecha/hora y pedido vinculado.
Iniciar servicio y Finalizar servicio (con comentarios opcionales al cerrar).
Pedido adicional y actividades mientras la cita está en curso.
Abrir TPV con el mismo cliente y vínculo de cita (la URL del TPV incluye parámetros para no mezclar pedidos).
Mi historial: pedidos creados como gestor.

Panel del dueño (agenda y citas)

En Panel de ventas → Agenda puede configurar la agenda global, ver citas, abrir el detalle de una cita, cancelar (cuando aplique) o compartir acceso al portal del gestor.

El campo Apartado temporal en carrito (minutos) (solo consultorio) controla cuánto tiempo permanece reservado el hueco cuando un comprador añade la cita al carrito (entre 3 y 30 minutos).

El campo Anticipación mínima para reservar (minutos) define con cuánta antelación el comprador puede elegir un horario en la vitrina (0–10080 min, equivalente a 7 días). No confundir con el apartado en carrito.

Tiempo real (SignalR)

En el host ASP.NET Core 8, la tienda puede usar notificaciones en tiempo casi real para dueños, gestores y compradores conectados.

La vitrina del comprador (sesión iniciada) y el portal del gestor se conectan al hub /hubs/store-notifications mediante SignalR (biblioteca @microsoft/signalr desde CDN). El host Core ya no ofrece stream SSE en esa ruta.
Ejemplos de eventos útiles: confirmación de pagos (order_paid), novedades de restaurante, etc. La lista exacta evoluciona con el producto.
En desarrollo local, si la consola del navegador muestra avisos de WebSocket por el refresco de dotnet watch, suele ser ruido de herramientas; recargue la página o use el perfil HTTP descrito en la guía de desarrollo del proyecto.

Placeholders en el HTML personalizado

En Configuración → Diseño de tienda → HTML personalizado puede insertar bloques que el motor sustituye al renderizar la vitrina.

Placeholder	Uso en consultorio / citas
`{{gestor_list}}`	Listado de expertos para que el comprador elija gestor antes de ver horarios (modo CS y flujos con agentes).
`{{product_portfolio}}`	Catálogo y ficha de producto; obligatorio para mostrar servicios citables.
`{{banner}}` / `{{store_name}}`	Banner superior y nombre de la tienda (común a todos los modos).

Referencia ampliada de selectores CSS en el mismo acordeón de diseño del panel.

URLs de ejemplo (no sustituya sin adaptar)

Reemplace {slug} por el nombre corto de su tienda y los ids por valores reales.

Vitrina consultorio: https://su-dominio/CS/{slug}
Servicio concreto (SKU): https://su-dominio/CS/{slug}/SER-CON-001
Portal del gestor (consultorio, cita 99): https://su-dominio/CS/{slug}/OT/99 (preferido; también …/{slug}/OT/99)
TPV enlazado desde el portal (ejemplo): https://su-dominio/{slug}/TPV?email=…&orderId=…&appointmentId=…

API (referencia técnica · borde Core 8)

Rutas habituales del flujo de citas en el API nativo (pueden delegarse al servidor legado si un administrador desactiva los toggles VendeFacil:UseNative* correspondientes). Detalle en docs/MIGRATION_NET8_SIGNALR.md.

Método	Ruta (resumen)	Rol
GET	`/api/storefront/cs/{slug}`	Datos públicos de la tienda CS.
GET	`/api/appointments/agenda-board/{storeId}`	Tablero de huecos (query: fecha, agente, producto).
POST	`/api/appointments/lock`	Apartar hueco (JWT comprador).
POST	`/api/orders`	Crear pedido con líneas de cita y `SlotLockToken` si aplica.
GET	`/api/appointments/{id}/agent-view`	Portal gestor: vista de la cita (JWT gestor + contexto de tienda).
POST	`/api/appointments/{id}/start` · `…/finish`	Iniciar / finalizar servicio desde el portal.
WS / SSE	`/hubs/store-notifications` · stream notificaciones	Tiempo real (SignalR preferente).

Documentación en el repositorio

docs/CONSULTORIO_CITAS_AGENDA_Y_CHECKOUT.md — flujo completo, carrito, recibo y QA sugerido.
docs/MANUALES_TIENDA.md — convenciones de URL por tipo de tienda.
docs/MIGRATION_NET8_SIGNALR.md — toggles nativos, rutas Core y SignalR.