Business - Articles
===================
.. Last update: 04/04/2022

If the account type for this installation is "prepaid", users can buy articles (such as
minute/trip packages) to top-up their balance.

The base url for the APIs in this page is at::

  /api/business-mobile/

A JSON file with OpenAPI data about all business-related mobile APIs can be downloaded :download:`here </openapi/srv-business-base/api-src-WebMobile.json>`.

List available articles
-----------------------

.. openapi:: /openapi/srv-business-base/api-src-WebMobile.json
   :paths:
     /v1/articles/list

If there is an error the response will be negative without any further indications.

If positive, ``Data`` will be::

  [
    {
      Id: 7,                                                                 // Int
      CreatedDate: "2001-01-01T01:01:01Z",                                   // DateTime
      BalanceUnit: 1,                                                        // enum
      ExtCommunityFilter: [ Guid array ],                                    // Guid Array
      SelectedCommunities: "...",                                            // String
      Name: "60 Minutes Package",                                            // String
      Labels: "{\"en\":\"60 Minutes Package\"}",                             // JSON Dictionary
      DescriptionLabels: "{\"en\":\"Package 60\",\"it\":\"Pacchetto 60\"}",  // JSON Dictionary
      WalletAmount: 60,                                                     // Decimal
      Price: 10,                                                             // Decimal
      DeletionDate: null                                                     // DateTime (nullable)
    },
    ...
  ]

``BalanceUnit`` can be one of the :ref:`enum-balanceunit` enumeration.

Buying one of this article will increase the wallet with the specified ``BalanceUnit``
of ``WalletAmount`` items.

Buy an article
--------------
Allow the user to buy a package to refill its wallet

.. openapi:: /openapi/srv-business-base/api-src-WebMobile.json
   :paths:
     /v1/articles/buy

The API will accept a JsonBody with the following format::

  {
    ArticleId: 5,          // Int
    Quantity: 1,           // Int
    PaymentMethodId: 3,    // Int (nullable)
    BalanceUnit: 0         // Int
  }
  
where the value of the ``BalanceUnit`` property can be either Token or Currency from the :ref:`enum-balanceunit` enumeration.

If the ``BalanceUnit`` property is set to token, ``PaymentMethodId`` will be mandatory and will refer to the user's payment method
to be used to pay via gateway.

The API will respond with a play error response if either the article was not found or the user is trying to pay in token for a
token package, or with one of the following erorrs:

``err_ArticleNotSet``
  No ArticleId has been provided

``err_QuantityNotSet``
  No Quantity has been provided or has been set to zero
 
``err_BalanceUnitNotSet``
  No BalanceUnit has been provided
  
``err_NotEnoughToken``
  No wallet has been found on the user to pay in tokens or the token balance
  of the wallet is less than the total cost to be payed