Quickstart Guide
================

Learn how to get started quickly with the be.ENERGISED CPO API.


The following sample will show you:

* How to authenticate against the API
* How to fetch a list of charging stations available for your token

For this example we have the following expectations:

* You already know how to use REST APIs and have seen basic concepts of
  `jsonapi.org <https://jsonapi.org/>`_
* You received an API token which has at least one scope starting with
  `cpoapi` (if your license allows this you can create one
  in the be.ENERGISED ui under Settings -> CPO API. This might come
  with additional costs depending on your license).


Authentication
--------------
The API uses bearer tokens, which can be fetched on the endpoint
`https://beenergised-jwtapis.auth.eu-central-1.amazoncognito.com`
(see example curl request). The initial token fetching requests
contains a `client_id` and a `client_secret`.

The response of this first request (json response) is an access token. This
access token must then be included in calls against the endpoint of your
mandant.

Sample request to receive the `bearer token`. `CLIENT_ID` and `CLIENT_SECRET`
must be exchanged with your received client_id and client_secret.

.. code-block:: bash

  curl --location --request POST 'https://beenergised-jwtapis.auth.eu-central-1.amazoncognito.com/token?grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET' \
    --header 'Content-Type: application/x-www-form-urlencoded'

The response will look similar to the following:

.. code-block:: json

    {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
        "expires_in": 86400,
        "token_type": "Bearer"
    }

The field `access_token` must then be included in all further requests with
the header `Authorization: Bearer <access_token>`. Also keep an eye on the
`expires_in` field. This field gives you a hint, how long your token can
be used before you have renew it.

Fetch a list of charging stations
---------------------------------
In order to fetch the charging stations you need to first fetch the bearer
token (as described before). The received access token must then be added
to the request header (`Authorization`). The charging stations can then
be fetched with:

.. code-block:: bash

    curl --location --request GET 'https://yourmandant.beenergised.cloud/api/cpoapi/v1/charging_stations/' \
    --header 'Authorization: <access_token>'

This will result in a json response. The json response contains a `data`
attribute with the entries. The response will automatically take into account
your token restrictions. If the token is bound to a certain entity in the
be.ENERGISED system, you will only receive stations which are available for
that entity. The response also contains a pagination information, so
that you can continue to read further pages (if there are some).

Sample response:

.. code-block:: javascript

    "data": [
        {
            "type": "charging_stations",
            "id": "a1123a54-ef49-4e52-9465-2ac2dc100f2e",
            "attributes": {
                "label": "Station 1",
                "chargeBoxIdentity": "cp_1",
                "iccid": "12345",
                "imsi": "567869",
                "serialnumber": "112233",
                "firmwareVersion": "htb.firmware.version"
            }
        }
    ],
    "meta": {
        "pagination": {
            "total": 10,
            "offset": 0,
            "limit": 1,
            "lastPage": false
        }
    },
    "links": {
        "current": "https://slug.beenergised.cloud/api/cpoapi/v1/charging_stations/?page%5Blimit%5D=1&page%5Boffset%5D=0",
        "next": "https://slug.beenergised.cloud/api/cpoapi/v1/charging_stations/?page%5Blimit%5D=1&page%5Boffset%5D=10"
    }