Marcar operación fallida
Registra que una operación de pago del TPV no se ha completado correctamente. La operación pasa a `status: "failed"`, conserva el mensaje de error cuando existe y no crea un cobro ni cambia el estado del ticket.
En este artículo
Usa esta guía cuando una operación de pago del TPV debe quedar registrada como fallida porque el cobro no se ha completado.
En Marea Gran Via, la acción actualiza una `tpv_payment_operation` existente: el backend registra `failed_at` si todavía no existía y guarda el `error_message` enviado por la pantalla o por el adaptador local.
Este flujo deja trazabilidad operativa del fallo. No sustituye a una cancelación externa y no marca el ticket como pagado.
Antes de empezar
- Sesión iniciada en Grupo Marea Demo y en la ubicación Marea Gran Via.
- Permiso de ubicación `tpv:use` para abrir y operar las pantallas del TPV.
- Una `tpv_payment_operation` existente en la misma ubicación y visible para el ticket o terminal seleccionado.
- Para la pantalla de cobro, abrir el ticket indicado por `TPV_TICKET_ID`. Para el panel principal, debe existir un servicio TPV activo y una operación accionable para `TPV_TERMINAL_ID` o sin terminal asignado.
- Si se usa el TPV principal, Marta Ruiz debe estar seleccionada como empleada del TPV cuando la pantalla lo solicite.
Instrucciones
- 1.
Abre la operación de pago
Entra en la pantalla avanzada de cobro del ticket o abre el TPV principal. En cobro avanzado, revisa la sección Pagos. En el TPV principal, abre Más acciones del TPV y después Operaciones de pago del terminal.
- 2.
Comprueba que se puede accionar
Verifica que la operación pertenece al ticket o al servicio activo y que encaja con el terminal seleccionado. Si ya está completada o cancelada, la UI no muestra acciones. En el panel principal tampoco aparecen operaciones con `execution_mode` `manual` o `backend_api`.
- 3.
Marca la operación como fallida
Pulsa Marcar fallida en la pantalla de cobro o Fallida en el panel del terminal. La pantalla envía `status: "failed"`, el terminal activo, el terminal reclamante si aplica y un mensaje manual de error.
- 4.
Revisa el resultado
Espera a que se actualice la lista. La operación debe aparecer como `failed` o Fallida y mostrar el mensaje de error cuando la pantalla lo exponga. Si `failed_at` estaba vacío, el backend lo registra en UTC.
- 5.
Entiende el efecto operativo
La acción no crea `ticket_payment`, `ticket_payment_allocation` ni `tpv_output_job`. El ticket no queda pagado y, si hace falta cobrar de nuevo, se debe usar una nueva operación o el flujo de pago correspondiente.
- 6.
Reconoce fallos automáticos
Si el adaptador local o el bridge HTTP informan un error, el sistema puede usar la misma actualización para dejar la operación en fallida. Para el operador, el resultado esperado es el mismo: estado fallido y mensaje de error cuando exista.
Validaciones y límites
- El botón solo es operable si la operación aparece dentro del alcance del terminal seleccionado o sin terminal asignado según el caso.
- El endpoint de actualización es `PUT /api/app/{orgId}/{locationId}/tpv-payment-operations/{operationId}` y el `operationId` efectivo sale de la ruta.
- El estado se normaliza y debe ser uno de `pending`, `claimed`, `requires_action`, `completed`, `failed` o `cancelled`.
- Si se envía `terminal_id`, debe pertenecer a la ubicación o resolver como terminal válido para actuar en ella.
- El backend no exige `error_message`; las pantallas manuales sí envían un mensaje por defecto.
- Repetir la acción sobre una operación ya fallida no sobrescribe `failed_at`, pero puede actualizar `error_message` y otros campos mutables.
- Marcar como fallida no invoca el adaptador de cancelación local ni recalcula importes pendientes del ticket.
Resultado esperado
La operación queda persistida como `failed`, con `failed_at` registrado por backend si faltaba y con `error_message` cuando se envió. No se registra cobro, no se paga el ticket y no se crea trabajo de salida.