[ADD] point_of_sale/payment_methods: add Glory cash machine doc

task-5158950

Support for Glory cash machines has been added to the POS in v19.0.
This commit adds documentation on how to configure both the machine
itself and the Odoo payment method.

This commit also adds a 'Cash machines' parent page, as we are planning
on supporting other models in the future.

closes #14834

Signed-off-by: Loredana Perazzo (lrpz) <lrpz@odoo.com>

Author: MaxTheWhale

content/applications/sales/point_of_sale/payment_methods.rst

@@ -6,8 +6,8 @@ Payment methods
 
 Configure a payment method with Odoo Point of Sale to provide customers with various payment
 options, including cash, card payments through a :ref:`configured payment terminal
-<pos/terminals/configuration>`, :doc:`online payments </applications/finance/payment_providers>`,
-or :doc:`customer accounts <payment_methods/customer_credit>`.
+<pos/terminals/configuration>`, :doc:`online payments <../../finance/payment_providers>`, or
+:doc:`customer accounts <payment_methods/customer_credit>`.
 
 To create a payment method, go to :menuselection:`Point of Sale --> Configuration --> Payment
 Methods`, click :guilabel:`New`, and follow the next steps:
@@ -16,12 +16,12 @@ Methods`, click :guilabel:`New`, and follow the next steps:
 #. Enable the following options if needed:
 
    - :guilabel:`Online Payment`: To link the payment method to a :doc:`payment provider
-     </applications/finance/payment_providers>` and enable online payments, select a provider in
+     <../../finance/payment_providers>` and enable online payments, select a provider in
      the :guilabel:`Allowed Providers` field or click :icon:`fa-arrow-right` :guilabel:`Payment
      Providers` to install one.
    - :guilabel:`Identify Customer`: Force the selection of a customer during the payment.
-#. Select the preferred :doc:`Journal </applications/finance/accounting/get_started/journals>` to
-   record all transactions.
+#. Select the preferred :doc:`Journal <../../finance/accounting/get_started/journals>` to record all
+   transactions.
 #. Select the appropriate :guilabel:`Point of Sale` to enable the payment method.
 #. Set the :guilabel:`Integration` field to one of the following options:
 
@@ -30,16 +30,17 @@ Methods`, click :guilabel:`New`, and follow the next steps:
      payments.
    - :guilabel:`Bank App (QR Code)`: Add at least one :ref:`bank account
      <accounting/journals/bank>` to the journal to enable :doc:`QR code payments
-     </applications/sales/point_of_sale/payment_methods/qr_code_payment>` with a bank app. Select a
-     :guilabel:`QR Code Format` in the form.
-   - :guilabel:`Cash Machine (Glory)`: Connect a **Glory** cash machine to automate the point of
-     sale's cash transactions.
+     <payment_methods/qr_code_payment>` with a bank app. Select a :guilabel:`QR Code Format` in the
+     form.
+   - :guilabel:`Cash Machine (Glory)`: Connect a :doc:`Glory <payment_methods/cash_machines/glory>`
+     :doc:`cash machine <payment_methods/cash_machines>` to automate the point of sale's cash
+     transactions.
 #. Save.
 
 .. note::
    - The :guilabel:`Delivery Payment` option links a payment method to online orders placed through
-     :doc:`Urban Piper </applications/sales/point_of_sale/online_food_delivery>`. Select the
-     appropriate :guilabel:`Delivery Provider` to associate with the payment method.
+     :doc:`Urban Piper <online_food_delivery>`. Select the appropriate :guilabel:`Delivery Provider`
+     to associate with the payment method.
    - If the Accounting app is installed, use the :guilabel:`Intermediary Account` field, if needed,
      to record transactions for this payment method in a specific receivable account for
      better traceability. Leave the field empty to use the company's default :ref:`receivable
@@ -55,10 +56,12 @@ Methods`, click :guilabel:`New`, and follow the next steps:
 .. seealso::
    - `Payment methods (video tutorial) <https://www.youtube.com/watch?v=eHr4tS8Wmss>`_
    - :doc:`payment_methods/terminals`
