taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

taler-merchant-pos-terminal.rst (4633B)

      1 ..
      2   This file is part of GNU TALER.
      3   Copyright (C) 2014-2018 Taler Systems SA
      4 
      5   TALER is free software; you can redistribute it and/or modify it under the
      6   terms of the GNU Affero General Public License as published by the Free Software
      7   Foundation; either version 2.1, or (at your option) any later version.
      8 
      9   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
     10   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
     11   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
     12 
     13   You should have received a copy of the GNU Affero General Public License along with
     14   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
     15 
     16   @author Torsten Grote
     17 
     18 .. _taler-merchant-pos-app:
     19 
     20 Merchant Point of Sale App Manual
     21 #################################
     22 
     23 The GNU Taler merchant point of sale (POS) App allows sellers to
     24 
     25 * process customers' orders by adding or removing products
     26 * calculate the amount owed by the customer
     27 * let the customer make a Taler payment via QR code or NFC
     28 
     29 .. contents:: Table of Contents
     30   :depth: 1
     31   :local:
     32 
     33 
     34 Android App
     35 ===========
     36 
     37 .. note::
     38     The Android app is currently optimized for tablet devices, not phones.
     39 
     40 At first start, the Android app asks you for a configuration URL
     41 and a user name as well as a password for HTTP basic authentication.
     42 
     43 At every start of the app,
     44 it uses the saved configuration data
     45 to fetch the current configuration (defined below)
     46 and populates the currency, the products and their categories.
     47 
     48 The Tabled UI is separated into three columns:
     49 
     50 * Right: Product categories that the user can select to show different products.
     51 * Middle: Products available in the selected category and their prices.
     52 * Left: The current order, the ordered products, their quantity and prices
     53   as well as the total amount.
     54 
     55 At the bottom of the main UI there is a row of buttons:
     56 
     57 * Restart: Clears the current order and turns into an Undo button which restores the order.
     58 * -1/+1: Available when ordered items are selected
     59   and allows you to increment/decrement their quantity.
     60 * Prev: Goes to the previous order (if available).
     61 * Next: Goes to the next order or creates a new one
     62   if the current is not empty and there is no next.
     63 * Data entry: Enter a product name and price manually.
     64 * Complete: Finalize an order and prompt the customer to pay.
     65 
     66 The top left corner features a hamburger icon.
     67 Clicking this opens a menu with these items:
     68 
     69 * Orders: Show current open orders.
     70 * History: Shows the payment history.
     71 * Settings: Allows you to change the app configuration settings (URL and username/password)
     72   and to forget the password (for locking the app).
     73 
     74 
     75 APIs and Data Formats
     76 =====================
     77 
     78 The GNU Taler merchant POS configuration is a single JSON file with the following structure.
     79 
     80 
     81   .. ts:def:: MerchantConfiguration
     82 
     83     interface MerchantConfiguration {
     84       // Configuration for how to connect to the backend instance.
     85       config: BackendConfiguration;
     86 
     87       // The available product categories
     88       categories: MerchantCategory[];
     89 
     90       // Products offered by the merchant (similar to `Product`).
     91       products: MerchantProduct[];
     92 
     93       // Map from labels to locations
     94       locations: { [label: string]: [location: Location], ... };
     95     }
     96 
     97 The elements of the JSON file are defined as follows:
     98 
     99   .. ts:def:: BackendConfiguration
    100 
    101     interface BackendConfiguration {
    102       // The URL to the Taler Merchant Backend (including instance if applicable)
    103       base_url: string;
    104 
    105       // The API key used for authentication
    106       api_key: string;
    107     }
    108 
    109 
    110   .. ts:def:: MerchantProduct
    111 
    112     interface MerchantProduct {
    113       // A merchant-internal unique identifier for the product
    114       product_id?: string;
    115 
    116       // Human-readable product description
    117       // that will be shown to the user and used in contract terms
    118       description: string;
    119 
    120       // Map from IETF BCP 47 language tags to localized descriptions
    121       description_i18n?: { [lang_tag: string]: string };
    122 
    123       // The price of the product
    124       price: Amount;
    125 
    126       // An optional base64-encoded product image
    127       image?: ImageDataUrl;
    128 
    129       // A list of category IDs this product belongs to.
    130       // Typically, a product only belongs to one category, but more than one is supported.
    131       categories: number[];
    132 
    133       // Where to deliver this product. This may be an URL for online delivery
    134       // (i.e. 'http://example.com/download' or 'mailto:customer@example.com'),
    135       // or a location label defined inside the configuration's 'locations'.
    136       delivery_location: string;
    137     }