Cliente · Comanda, pago y reseñas

Esta área cubre el tramo final del recorrido del comensal en la mesa: construir y enviar el pedido (la comanda), abrir y pagar la cuenta (bill) y, tras el servicio, dejar una reseña. Todos estos endpoints son Router A (cara cliente) y se montan bajo /sessions/{session_token}: el session_token de la mesa abierta es la unidad de scope, no hay login de cliente obligatorio. El multitenancy por restaurant_id queda implícito: la sesión ya está atada a su mesa y restaurante, así que el cliente nunca envía restaurant_id en el body.

El flujo es: el cliente añade líneas al DRAFT y hace submit, la comanda recorre su máquina de estados (validación IA, aprobación del manager según order_approval_mode) y, cuando el servicio termina, se abre la cuenta sobre el ticket de la sesión y se cobra. La cuenta es idempotente (una sesión tiene como mucho una cuenta activa; reabrirla refresca totales) y los POST críticos —pagar la cuenta, disparar un curso (fire-next-course / courses/{type}/fire)— aceptan la cabecera Idempotency-Key para que un reintento reproduzca la primera respuesta en vez de cobrar o disparar dos veces. La validación IA y el cobro son fail-closed: ante un fallo del validador o de la pasarela se rechaza (HTTP 502 en pago), nunca se auto-aprueba.

Patrones a tener en cuenta

• Precios en céntimos (int): 12,50 € se representa como 1250.
• Submit bloqueado si la sesión está pausada (manager llamado): POST .../submit devuelve 409 y la comanda permanece en DRAFT.
• Tiempo real por SSE: el ciclo de vida de la comanda (batch_ai_result, batch_updated) y la confirmación de pago (PaymentConfirmed, publicado tras el commit) se propagan por el stream de eventos; ver eventos SSE.
• Errores mapeados a HTTP en el borde: 404 (sin cuenta/comanda activa), 409 (cuenta ya pagada, total desfasado, doble fire), 402 (importe mayor al pendiente), 422 (propina inválida).

Para el detalle del concepto y las transiciones de estado, ver Comanda y su ciclo de vida; para la cuenta, el split y la propina, Pago; y para el perfil del cliente y las reseñas post-servicio, Clientes y reseñas. Para una visión transversal de la API, ver la introducción de la 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-comanda-pago.md y regenera con python scripts/gen_openapi_reference.py.

Resumen de endpoints

Método	Ruta	Resumen	Auth
POST	/api/v1/orders/validate	Validate Order	Pública
DELETE	/api/v1/sessions/lines/{line_id}	Delete Line	Pública
PATCH	/api/v1/sessions/lines/{line_id}	Update Line Quantity	Pública
PATCH	/api/v1/sessions/lines/{line_id}/allergens	Set Line Allergens	Pública
GET	/api/v1/sessions/{session_token}/active-comanda	Get Active Comanda	Pública
GET	/api/v1/sessions/{session_token}/bill	Get Bill	Pública
PATCH	/api/v1/sessions/{session_token}/bill	Configure Bill	Pública
POST	/api/v1/sessions/{session_token}/bill	Request Bill	Pública
POST	/api/v1/sessions/{session_token}/bill/payments	Pay Bill	Pública
POST	/api/v1/sessions/{session_token}/cancel	Cancel Comanda	Pública
POST	/api/v1/sessions/{session_token}/courses/{course_type}/fire	Fire Course By Type	Pública
GET	/api/v1/sessions/{session_token}/draft	Get Draft	Pública
POST	/api/v1/sessions/{session_token}/lines	Add Line	Pública
GET	/api/v1/sessions/{session_token}/order-history	Get Order History	Pública
POST	/api/v1/sessions/{session_token}/revert-to-draft	Revert To Draft	Pública
POST	/api/v1/sessions/{session_token}/review	Submit Review	Pública
POST	/api/v1/sessions/{session_token}/submit	Submit For Review	Pública
GET	/api/v1/sessions/{session_token}/tab	Get Tab	Pública
PUT	/api/v1/sessions/{session_token}/tab/course-plan	Put Course Plan	Pública
POST	/api/v1/sessions/{session_token}/tab/fire-next-course	Fire Next Course	Pública
GET	/api/v1/sessions/{session_token}/ticket	Get Ticket	Pública

Detalle

POST /api/v1/orders/validate

Validate Order

Validate a draft order for the chatbot.

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

DELETE /api/v1/sessions/lines/{line_id}

Delete Line

Remove a line from the comanda; cancels the comanda if it becomes empty.

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

PATCH /api/v1/sessions/lines/{line_id}

Update Line Quantity

Update the quantity of a line in the session's draft comanda.

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

PATCH /api/v1/sessions/lines/{line_id}/allergens

Set Line Allergens

Set the diner-flagged allergens for a line in the session's draft comanda.

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

GET /api/v1/sessions/{session_token}/active-comanda

Get Active Comanda

Return the session's latest in-flight comanda, or 404 if there is none.

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

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

Get Bill

Return the active bill (with shares), or 404 if none.

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

PATCH /api/v1/sessions/{session_token}/bill

Configure Bill

Set the split mode and tip for the bill.

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

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

Request Bill

Open (or refresh) the bill for a session.

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

POST /api/v1/sessions/{session_token}/bill/payments

Pay Bill

Charge a payment against the bill.

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

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

Cancel Comanda

Cancel the comanda and notify the customer via chat and SSE.

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

POST /api/v1/sessions/{session_token}/courses/{course_type}/fire

Fire Course By Type

Fire a specific course by course_type.

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

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

Get Draft

Return the session's draft comanda, creating an empty one if none exists.

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

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

Add Line

Add a product line to the session's draft comanda.

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

GET /api/v1/sessions/{session_token}/order-history

Get Order History

Return all non-draft comandas for the session, oldest first.

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

POST /api/v1/sessions/{session_token}/revert-to-draft

Revert To Draft

Revert a rejected comanda back to DRAFT so the customer can edit it.

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

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

Submit Review

Submit the customer's star rating + optional comment for the session.

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

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

Submit For Review

Submit the draft comanda for AI validation and manager review.

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

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

Get Tab

Return the aggregated tab view for the session (RD01 §5 / RD03 Parte 2).

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

PUT /api/v1/sessions/{session_token}/tab/course-plan

Put Course Plan

Replace the per-session course plan.

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

POST /api/v1/sessions/{session_token}/tab/fire-next-course

Fire Next Course

Fire the next fireable course in the plan (lowest order_index, unfired).

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

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

Get Ticket

Return the aggregated ticket for the session's active comandas, or 404 if none.

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