+   - :doc:`payment_methods/cash_machines`
 
 .. toctree::
    :titlesonly:
 
+   payment_methods/cash_machines
    payment_methods/customer_credit
    payment_methods/qr_code_payment
    payment_methods/terminals

content/applications/sales/point_of_sale/payment_methods/cash_machines.rst

@@ -0,0 +1,39 @@
+:show-content:
+
+=============
+Cash machines
+=============
+
+Connecting and integrating a cash machine with a :ref:`POS system <pos/session-start>` enables
+automation of cash transactions, cash counting, and change return.
+
+.. _pos/cash_machines/configuration:
+
+Configuration
+=============
+
+Configure the cash machine itself before setting it up in Odoo. Currently, Odoo supports :doc:`Glory
+<cash_machines/glory>` cash machines. Once the cash machine is fully set up:
+
+#. Create the associated :doc:`payment method <../payment_methods>`.
+#. Select the POS in the :guilabel:`Point of Sale` field.
+
+.. _pos/terminals/cash-machine-use:
+
+Use
+===
+
+To process a :ref:`payment <pos/sell>` with a :ref:`configured cash machine
+<pos/cash_machines/configuration>`, select the machine's :doc:`payment method <../payment_methods>`
+on the **payment screen**, then follow the instructions on the machine.
+
+Once the transaction is successful, the payment is automatically validated in Point of Sale.
+
+.. note::
+   - Connection issues between Odoo and the cash machine result in transaction cancellation.
+   - To cancel the payment request, click :guilabel:`Cancel`.
+
+.. toctree::
+   :titlesonly:
+
+   cash_machines/glory

content/applications/sales/point_of_sale/payment_methods/cash_machines/glory.rst

