Integraciones POS
La página de configuración Integraciones conecta un servidor de HandyCafe habilitado con un terminal Ödeal D2D. La disponibilidad se comprueba a través de HandyCafe Cloud. El menú y la página quedan completamente ocultos cuando el café no tiene permiso para usar Ödeal.
Antes de empezar
Necesitas una suscripción activa a HandyCafe Cloud, una clave de comercio de Ödeal y una clave secreta de Ödeal. También tienes que crear el terminal en el área Cihazlarım de Ödeal. El nombre exacto asignado a ese terminal es su externalDeviceKey. Empieza con el entorno Stage. Cambia a Producción solo después de que Ödeal haya aprobado las credenciales de producción y la configuración del callback.
Configurar Ödeal
- Abre Configuración y selecciona Integraciones.
- En Cuenta de Ödeal, escribe la clave de comercio y la clave secreta proporcionadas por Ödeal. HandyCafe envía estos valores directamente a HandyCafe Cloud. Se cifran y no se guardan en la base de datos local ni se vuelven a mostrar.
- Selecciona Prueba de conexión. Cuando hay claves nuevas, HandyCafe las guarda de forma segura antes de probar la conexión con la API de Ödeal. Esta prueba solo verifica la cuenta de Ödeal. No demuestra que el terminal esté emparejado ni en línea.
- Agrega el terminal. Escribe un nombre local claro para el dispositivo. En Nombre del dispositivo en Ödeal (externalDeviceKey), escribe el nombre exacto del dispositivo creado en Ödeal. Después indica el PaxID opcional, el entorno, el tiempo de espera del pago, la ciudad del cliente, el distrito del cliente, la tasa de IVA de la sesión y la tasa de IVA del pedido.
- Activa Integración POS activa y selecciona Guardar.
- Completa un recibo de efectivo en Stage y un pago con tarjeta en Stage para verificar el emparejamiento del terminal y las dos vías de liquidación.
En esta versión solo se admite un terminal Ödeal activo por servidor. Así se evita que un pago se dirija a un terminal no previsto antes de que exista un selector de terminal para el cajero.
HandyCafe guarda el inventario de terminales localmente antes de que Cloud verifique un nuevo par de credenciales. Que Ödeal rechace una credencial no descarta el nombre del terminal ni los campos de emparejamiento. Un terminal que necesita credenciales nuevas se guarda como inactivo hasta que esas credenciales se verifican para el entorno seleccionado.
La página Integraciones lee el inventario de terminales directamente de la base de datos SQLite local y lo muestra sin esperar a Cloud. Solo el estado de las credenciales cifradas y el permiso remoto del proveedor requieren una petición a Cloud.
Si Ödeal rechaza la configuración, HandyCafe muestra la explicación devuelta por Ödeal. Una respuesta de tipo perfil de organización no encontrado significa que el par de clave de comercio y clave secreta no pertenece a ninguna organización en el entorno Stage o Producción seleccionado.
Comportamiento de los pagos
Cuando el método de pago activo es efectivo o tarjeta, el cobro de una sesión de PC, el cobro de una sesión de consola y el cierre de un pedido independiente envían una cesta idempotente a Ödeal. El efectivo se envía como la opción de pago CASH documentada por Ödeal. El terminal registra el pago en efectivo e imprime el comprobante fiscal o el recibo de e-Archivo sin abrir una pantalla de cobro con tarjeta. La tarjeta se envía como CREDITCARD; HandyCafe espera el resultado del callback mientras el cliente completa el pago en el terminal. Un cobro que incluye efectivo y tarjeta envía las dos opciones de pago con sus importes respectivos.
El cliente puede elegir pagar a plazos en el terminal cuando la tarjeta y el contrato del comercio lo permiten. HandyCafe guarda el número de plazos informado junto con la venta local. La venta local solo se registra en firme después de que Ödeal confirme la transacción. Si ese registro local falla tras la confirmación, HandyCafe solicita una cancelación en el mismo día. Una cancelación fallida genera un error de conciliación manual y hay que revisarla en el informe de transacciones de Ödeal. Los métodos de pago distintos de efectivo y tarjeta continúan por el flujo de liquidación habitual de HandyCafe.
Pruebas y operaciones del terminal
Prueba de conexión solo verifica las credenciales de comercio de Ödeal y el acceso a la API. No imprime ningún recibo, no cobra a ninguna tarjeta y no demuestra que externalDeviceKey esté emparejado con el terminal.
La documentación de la API D2D facilitada no define endpoints separados de Imprimir recibo de prueba ni de Cobro de prueba. Las pruebas de aceptación usan cestas normales en el entorno Stage: envía una cesta de efectivo y comprueba el comprobante impreso; después envía una cesta de tarjeta y completa en el terminal una transacción de un solo pago o a plazos. Usa únicamente los datos de tarjetas de prueba de Stage proporcionados por Ödeal.
Los casos de aceptación de Ödeal incluyen el cierre de día y la reimpresión del último recibo. Ambas son operaciones del terminal. D2D no documenta llamadas remotas de API para ellas, así que HandyCafe no las expone como botones remotos.
Activación y desactivación remotas
Los administradores de HandyCafe controlan Ödeal desde Admin > Configuración de administración > Proveedores POS en el Panel de control. El interruptor global es el control maestro. Los valores predeterminados por país usan códigos ISO de dos letras como TR. Los controles por café pueden abrir o cerrar Ödeal explícitamente para una licencia. Una decisión específica del café prevalece sobre el valor predeterminado del país. Restablecer la decisión del café hace que ese café vuelva a seguir la configuración de su país.
El orden de decisión es el interruptor global, después la decisión específica del café y por último el valor predeterminado del país. Un interruptor global desactivado cierra Ödeal para todos los cafés. Un cierre explícito del café oculta la página aunque su país esté abierto. Una apertura explícita del café permite la página aunque su país no esté en la lista predeterminada. Desactivar el acceso bloquea de inmediato la creación de cestas nuevas. Las transacciones pendientes existentes se pueden seguir consultando o cancelando para que ningún pago en curso quede bloqueado.
El servidor comprueba la disponibilidad a través de HandyCafe Cloud y guarda en caché la última decisión de país o de café verificada correctamente. El catálogo de proveedores devuelve HTTP 200 con un error.code estructurado cuando su credencial no es válida. La aplicación de escritorio gestiona esa respuesta actualizando la credencial y reintentando. Un fallo temporal de autenticación o de red no reinterpreta como desactivada una decisión de administración que estaba activada, así que el menú Integraciones se mantiene estable. Una respuesta posterior correcta actualiza la caché de inmediato, incluida una decisión de administración de desactivar. Si no hay ninguna decisión verificada previamente, un país de café desconocido, una suscripción inactiva o un proveedor desactivado mantienen la página oculta. Las nuevas operaciones de Ödeal siempre las vuelve a autorizar Cloud, incluso cuando se usa la visibilidad guardada en caché. Cuando el perfil de café sincronizado no tiene país, se usa el país guardado en la licencia.
Seguridad y recuperación
Las credenciales de Ödeal se cifran en HandyCafe Cloud con la clave de bóveda del despliegue. Las peticiones de callback se autentican mediante la clave de petición configurada o mediante las cabeceras de comercio y secreto de Ödeal. Los códigos de referencia de cesta son estables para cada pedido o sesión. Repetir el mismo cobro no crea un segundo cargo.
La cancelación en Ödeal solo está disponible según las reglas de mismo día de Ödeal, antes de que se cierre el lote del terminal. Una cesta pendiente se puede eliminar por separado antes de que se complete el pago. Ödeal D2D no ofrece una operación general de reembolso. Usa el back office y el informe de transacciones de Ödeal cuando haya pasado la ventana de cancelación.
Ödeal D2D no ofrece una operación documentada de informe Z remoto ni de cierre de día. Completa el cierre de día en el terminal. HandyCafe puede leer informes de transacciones para la conciliación y registra los callbacks de payback de Ödeal.