taler-docs

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

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

      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 
     30 Android App
     31 ===========
     32 
     33 .. note::
     34     The Android app is currently optimized for tablet devices, not phones.
     35 
     36 At first start, the Android app asks you for a configuration URL
     37 and a user name as well as a password for HTTP basic authentication.
     38 
     39 At every start of the app,
     40 it uses the saved configuration data
     41 to fetch the current configuration (defined below)
     42 and populates the currency, the products and their categories.
     43 
     44 The Tabled UI is separated into three columns:
     45 
     46 * Right: Product categories that the user can select to show different products.
     47 * Middle: Products available in the selected category and their prices.
     48 * Left: The current order, the ordered products, their quantity and prices
     49   as well as the total amount.
     50 
     51 At the bottom of the main UI there is a row of buttons:
     52 
     53 * Restart: Clears the current order and turns into an Undo button which restores the order.
     54 * -1/+1: Available when ordered items are selected
     55   and allows you to increment/decrement their quantity.
     56 * Prev: Goes to the previous order (if available).
     57 * Next: Goes to the next order or creates a new one
     58   if the current is not empty and there is no next.
     59 * Data entry: Enter a product name and price manually.
     60 * Complete: Finalize an order and prompt the customer to pay.
     61 
     62 The top left corner features a hamburger icon.
     63 Clicking this opens a menu with these items:
     64 
     65 * Orders: Show current open orders.
     66 * History: Shows the payment history.
     67 * Settings: Allows you to change the app configuration settings (URL and username/password)
     68   and to forget the password (for locking the app).
     69 
     70 
     71 APIs and Data Formats
     72 =====================
     73 
     74 The GNU Taler merchant POS configuration is a single JSON file with the following structure.
     75 
     76 
     77 .. ts:def:: MerchantConfiguration
     78 
     79   interface MerchantConfiguration {
     80     // Configuration for how to connect to the backend instance.
     81     config: BackendConfiguration;
     82 
     83     // The available product categories
     84     categories: MerchantCategory[];
     85 
     86     // Products offered by the merchant (similar to `ProductSold`).
     87     products: MerchantProduct[];
     88 
     89     // Map from labels to locations
     90     locations: { [label: string]: [location: Location], ... };
     91   }
     92 
     93 The elements of the JSON file are defined as follows:
     94 
     95 .. ts:def:: BackendConfiguration
     96 
     97   interface BackendConfiguration {
     98     // The URL to the Taler Merchant Backend (including instance if applicable)
     99     base_url: string;
    100 
    101     // The API key used for authentication
    102     api_key: string;
    103   }
    104 
    105 
    106 .. ts:def:: MerchantProduct
    107 
    108   interface MerchantProduct {
    109     // A merchant-internal unique identifier for the product
    110     product_id?: string;
    111 
    112     // Human-readable product description
    113     // that will be shown to the user and used in contract terms
    114     description: string;
    115 
    116     // Map from IETF BCP 47 language tags to localized descriptions
    117     description_i18n?: { [lang_tag: string]: string };
    118 
    119     // The price of the product
    120     price: Amount;
    121 
    122     // An optional base64-encoded product image
    123     image?: ImageDataUrl;
    124 
    125     // A list of category IDs this product belongs to.
    126     // Typically, a product only belongs to one category, but more than one is supported.
    127     categories: number[];
    128 
    129     // Where to deliver this product. This may be an URL for online delivery
    130     // (i.e. 'http://example.com/download' or 'mailto:customer@example.com'),
    131     // or a location label defined inside the configuration's 'locations'.
    132     delivery_location: string;
    133   }