Cliente · Sesión y carrito

Esta área cubre el arranque de la experiencia del comensal: el registro y login del cliente (email/contraseña y OAuth con Google/Apple), la sesión de mesa que se abre al escanear el QR (TableSession, identificada por session_token) y el carrito compartido que todos los comensales de la mesa ven y editan en tiempo real. Es el punto de entrada al que llega el frontend tras leer el QR y desde el que se construye lo que luego pasará a comanda.

Modelo de auth. Conviven dos esquemas. Por un lado, la autenticación del cliente (/register, /login, /oauth/*) devuelve un JWT Bearer para la cuenta del comensal, con state anti-CSRF y PKCE en el flujo OAuth de Google. Por otro, las sesiones de mesa no usan JWT de usuario: se identifican por el session_token opaco que viaja en la ruta (/sessions/{session_token}/...); ese token, derivado del JWT del QR, es la credencial efectiva para operar sobre la sesión y su carrito.

Patrones comunes:

• Multitenancy por restaurant_id: la sesión queda ligada al restaurante y la mesa resueltos desde el JWT del QR; el restaurant_id no se acepta nunca del body, siempre se deriva del token verificado.
• Idempotencia: POST /sessions/validate y POST /sessions/{token}/call-manager son naturalmente idempotentes (reusan la sesión o llamada activa, sin cabecera). POST /sessions/{token}/cart/items acepta una cabecera Idempotency-Key opcional, scopeada por session_token, para que un reintento tras timeout no duplique cantidad; las llamadas concurrentes con la misma clave reciben 409.
• Tiempo real por SSE: GET /sessions/{token}/events mantiene un stream text/event-stream que emite cart_updated, chat_message, session_closed y guest_count_updated con heartbeats periódicos. Toda mutación del carrito publica cart_updated. Ver eventos SSE.

Precios en céntimos y optimistic locking

Todos los importes (price, total_price, total) van en céntimos (enteros): 12,50 € es 1250. Las respuestas de sesión incluyen un campo version para el optimistic locking: las escrituras concurrentes sobre la misma sesión se detectan por versión y un conflicto se traduce en 409.

Para el porqué de las decisiones de negocio (ventana de jornada de 10 h que no es timeout de inactividad, bloqueo de pedidos con sesión pausada, cómo el precio de línea incluye los extras, tope acumulado por producto), consulta Sesiones y carrito. Para el modelo de cuentas de cliente, preferencias y reseñas, consulta Clientes y reseñas. Visión general del contrato de API en Referencia de API.

Generado automáticamente

Las tablas y fichas de endpoints de esta página se generan desde el contrato OpenAPI. No las edites a mano; edita la intro en documentation/reference/api/_intros/cliente-sesion-carrito.md y regenera con python scripts/gen_openapi_reference.py.

Resumen de endpoints

Método	Ruta	Resumen	Auth
POST	/api/v1/auth/login	Login Customer	Pública
GET	/api/v1/auth/oauth/apple	Initiate Apple Oauth	Pública
POST	/api/v1/auth/oauth/callback	Oauth Callback	Pública
GET	/api/v1/auth/oauth/google	Initiate Google Oauth	Pública
POST	/api/v1/auth/register	Register Customer	Pública
GET	/api/v1/customers/me	Get Current User Profile	Bearer (admin)
PATCH	/api/v1/customers/me	Update Current User Profile	Bearer (admin)
POST	/api/v1/sessions/peek	Peek Session	Pública
POST	/api/v1/sessions/validate	Validate Session	Pública
GET	/api/v1/sessions/{session_token}	Get Session	Pública
POST	/api/v1/sessions/{session_token}/call-manager	Call Manager	Pública
GET	/api/v1/sessions/{session_token}/cart	Get Cart	Pública
POST	/api/v1/sessions/{session_token}/cart/items	Add Cart Item	Pública
DELETE	/api/v1/sessions/{session_token}/cart/items/{item_id}	Delete Cart Item	Pública
PATCH	/api/v1/sessions/{session_token}/cart/items/{item_id}	Update Cart Item	Pública
POST	/api/v1/sessions/{session_token}/dismiss-manager-call	Dismiss Manager Call	Pública
GET	/api/v1/sessions/{session_token}/events	Session Events	Pública
PATCH	/api/v1/sessions/{session_token}/guest-count	Update Guest Count	Pública
POST	/api/v1/sessions/{session_token}/invalidate	Invalidate Session	Pública
POST	/api/v1/sessions/{session_token}/refresh	Refresh Session	Pública

Detalle

POST /api/v1/auth/login

Login Customer

Login customer and return access token.

• Auth: Pública
• Parámetros: —
• Body: LoginRequest
• Respuestas: 200 TokenResponse, 422 HTTPValidationError

GET /api/v1/auth/oauth/apple

Initiate Apple Oauth

Initiate Apple OAuth2 flow for customer authentication.

• Auth: Pública
• Parámetros: —
• Respuestas: 200 OAuthInitResponse

POST /api/v1/auth/oauth/callback

Oauth Callback

Handle OAuth2 callback and create customer session.

• Auth: Pública
• Parámetros: —
• Body: OAuthCallbackRequest
• Respuestas: 200 CustomerOAuthResponse, 422 HTTPValidationError

GET /api/v1/auth/oauth/google

Initiate Google Oauth

Initiate Google OAuth2 flow for customer authentication.

• Auth: Pública
• Parámetros: —
• Respuestas: 200 OAuthInitResponse

POST /api/v1/auth/register

Register Customer

Register a new customer.

• Auth: Pública
• Parámetros: —
• Body: RegisterRequest
• Respuestas: 201 CustomerResponse, 422 HTTPValidationError

GET /api/v1/customers/me

Get Current User Profile

Get current authenticated customer profile.

• Auth: Bearer (admin)
• Parámetros: —
• Respuestas: 200 CustomerResponse

PATCH /api/v1/customers/me

Update Current User Profile

Update current authenticated customer profile and preferences.

• Auth: Bearer (admin)
• Parámetros: —
• Body: CustomerUpdateRequest
• Respuestas: 200 CustomerResponse, 422 HTTPValidationError

POST /api/v1/sessions/peek

Peek Session

Validate the QR JWT and report whether an active session already exists

• Auth: Pública
• Parámetros: —
• Body: PeekSessionRequest
• Respuestas: 200 PeekSessionResponse, 422 HTTPValidationError

POST /api/v1/sessions/validate

Validate Session

Validate QR code (JWT) and create or reuse a table session.

• Auth: Pública
• Parámetros: —
• Body: ValidateSessionRequest
• Respuestas: 200 ValidateSessionResponse, 422 HTTPValidationError

GET /api/v1/sessions/{session_token}

Get Session

Get session details by token.

• Auth: Pública
• Parámetros: session_token (path, requerido)
• Respuestas: 200 SessionResponse, 422 HTTPValidationError

POST /api/v1/sessions/{session_token}/call-manager

Call Manager

Call a manager for assistance at the current table session.

• Auth: Pública
• Parámetros: session_token (path, requerido)
• Body: CallManagerRequest
• Respuestas: 201 CallManagerResponse, 422 HTTPValidationError

GET /api/v1/sessions/{session_token}/cart

Get Cart

Get all items in the session's cart.

• Auth: Pública
• Parámetros: session_token (path, requerido)
• Respuestas: 200 CartResponse, 422 HTTPValidationError

POST /api/v1/sessions/{session_token}/cart/items

Add Cart Item

Add an item to the cart.

• Auth: Pública
• Parámetros: Idempotency-Key (header, opcional), session_token (path, requerido)
• Body: CartItemCreate
• Respuestas: 201 CartItemResponse, 422 HTTPValidationError

DELETE /api/v1/sessions/{session_token}/cart/items/{item_id}

Delete Cart Item

Remove an item from the cart.

• Auth: Pública
• Parámetros: item_id (path, requerido), session_token (path, requerido)
• Respuestas: 204, 422 HTTPValidationError

PATCH /api/v1/sessions/{session_token}/cart/items/{item_id}

Update Cart Item

Update quantity of a cart item.

• Auth: Pública
• Parámetros: item_id (path, requerido), session_token (path, requerido)
• Body: CartItemUpdate
• Respuestas: 200 CartItemResponse, 422 HTTPValidationError

POST /api/v1/sessions/{session_token}/dismiss-manager-call

Dismiss Manager Call

Customer dismisses their manager call, unpausing the session.

• Auth: Pública
• Parámetros: session_token (path, requerido)
• Body: ManagerCallDismiss
• Respuestas: 200, 422 HTTPValidationError

GET /api/v1/sessions/{session_token}/events

Session Events

SSE endpoint for real-time session events.

• Auth: Pública
• Parámetros: session_token (path, requerido)
• Respuestas: 200, 422 HTTPValidationError

PATCH /api/v1/sessions/{session_token}/guest-count

Update Guest Count

Update the guest count for an active session.

• Auth: Pública
• Parámetros: session_token (path, requerido)
• Body: UpdateGuestCountRequest
• Respuestas: 200 SessionResponse, 422 HTTPValidationError

POST /api/v1/sessions/{session_token}/invalidate

Invalidate Session

Invalidate (end) a session.

• Auth: Pública
• Parámetros: session_token (path, requerido)
• Respuestas: 204, 422 HTTPValidationError

POST /api/v1/sessions/{session_token}/refresh

Refresh Session

Refresh session expiration time.

• Auth: Pública
• Parámetros: session_token (path, requerido)
• Respuestas: 200 SessionResponse, 422 HTTPValidationError