Códigos de respuesta y error

Esta referencia describe los códigos de respuesta y error que usan las operaciones del TPV Integrado. Todas las operaciones devuelven al menos un Code numérico y un Message.

¿Qué son los códigos de respuesta y error?

Todas las operaciones del TPV Integrado devuelven una respuesta con un Code numérico (Int) y un Message (String).

Todos los valores que se listan a continuación se devuelven en el mismo campo Code. La categorización en “Códigos de respuesta” y “Códigos de error” existe solo para dar claridad a la documentación y crear agrupaciones lógicas.

Estructura de la respuesta

Todas las operaciones devuelven una respuesta estructurada que contiene como mínimo:

Campo	Tipo	Descripción
`Code`	String	Código de respuesta (consulta la tabla a continuación).
`Message`	String	Resultado legible por humanos.

Un código de respuesta 0 indica éxito.

Códigos de respuesta comunes

Código	Descripción
0	Operación ejecutada con éxito
1	Operación denegada
2	Operación cancelada por el usuario
3	Se encontró un error durante el procesamiento de la operación
4	Error desconocido: revisa los detalles del mensaje
5	TPV Integrado aún en estado WAITING_CONFIRMATION. Envía un comando Polling para iniciar.
6	Operación de cancelación ejecutada con éxito

Los códigos 2 y 6 se relacionan con la cancelación, pero significan cosas distintas. El código 2 (Operación cancelada por el usuario) lo devuelve un comando abortado: Sale, Refund o Pre-authorization. El código 6 (Operación de cancelación ejecutada con éxito) lo devuelve el propio comando Cancel. Ambos se aplican a los modos SDK (USB / HTTP) y Cloud2Cloud.

El código 5 indica que el terminal debe restablecer su conexión, por ejemplo después de un reinicio o de una caída del enlace. Ejecuta Polling de nuevo en el mismo Connector, reenvía los parámetros de configuración y reintenta el comando. Consulta Polling y reconexión.

Cuando Code es 3 para Sale, Refund, Pre-authorization o Shift, el campo Message es una cadena codificada en JSON que describe las validaciones fallidas. Consulta Errores de validación.

Códigos de error para el Modo TPV Integrado

Estos códigos aparecen normalmente en escenarios de activación, reconexión o pérdida de conexión.

La siguiente tabla lista todos los códigos de error definidos en el manual.

Código	Descripción
`1-500`	El terminal no pudo inicializar las dependencias necesarias para abrir el puerto serie.
`1-501`	Problema de conectividad al intentar configurar la conexión Wi-Fi. Verifica si el Wi-Fi está habilitado en el terminal.
`1-502`	Error al intentar abrir el puerto serie del terminal.
`1-503`	El usuario solicitó salir del Modo TPV Integrado.
`A-503`	La conexión Wi-Fi o USB finaliza de forma inesperada mientras la aplicación está escuchando comandos.
`A-504`	El usuario intenta salir del Modo TPV Integrado, pero la aplicación no pudo cerrar la comunicación.
`A-505`	Se detectó una desconexión de la interfaz y el Modo TPV Integrado se desconectó.
`G-XXXX`	Errores relacionados con el proveedor de integración en la nube, como G-Services.
`S-100`	Hubo un error interno en el TPV o una desconexión de la interfaz y la comunicación se interrumpió.

Para los códigos relacionados con la conexión (por ejemplo, A-503, A-504, A-505, S-100), sigue el flujo de reconexión descrito en los Conceptos básicos. No asumas que el Connector sigue siendo válido.

Códigos de estado de transacción

Se devuelven en el campo Status de una respuesta de CheckStatus. Describen el estado de una transacción pasada, no el resultado del propio comando CheckStatus; ese resultado está en Code.

Código de estado	Nombre del estado	Descripción
0	`APPROVED`	Transacción capturada. Se usa para ventas con tarjeta estándar y para QR Code con tarjeta.
1	`AUTHORIZED`	Transacción autorizada (preautorización o QR PCT).
2	`REFUNDED`	Transacción reembolsada (D+1).
3	`CANCELED`	Transacción cancelada (D+0).
4	`REVERSED`	Transacción revertida (deshecha).
5	`NOT_FOUND`	No se encontró ninguna transacción para el `CallerId` indicado.
6	`UNKNOWN`	Estado no mapeado.

Los métodos de pago con QR Code se comportan de forma distinta. Las transacciones QR PCT (Point of Capture) siempre devuelven AUTHORIZED y nunca APPROVED. QR Code con tarjeta sigue el mismo comportamiento que una venta con tarjeta estándar.

Pautas para el manejo de errores

Verifica siempre el Code de la respuesta antes de continuar (por ejemplo, 0 = éxito).
No reintentes operaciones a ciegas; revalida el estado del terminal con Polling después de un error.
Para el código 5, envía un comando Polling antes de continuar.
Para los errores relacionados con la conexión, sigue las instrucciones de reconexión de esta documentación.

Recursos relacionados

Polling y reconexión — cuándo hacer polling y cómo recuperarte.