diff --git a/doc/webservices/iap.rst b/doc/webservices/iap.rst index 23467c267c3..003fe2cf07f 100644 --- a/doc/webservices/iap.rst +++ b/doc/webservices/iap.rst @@ -81,8 +81,11 @@ Overview The Credits +.. note:: The credits went from integer to float value starting **October 2018** + Integer values are still supported. + Every service provided through the In-App platform can be used by the - clients with tokens or *credits*. The credits are an integer unit and + clients with tokens or *credits*. The credits are an float unit and their monetary value depends on the service and is decided by the provider. This could be: @@ -157,7 +160,8 @@ The first step is to register your service on the IAP endpoint (production and/or test) before you can actually query user accounts. To create a service, go to your *Portal Account* on the IAP endpoint (https://iap.odoo.com for production, https://iap-sandbox.odoo.com for testing, the endpoints are -*independent* and *not synchronized*). +*independent* and *not synchronized*). Alternatively, you can go to your portal +on Odoo (https://iap.odoo.com/my/home) and select *In-App Services*. .. note:: @@ -166,33 +170,45 @@ production, https://iap-sandbox.odoo.com for testing, the endpoints are on sandbox to ease the tests. Log in then go to :menuselection:`My Account --> Your In-App Services`, click -Create and provide the name of your service. +Create and provide the informations of your service. -The now created service has *two* important fields: +The service has *four* important fields: * :samp:`name` - :class:`ServiceName`: this will identify your service in the - client's :ref:`app ` communicates directly with IAP. -* :samp:`key` - :class:`ServiceKey`: the developer key that identifies you in - IAP (see :ref:`your service `) and allows to draw credits from - the client's account. - + client's :ref:`app ` communicates directly with IAP, choose it + carefully! .. warning:: The :class:`ServiceName` is unique and should usually match the name of your - Odoo App. + Odoo Client App. +* :samp:`Icon` - :class:`Icon`: A generic icon that will serve as default for your + :ref:`packages ` + +* :samp:`key` - :class:`ServiceKey`: the developer key that identifies you in + IAP (see :ref:`your service `) and allows to draw credits from + the client's account. It will be shown only once upon creation of the service + and can be regenerated at will. .. danger:: Your :class:`ServiceKey` *is a secret*, leaking your service key allows other application developers to draw credits bought for your service(s). -.. image:: images/service_select.png +* :samp:`privacy policy` - :class:`PrivacyPolicy`: This is an url to the privacy + policy of your service. This should explicitly mention the **information you collect**, + How you **use it, its relevance** to make your service work and inform the + client on how they can **access, update or delete their personal information**. + +.. image:: images/menu.png :align: center -.. image:: images/service_create.png +.. image:: images/service_list.png :align: center -.. image:: images/service_packs.png +.. image:: images/creating_service.png + :align: center + +.. image:: images/service_created.png :align: center You can then create *credit packs* which clients can purchase in order to @@ -203,9 +219,10 @@ use your service. Packages -------- -The credit packages are essentially a product with 4 characteristics. +The credit packages are essentially a product with 5 characteristics. * Name: the name of the package, +* Icon: A specific icon for the package. If not provided, it will fallback on the service icon * Description: details on the package that will appear on the shop page as well as the invoice, * Credits: the amount of credits the client is entitled to when buying the package, @@ -362,7 +379,6 @@ parameters we can use to make things clearer to the end-user: .. patch:: - .. TODO:: how do you test your service? JSON-RPC2_ Transaction API @@ -394,13 +410,13 @@ Authorize :param ServiceKey key: :param UserToken account_token: - :param int credit: + :param float credit: :param str description: optional, helps users identify the reason for charges on their accounts. :returns: :class:`TransactionToken` if the authorization succeeded. :raises: :class:`~odoo.exceptions.AccessError` if the service token is invalid :raises: :class:`~odoo.addons.iap.models.iap.InsufficientCreditError` if the account does - :raises: ``TypeError`` if the ``credit`` value is not an integer + :raises: ``TypeError`` if the ``credit`` value is not an integer or a float .. code-block:: python @@ -434,7 +450,7 @@ Capture :param TransactionToken token: :param ServiceKey key: - :param int credit_to_capture: (new - 15 Jan 2018) optional parameter to capture a smaller amount of credits than authorized + :param float credit_to_capture: (new - 15 Jan 2018) optional parameter to capture a smaller amount of credits than authorized :raises: :class:`~odoo.exceptions.AccessError` .. code-block:: python @@ -534,6 +550,33 @@ care how they are implemented Raised by any unexpeted behaviour at the discretion of the App developer (*you*). + +Test the API +------------ + +In order to test the developped app, we propose a sandbox platform that allows you to: + +1. Test the whole flow from the client's point of view - Actual services and transactions + that can be consulted. (again this requires to change the endpoint, see the danger note + in :ref:`Service `) +2. Test the API. + +The latter consists in specific tokens that will work on **IAP-Sandbox only**. + +* token ``000000``: represents a non-existing account. Returns + an :class:`~odoo.addons.iap.models.iap.InsufficientCreditError` on authorize attempt. +* token ``000111``: Represents an account without sufficient credits to perform any service. + Returns an :class:`~odoo.addons.iap.models.iap.InsufficientCreditError` on authorize attempt. +* token ``111111``: Represents an account with enough credits to perform any service. + An authorize attempt will return a dummy transacion token that is processed by the capture + and cancel routes. + +.. note:: + + * Those tokens are only active on the IAP-Sanbox server. + * The service key is completely ignored with this flow, If you want to run a robust test + of your service, you should ignore these tokens. + Odoo Helpers ============ @@ -548,7 +591,7 @@ Charging .. note:: A new functionality was introduced to capture a different amount of credits than reserved. - As this patch was added on the 15th of January 2018, you will need to upgrade your ``iap`` module in order to use it. + As this patch was added on the **15th of January 2018**, you will need to upgrade your ``iap`` module in order to use it. The specifics of the new functionality are highlighted in the code. .. class:: odoo.addons.iap.models.iap.charge(env, key, account_token, credit[, description, credit_template]) @@ -567,12 +610,12 @@ Charging configuration key :param ServiceKey key: :param UserToken token: - :param int credit: + :param float credit: :param str description: :param Qweb template credit_template: .. code-block:: python - :emphasize-lines: 10,13,14,15 + :emphasize-lines: 11,13,14,15 @route('/deathstar/superlaser', type='json') def superlaser(self, user_account, @@ -583,7 +626,8 @@ Charging 0.0 is none, 1.0 is full power """ credits = int(MAXIMUM_POWER * factor) - with charge(request.env, SERVICE_KEY, user_account, credits) as transaction: + description = "We will demonstrate the power of this station on your home planet of Alderaan." + with charge(request.env, SERVICE_KEY, user_account, credits, description) as transaction: # TODO: allow other targets transaction.credit = max(credits, 2) # Sales ongoing one the energy price, diff --git a/doc/webservices/images/creating_service.png b/doc/webservices/images/creating_service.png new file mode 100644 index 00000000000..dec807ade45 Binary files /dev/null and b/doc/webservices/images/creating_service.png differ diff --git a/doc/webservices/images/menu.png b/doc/webservices/images/menu.png new file mode 100644 index 00000000000..50e1ed0267a Binary files /dev/null and b/doc/webservices/images/menu.png differ diff --git a/doc/webservices/images/package.png b/doc/webservices/images/package.png index a1627f9aecd..aca5959f7db 100644 Binary files a/doc/webservices/images/package.png and b/doc/webservices/images/package.png differ diff --git a/doc/webservices/images/service_create.png b/doc/webservices/images/service_create.png deleted file mode 100644 index 2163259ed84..00000000000 Binary files a/doc/webservices/images/service_create.png and /dev/null differ diff --git a/doc/webservices/images/service_created.png b/doc/webservices/images/service_created.png new file mode 100644 index 00000000000..1cb7a78c921 Binary files /dev/null and b/doc/webservices/images/service_created.png differ diff --git a/doc/webservices/images/service_list.png b/doc/webservices/images/service_list.png new file mode 100644 index 00000000000..d2b37f6255c Binary files /dev/null and b/doc/webservices/images/service_list.png differ diff --git a/doc/webservices/images/service_packs.png b/doc/webservices/images/service_packs.png deleted file mode 100644 index f86e97888be..00000000000 Binary files a/doc/webservices/images/service_packs.png and /dev/null differ diff --git a/doc/webservices/images/service_select.png b/doc/webservices/images/service_select.png deleted file mode 100644 index fb5878cd384..00000000000 Binary files a/doc/webservices/images/service_select.png and /dev/null differ