Connectors
==========
A connector is a part of a charging station, where one charging stations
can have one to many connectors. A connector is often used to identify certain
actions on remote calls or necessary for other entities
(e.g. maintenance windows).

Reading
-------
Connectors can be accessed via the `connectors` `GET` endpoint.
This endpoint will return a list of all visible stations in be.ENERGISED.

The list endpoint is using
`offset pagination <pagination.html#offset-based-pagination>`__.

.. code-block:: bash

    curl --location --request GET 'https://<slug>.beenergised.cloud/api/cpoapi/v1/connectors/' \
    --header 'Authorization: <access_token>' \
    --header 'Content-Type: application/json'

Connectors might also be accessed in the context of a charging station.

The list endpoint is using
`offset pagination <pagination.html#offset-based-pagination>`__.

.. code-block:: bash

    curl --location --request GET 'https://<slug>.beenergised.cloud/api/cpoapi/v1/cp/:cpuuid/connectors/' \
    --header 'Authorization: <access_token>' \
    --header 'Content-Type: application/json'

A single connector can be either fetched directly with a
uuid or it can be loaded in the context of a station.

Together with the cp uuid.

.. code-block:: bash

    curl --location --request GET 'https://<slug>.beenergised.cloud/api/cpoapi/v1/cp/:cpuuid/connectors/:connectoruuid' \
    --header 'Authorization: <access_token>' \
    --header 'Content-Type: application/json'

Directly with the uuid:

.. code-block:: bash

    curl --location --request GET 'https://<slug>.beenergised.cloud/api/cpoapi/v1/connectors/:connectoruuid' \
    --header 'Authorization: <access_token>' \
    --header 'Content-Type: application/json'

Response fields
~~~~~~~~~~~~~~~
The ``GET`` responses include every field accepted by ``POST`` / ``PUT`` so
the returned object can be modified and PUT back without external lookups:

- **connectorType** (string): UUID of the connector type, as accepted by
  ``POST`` / ``PUT``. Use this to identify the exact connector type row
  attached to a station's model without cross-referencing the
  ``GET /connector_types`` list.
- **physicalReference** (string, nullable): Physical reference label
  (returned as ``null`` when no reference is stored).
- **ocppId** (integer): OCPP connector identifier as configured on the
  station (matches the ``ocppId`` accepted by ``POST`` / ``PUT``).

Connector types
---------------
The global catalogue of connector types available in be.ENERGISED:

.. code-block:: bash

    curl --location --request GET 'https://<slug>.beenergised.cloud/api/cpoapi/v1/connector_types' \
    --header 'Authorization: <access_token>' \
    --header 'Content-Type: application/json'

Each entry exposes ``uuid``, ``label``, ``socket``, ``polarisType``,
``maxPowerInKw``, ``currentType`` and ``maxPhase``. The technical attributes
are there to disambiguate rows that share a ``label`` (e.g. multiple
"Type 2 ≤ 11 kW" seeds).

If you already know the model of the station you are configuring, prefer the
per-model endpoint below — it returns only the connector types actually
attached to that model, so no disambiguation is required:

.. code-block:: bash

    curl --location --request GET 'https://<slug>.beenergised.cloud/api/cpoapi/v1/models/:id/connector_types' \
    --header 'Authorization: <access_token>' \
    --header 'Content-Type: application/json'

Use the ``uuid`` from the response as the ``connectorType`` value when
creating a connector via ``POST /charging_stations/:cpuuid/connectors/``.