Region Event Service
====================

The region event service provides endpoints which handle boundary crossing events for a devices monitored regions.

.. contents:: Topics

Endpoints
---------

.. _regionevent-get-region-defintions:

Get Region Definitions
~~~~~~~~~~~~~~~~~~~~~~

.. http:get:: regionevent/regionDefinitions.json

    region_event_post must be included in the scope for the initial access token negotiated in the oauth/requestGuestToken request. regionevent/regionDefinitions.json obtains a list of regions based on the latitude and longitude of the favorite store of the card number queried, or enrollment store if no favorite store is set. The user's device should attempt to monitor the locations returned. Additionally, this method provides a special OAuth token that should be used to authenticate Post Region Event calls. This token does not expire.

    The following authentication methods are allowed for this endpoint:

    * :ref:`oauth_auth`

    :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in.
    :query String printedCardNumber: *(required)*  The card of the user.

.. http:response:: success

    :jsonparam String result: *(required)*  ``success``
    :jsonparam String regionEventAccessToken: *(required)*  A token used for authenticating with Post Region Event endpoint.
    :jsonparam List[Object] geoRegions: *(required)* See :http:jsonentity:`RegionDefinition` for format of the objects.

    Example GET request to :http:get:`regionevent/regionDefintions.json`:

        https://api.staging.paytronix.com:1283/rest/|release|/regionevent/regionDefintions.json?access_token=CjyxRJwTbA26_gUP__O6jUk1pbErFrxgQ90UYMcL01&printedCardNumber=60000300000095362&authentication=oauth&merchantId=30

    Example Response

    .. code:: javascript

        {
            "result": "success",
            "regionEventAccessToken": "CSDKs2839dfj_dfsd_fweiw9f823jSADlks9d832sa",
            "geoRegions": [
                {
                    "coordinates": {
                        "latitude":"44.419069",
                        "longitude":"-72.015510"
                    },
                    "regionType":"storeCode",
                    "radius":500,
                    "storeCode":"abc3"
                },
                {
                    "coordinates": {
                        "latitude":"42.344748",
                        "longitude":"-71.205246"
                    },
                    "regionType":"storeCode",
                    "radius":500,
                    "storeCode":"2"
                }
            ]
        }



.. _regionevent-post-region-event:

Post Region Event
~~~~~~~~~~~~~~~~~

.. http:post:: regionevent/regionEvent.json

    Endpoint to call when a user crosses a monitored region boundary. When authenticating with oauth, the client should pass the token recieved from the last call to :ref:`regionevent-get-region-defintions`.

    The following authentication methods are allowed for this endpoint:

    * :ref:`oauth_auth`

    :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in.
    :jsonparam String printedCardNumber: *(required)*  The card of the user.
    :jsonparam Object coordinates: *(optional)* The current location of the user.
    :jsonparam String regionEventType: *(required)* Possible values: ``ENTER`` or ``EXIT`` indicating whether a user has entered or left a region.
    :jsonparam Object region: *(required)* The identifier of the subject region. See :http:jsonentity:`RegionIdentity`

.. http:response:: success

    :jsonparam String result: *(required)*  ``success``
    :jsonparam String message: *(optional)* The message to be displayed to the user. If this field is not included in the response, a message should not be displayed

    Example Request Body

    .. code:: javascript

        {
            "merchantId": 30,
            "access_token": "CSDKs2839dfj_dfsd_fweiw9f823jSADlks9d832sa",
            "printedCardNumber": "60000300000095362",
            "coordinates": {
                "latitude":"43.3942918",
                "longitude":"-67.0680837"
            },
            "regionEventType": "ENTER",
            "region": {
                "regionType":"storeCode",
                "storeCode":"1"
            }
        }

    Example Response with a message

    .. code:: javascript

        {
            "result": "success",
            "message": "Need a pick-me-up? Check out JK Cafe's delicious pastries!"
        }

    And without a message it is simply

    .. code:: javascript

        {
            "result": "success"
        }

Reply Objects
-------------

.. http:jsonentity:: RegionDefinition

    :jsonparam String regionType: *(required)*  ``storeCode``
    :jsonparam String storeCode: *(required)*  The unique code of the store at this region.
    :jsonparam Object coordinates: *(required)*  The coordinates the region is centered at. See :http:jsonentity:`Coordinates`
    :jsonparam Integer radius: *(required)*  The radius of this region measured in meters.

.. http:jsonentity:: Coordinates

    :jsonparam Decimal latitude: *(required)*  The latitude of a coordinate pair.
    :jsonparam Decimal longitude: *(required)*  The latitude of a coordinate pair.

.. http:jsonentity:: RegionIdentity

    :jsonparam String regionType: *(required)*  ``storeCode``
    :jsonparam String storeCode: *(required)*  The unique code of the store at this region.


Error Codes
-----------

Typically there is little user recourse for errors returned by the Region Event Service and most calls will happen in the background to the user, so it is not useful to display an error to the user. That said, the errorMessage field should be suitable for displaying to an end user and the errorCode is suitable for mapping your own error message to display.


+---------------------------------------+---------------------------------------------+
| Code                                  | Message                                     |
+=======================================+=============================================+
| ``regionevent.server_error``          | Unable to process this region event request |
+---------------------------------------+---------------------------------------------+
| ``regionevent.auth_error``            | Integration not authorized for merchant     |
+---------------------------------------+---------------------------------------------+
| ``regionevent.unknown_region``        | Did not recognize designated region         |
+---------------------------------------+---------------------------------------------+
| ``regionevent.no_time_zone``          | Unable to determine time zone               |
+---------------------------------------+---------------------------------------------+
| ``regionevent.not_configured``        | This feature has not been fully configured  |
+---------------------------------------+---------------------------------------------+
| ``regionevent.server_error``          | Unable to process region defintions request |
+---------------------------------------+---------------------------------------------+
| ``regionevent.not_configured``        | This feature has not been fully configured  |
+---------------------------------------+---------------------------------------------+
| ``regionevent.no_guest_neighborhood`` | Unable to determine guest neighborhood      |
+---------------------------------------+---------------------------------------------+