summaryrefslogtreecommitdiff
path: root/taler-merchant-pos-terminal.rst
blob: 356838fdcd6a07c588c5ac38995d1af319e0b133 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
..
  This file is part of GNU TALER.
  Copyright (C) 2014-2018 Taler Systems SA

  TALER is free software; you can redistribute it and/or modify it under the
  terms of the GNU Affero General Public License as published by the Free Software
  Foundation; either version 2.1, or (at your option) any later version.

  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.

  You should have received a copy of the GNU Affero General Public License along with
  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>

  @author Torsten Grote

GNU Taler Merchant POS Manual
#############################

The GNU Taler merchant POS (point of sale) terminal allows sellers to

* process customers' orders by adding or removing products
* calculate the amount owed by the customer
* let the customer make a Taler payment via QR code or NFC

Android App
===========

.. note::
    The Android app is currently optimized for tablet devices, not phones.

At first start, the Android app asks you for a configuration URL
and a user name as well as a password for HTTP basic authentication.

At every start of the app,
it uses the saved configuration data
to fetch the current configuration (defined below)
and populates the currency, the products and their categories.

The Tabled UI is separated into three columns:

* Right: Product categories that the user can select to show different products.
* Middle: Products available in the selected category and their prices.
* Left: The current order, the ordered products, their quantity and prices
  as well as the total amount.

At the bottom of the main UI there is a row of buttons:

* Restart: Clears the current order and turns into an Undo button which restores the order.
* -1/+1: Available when ordered items are selected
  and allows you to increment/decrement their quantity.
* Prev: Goes to the previous order (if available).
* Next: Goes to the next order or creates a new one
  if the current is not empty and there is no next.
* Complete: Finalize an order and prompt the customer to pay.

The top left corner features a hamburger icon.
Clicking this opens a menu with these items:

* Orders: Show current open orders.
* History: Shows the payment history.
* Settings: Allows you to change the app configuration settings (URL and username/password)
  and to forget the password (for locking the app).

Testing nightly builds
----------------------

Every change to the app's source code triggers an automatic build
that gets published in a F-Droid repository.
If you don't have it already, download the `F-Droid app <https://f-droid.org/>`_
and then click the following link (on your phone) to add the nightly repository.

    `GNU Taler Nightly F-Droid Repository <fdroidrepos://gnu-taler.gitlab.io/fdroid-repo-nightly/fdroid/repo?fingerprint=55F8A24F97FAB7B0960016AF393B7E57E7A0B13C2D2D36BAC50E1205923A7843>`_

.. note::
    Nightly apps can be installed alongside official releases
    and thus are meant **only for testing purposes**.
    Use at your own risk!

While not recommended, APKs can also be
`downloaded directly <https://gitlab.com/gnu-taler/fdroid-repo-nightly/-/tree/master/fdroid%2Frepo>`__.

Building from source
--------------------

Import in and build with Android Studio or run on the command line:

.. code-block:: console

  $ git clone https://git.taler.net/merchant-terminal-android.git
  $ cd merchant-terminal-android
  $ ./gradlew assembleRelease

If you do not have the proprietary Android SDK installed,
see the :doc:`taler-developer-manual`
for :ref:`build instructions using free SDK rebuilds <Build-apps-from-source>`.

APIs and Data Formats
=====================

The GNU Taler merchant POS configuration is a single JSON file with the following structure.


  .. ts:def:: MerchantConfiguration

    interface MerchantConfiguration {
      // Configuration for how to connect to the backend instance.
      config: BackendConfiguration;

      // The available product categories
      categories: MerchantCategory[];

      // Products offered by the merchant (similar to `Product`).
      products: MerchantProduct[];

      // Map from labels to locations
      locations: { [label: string]: [location: Location], ... };
    }

The elements of the JSON file are defined as follows:

  .. ts:def:: BackendConfiguration

    interface BackendConfiguration {
      // The URL to the Taler Merchant Backend
      base_url: string;

      // The name of backend instance to be used (see `Backend Options <Backend-options>`)
      instance: string;

      // The API key used for authentication
      api_key: string;
    }

  .. ts:def:: MerchantCategory

    interface MerchantCategory {
      // A unique numeric ID of the category
      id: number;

      // The name of the category. This will be shown to users and used in the order summary.
      name: string;

      // Map from IETF BCP 47 language tags to localized names
      name_i18n?: { [lang_tag: string]: string };
    }


  .. ts:def:: MerchantProduct

    interface MerchantProduct {
      // A merchant-internal unique identifier for the product
      product_id?: string;

      // Human-readable product description
      // that will be shown to the user and used in contract terms
      description: string;

      // Map from IETF BCP 47 language tags to localized descriptions
      description_i18n?: { [lang_tag: string]: string };

      // The price of the product
      price: Amount;

      // An optional base64-encoded product image
      image?: ImageDataUrl;

      // A list of category IDs this product belongs to.
      // Typically, a product only belongs to one category, but more than one is supported.
      categories: number[];

      // Where to deliver this product. This may be an URL for online delivery
      // (i.e. 'http://example.com/download' or 'mailto:customer@example.com'),
      // or a location label defined inside the configuration's 'locations'.
      delivery_location: string;
    }