@@ -0,0 +1,130 @@
+=====
+Glory
+=====
+
+**Glory** :doc:`cash machines <../cash_machines>` enable the automation of cash transactions.
+
+.. note::
+   - The integration with the Glory cash machine only supports basic functions, such as cash
+     transactions and cash count checks.
+   - Tasks like filling and emptying the machine must be performed directly through the cash machine
+     interface.
+
+.. _pos/glory/configuration:
+
+Configuration
+=============
+
+Cash machine settings
+---------------------
+
+#. Power on the cash machine, which briefly displays its IP address at the bottom of the screen.
+   Note it down for later.
+
+   .. note::
+      The IP address should be formatted as `###.###.#.##` (e.g., `192.168.0.25`).
+
+#. Navigate to the cash machine's homepage by entering its IP address as the URL in `HTTPS` (e.g.,
+   `https://192.168.0.25`), and log in with your Glory credentials.
+#. As long as the certificate is not imported, a warning page appears when trying to access the
+   machine's homepage. Bypass it by clicking :guilabel:`Advanced` and then :guilabel:`Proceed to
+   [IP address] (unsafe)`.
+#. From the Glory homepage, go to :guilabel:`Host Configuration` and ensure the :guilabel:`Network`
+   setting is set to :guilabel:`MANUAL`, meaning the IP address is static.
+#. Then, navigate to :guilabel:`SSL Configuration` and scroll down to the :guilabel:`HTTPS Server
+   Setting` section.
+
+   #. In parallel, open the terminal and verify that *OpenSSL* is installed. Type `openssl` and
+      press enter. If installed, this command displays a `help` menu listing all available OpenSSL
+      commands. If nothing happens, `install it <https://openssl-library.org/source/>`_.
+   #. Then, paste the following command and press `Enter` to generate and download the certificate
+      and private key. Ensure that you replace the demo IP address with the cash machine’s actual IP
+      address.
+
+      .. code-block:: bash
+
+         openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 3650 -nodes -subj "/CN=192.168.0.25" -addext "subjectAltName = IP:192.168.0.25"
+
+      .. important::
+         The self-signed SSL certificate and key pair must use the same static IP address as the
+         cash machine.
+
+#. Once the files are generated, from the :guilabel:`HTTPS Server Setting` section, upload
+   `cert.pem` as the :guilabel:`Certificate` and `key.pem` as the :guilabel:`Private Key`.
+#. Go to :guilabel:`WebApp Configuration` and ensure the :guilabel:`Interface` setting from the
+   :guilabel:`A: Nodejs Setting` section is set to :guilabel:`Enable`.
+#. Then, adjust the following settings depending on the POS setup:
+
+   - If **multiple POS** are connected to the same cash machine, go to :guilabel:`App
+     Configuration`, scroll down to the :guilabel:`SOAP IF Setting`, and ensure :guilabel:`Session
+     mode` and :guilabel:`Occupy mode` are both set to :guilabel:`Enable`.
+   - If **a dedicated user** has been set up on the cash machine for Odoo, go to :guilabel:`App
+     Configuration`, scroll down to the :guilabel:`SOAP IF Setting` section, and :guilabel:`Enable`
+     the :guilabel:`User check` setting.
+#. Restart the cash machine to apply the new settings.
+
+.. note::
+   As this setup is complex and may involve advanced knowledge of Glory hardware, it is advisable to
+   consult the Glory integration partner for configuration if there is any uncertainty.
+
+Import self-signed certificates
+-------------------------------
+
+For a long-term solution, the generated certificates must be imported into the device running the
+POS. The import process is heavily dependent on the :abbr:`OS (Operating System)` and the browser.
+
+.. tabs::
+
+   .. tab:: Windows OS
+
+      Windows manages certificates, which means that self-signed certificates must be imported
+      from the certification files rather than the browser. To do so,
+
+      #. Open the Windows File Explorer and locate the downloaded certification files.
+      #. Right-click on the certification files and select :guilabel:`Install Certificate`.
+      #. Specify the certificate location and select the installation scope: either the
+         :guilabel:`Current User` only or all users (:guilabel:`Local Machine`). Then, click
+         :guilabel:`Next`.
+      #. On the `Certificate Store` screen, tick :guilabel:`Place all certificates in the following
+         store`, click :guilabel:`Browse...`, and select :guilabel:`Trusted Root Certification
+         Authorities`.
+      #. Click :guilabel:`Finish` and accept the pop-up security window.
+      #. Restart the computer to make sure that the changes are applied.
+
+   .. tab:: Linux OS
+
+      When using **Google Chrome**,
+
+      #. Open the web browser.
+      #. Navigate to :menuselection:`Settings --> Privacy and security --> Security --> Manage
+         certificates`.
+      #. Go to the :guilabel:`Authorities` tab, click :guilabel:`Import`, and select the exported
+         certification files.
+      #. Accept all warnings and click :guilabel:`ok`.
+      #. Restart the web browser.
+
+      When using **Mozilla Firefox**,
+
+      #. Open the web browser.
+      #. Navigate to :menuselection:`Settings --> Privacy & Security --> Security --> View
+         Certificates... --> Import`.
+      #. Select the exported certification files.
+      #. Tick the checkboxes and validate.
+      #. Restart the web browser.
+
+Payment method
+--------------
+
+#. :ref:`Install <general/install>` the POS Glory Cash Machines module.
+#. :doc:`Associate a cash payment method <../../payment_methods>`:
+
+   - Go to :menuselection:`Point of Sale --> Configuration --> Payment Methods`. Create a new
+     :guilabel:`Cash` payment method or update an existing payment method.
+   - Select the associated POS in the :guilabel:`Point of Sale` field.
+   - Select :guilabel:`Cash Machine (Glory)` in the :guilabel:`Integration` field.
+   - Fill in the :guilabel:`Cash Machine IP` field with the IP address of the cash machine.
+   - If the cash machine was configured to use :guilabel:`User check` in the previous section, fill
+     in the :guilabel:`Cash Machine Username` and :guilabel:`Cash Machine Password`.
+
+.. seealso::
+   :doc:`../../payment_methods`