Guides

EMP

The EMP mode is designed for use cases where only Charging Keys are exchanged with Plugsurfing. In this mode, Plugsurfing does not have the list of users.

Charging Keys - GET

Returns all charging keys associated with the given fleetId. If not fleetId is set, it returns all charging keys.

The response is paginated, and if there are more keys than can be returned in a single response, a cursor property is included. This cursor can be used in subsequent requests to retrieve additional keys, until there are no more results, at which point the cursor will be omitted from the response.

Endpoint: /emp/v1/charging-keys

API Reference

Request parameters:

  • fleetId (string, optional) - Filter charging keys assigned to a specific Fleet id
  • cursor (string, optional) - Cursor used to fetch the next set of keys
  • page_size (string, optional, default 100) - How many keys should be returned, 10 to 500

Example parameters:

?fleetId=y1nNLJqb7m&cursor=0VEAR5v76m&page_size=100

Example response:

200 - OK

{
  "keys": [
    {
      "keyIdentifier": "3633e0e0",
      "validTo": "2022-01-24T11:25:54.210Z",
      "contractId": "DE-9FS-C045DS363-E",
      "visualNumber": "DE-9FS-C045DS363-E",
      "fleetId": "y1nNLJqb7m",
      "enabled": true
    },
    ...
  ],
  "cursor": "0VEAR5v76m"
}

Fields

  • keys (array, required) - List of charging keys:
    • keyIdentifier (string, required) - Charging key identifier in hexadecimal, little-endian format
    • validTo (string, required) - Date until the key is valid.
    • contractId (string, required) - Charging key contract id
    • visualNumber (string, required) - Identifier printed on the physical key.
    • fleetId (string, optional) - Fleet id
    • enabled (boolean, required) - Charging key is enabled or disabled. Default: true
  • cursor (string, optional) - If there is more keys than page_size (default 100), cursor can be used in next request to get the next batch of keys

Error responses:

  • 403 - Forbidden. Missing Authentication Token.
  • 500 - Internal server error.

Charging Key Create - POST

Create a charging key.

Endpoint: /emp/v1/charging-keys

API Reference

Request body:

  • keyIdentifier (string, required) - Charging key identifier in hexadecimal, little-endian format
  • visualNumber (string, required) - Identifier printed on the physical key.
  • fleetId (string) - Fleet id
  • enabled (boolean) - Charging key is enabled or disabled. Default: true
  • contractId (string) - Charging key contract id. Optional (by default, we will create it for you)

Example body:

{
  "keyIdentifier": "e0e03336",
  "fleetId": "y1nNLJqb7m",
  "contractId": "DE-9FS-C045DS363-E",
  "visualNumber": "DE-9FS-C045DS363-E",
  "enabled": true
}

Example response:

200 - OK

{
  "keyIdentifier": "3633e0e0",
  "validTo": "2022-01-24T11:25:54.210Z",
  "contractId": "DE-9FS-C045DS363-E",
  "visualNumber": "DE-9FS-C045DS363-E",
  "fleetId": "y1nNLJqb7m",
  "enabled": true
}

Fields:

  • keyIdentifier (string, required) - Charging key identifier in hexadecimal, little-endian format
  • validTo (string, required) - Date until the key is valid.
  • contractId (string, required) - Charging key contract id
  • visualNumber (string, required) - Identifier printed on the physical key.
  • fleetId (string, optional) - Fleet id
  • enabled (boolean, required) - Charging key is enabled or disabled. Default: true

Error responses:

  • 400 - The provided query parameters, route parameters or body is invalid.
  • 409 - Charging key already activated.
  • 500 - Internal server error.

Charging Key Enable - PUT

Enable a key (after it was previously disabled) for charging. Key used here needs to be created before.

Endpoint: /emp/v1/charging-keys/{keyIdentifier}/enable

API Reference

Parameters:

  • keyIdentifier (string) - keyIdentifier provided when creating the charging key.

Example response:

200 - OK

{
  "keyIdentifier": "3633e0e0",
  "validTo": "2022-01-24T11:25:54.210Z",
  "contractId": "DE-9FS-C045DS363-E",
  "visualNumber": "DE-9FS-C045DS363-E",
  "fleetId": "y1nNLJqb7m",
  "enabled": true
}

Fields:

  • keyIdentifier (string, required) - Charging key identifier in hexadecimal, little-endian format
  • validTo (string, required) - Date until the key is valid.
  • contractId (string, required) - Charging key contract id
  • visualNumber (string, required) - Identifier printed on the physical key.
  • fleetId (string, optional) - Fleet id
  • enabled (boolean, required) - Charging key is enabled or disabled. Default: true

Error responses:

  • 403 - Forbidden. You have no access to this charging key.
  • 404 - Charging key not found.
  • 500 - Internal server error.

Charging Key Disable - PUT

Disable a key. It will immediately make Plugsurfing reject all authorization requests made with this key.

Note: Some CPOs store whitelisted keys, so in some rare cases it might take a bit longer time until charging is rejected.

Endpoint: /emp/v1/charging-keys/{keyIdentifier}/disable

API Reference

Parameters:

  • keyIdentifier (string) - keyIdentifier provided when creating the charging key.

Response:

200 - OK

{
  "keyIdentifier": "3633e0e0",
  "validTo": "2022-01-24T11:25:54.210Z",
  "contractId": "DE-9FS-C045DS363-E",
  "visualNumber": "DE-9FS-C045DS363-E",
  "fleetId": "y1nNLJqb7m",
  "enabled": true
}

Fields:

  • keyIdentifier (string, required) - Charging key identifier in hexadecimal, little-endian format
  • validTo (string, required) - Date until the key is valid.
  • contractId (string, required) - Charging key contract id
  • visualNumber (string, required) - Identifier printed on the physical key.
  • fleetId (string, optional) - Fleet id
  • enabled (boolean, required) - Charging key is enabled or disabled. Default: true

Error responses:

  • 403 - Forbidden. You have no access to this charging key.
  • 404 - Charging key not found.
  • 500 - Internal server error.

Charging Key Orders - GET

Fetch a list of charging key orders belonging to supported organizations.

Endpoint: /emp/v1/orders

API Reference

Query params

  • fromDate (iso datetime string, optional) - date value to filter orders that were created after
  • toDate (iso datetime string, optional) - date value to filter orders that were created before
  • status (string, optional) - value to filter orders by status
  • pageSize (number, optional) - number of orders to return
  • cursor (string, optional) - value to fetch next batch of paginated orders

Response fields:

  • products (array, required) - list of orders
  • cursor (string, optional) - cursor value to access next pages

Example response:

200 - OK

{
  "products": [
    {
      "id": "aYnky297eG",
      "address": {
        "country": "Austria",
        "additionalInformation": "test test",
        "firstName": "Frans",
        "lastName": "Anderson",
        "address": "First Way 261b",
        "city": "Wistful Vista",
        "postalCode": "85960",
        "companyName": "Low area Corp.",
        "addressLine2": "Suite 9"
      },
      "quantity": 1,
      "product": {
        "id": "Am07b6Q7JZ"
      },
      "created": "2023-06-26T10:00:00Z",
      "organizationId": "JoEl1xoP7r",
      "status": "ORDER_ASSIGNED",
      "updated": "2023-06-26T12:00:00Z"
    }
  ],
  "cursor": "Cml116D3OZ"
}

Error responses:

  • 500 - Internal server error.

Assign Charging Key Order - POST

Mark order as Assigned

Endpoint: /emp/v1/order/{orderId}/assign

API Reference

Parameters:

  • orderId (string) - order id to be assigned

Response fields:

Product

Example response:

200 - OK

{
  "id": "aYnky297eG",
  "address": {
    "country": "Austria",
    "additionalInformation": "test test",
    "firstName": "Frans",
    "lastName": "Anderson",
    "address": "First Way 261b",
    "city": "Wistful Vista",
    "postalCode": "85960",
    "companyName": "Low area Corp.",
    "addressLine2": "Suite 9"
  },
  "quantity": 1,
  "product": {
    "id": "Am07b6Q7JZ"
  },
  "created": "2023-06-26T10:00:00Z",
  "organizationId": "JoEl1xoP7r",
  "status": "ORDER_ASSIGNED",
  "updated": "2023-06-26T12:00:00Z"
}

Error responses:

  • 500 - Internal server error.

Session start - POST

Start session for EMP

Endpoint /emp/v1/sessions/start

API Reference

Request body:

  • connectorId (string, required) - connector id
  • keyIdentifier (string, required) - charging key identifier

Example body:

{
  "connectorId": "aHeS4zN1UjzJf/HVDH66SbaItXqHvfLxexulktxTqJavgcbozuV9KJGqNYjmaQPwTb4Ck9wTZcWeEdfeco1srw==",
  "keyIdentifier": "BnZd3qp87z"
}

Example response:

200 - OK

{
  "sessionId": "0gLAoxYQepp"
}

Error responses:

  • 400 - The provided body is invalid.
  • 500 - Internal server error.

Session stop - POST

Stop a remote charging session by providing a session id. Only sessions started remotely can be remotely stopped.

Endpoint /emp/v1/sessions/{sessionId}/stop

API Reference

Parameters:

  • sessionId (string, required) - session id

Response:

200 - OK

Error responses:

  • 400 - The provided body is invalid
  • 500 - Internal server error.

Session by id - GET

Get session by session id

Endpoint /emp/v1/sessions/{sessionId}

API Reference

Parameters:

  • sessionId (string, required) - session id

Response fields:

* - Available only if session is in COMPLETE status

  • sessionStatus (string) - explained in more detail in Statuses
  • balanceStatus (string, optional) - can be one of ["PROCESSING", "PAID", "DEBT", "REFUND"]. Should be ignored for External Clearing.
  • charger (object)
    • chargingStationName (string)
    • connectorLabel (string)
    • evseId (string)
  • chargingKeyType (string, optional) - is available only after a session has successfully started
  • connectorId (string)
  • duration * (string, optional)
  • energy * (object)
    • unit (string)
    • value (integer)
  • price (object) *
    • currencyCode (string) - 3-letter currency code
    • minorExclVat (integer)
    • minorInclVat (integer)
    • vat (string) - VAT percentage ex. "17.5"
  • receiptAvailable * (boolean) - if true, receipt is ready and its URL can be fetched from session receipt endpoint.
    Receipt is not generated for External Clearing.
  • sessionId (string)
  • site (string)
  • startTime (iso datetime string)
Example response:

200 - OK

{
  "sessionStatus": "COMPLETE",
  "balanceStatus": "PAID",
  "charger": {
    "chargingStationName": "ZzZ 220218114136937169",
    "connectorLabel": "1",
    "evseId": "NO*XXX*EZzZ220218114136937169*1"
  },
  "chargingKeyType": "virtual",
  "connectorId": "abcJd/vR5fvzBa0X/gxaXA==",
  "duration": "PT15M",
  "energy": {
    "unit": "WH",
    "value": 1840
  },
  "price": {
    "currencyCode": "NOK",
    "minorExclVat": 0,
    "minorInclVat": 0,
    "vat": "25"
  },
  "receiptAvailable": false,
  "sessionId": "Zw4z33VbNYC",
  "site": "ZzZ 220218114135485264",
  "startTime": "2022-02-18T10:41:39.148Z"
}

Error responses:

  • 400 - The provided query parameters, route parameters or body is invalid
  • 404 - User or session not found
  • 500 - Internal Server Error

Product order

  • id (string) - the id of the order
  • address (object)
    • country (string) - country
    • additionalInformation (string) - additional information
    • firstName (string) - first name
    • lastName (string) - last name
    • address (string) - address
    • city (string) - city
    • postalCode (string) - postal code
    • companyName (string) - company name
    • addressLine2 (string) - address line 2
  • quantity (number) - the quantity value
  • product (object)
    • id (string) - the id of ordered product
  • created (string) - the date when order was created
  • organizationId (string) - emp organization id
  • status (string) - the status of order
  • updated (string) - the date when order was update

Geosearch radius

See: Geosearch

Geosearch route

See: Geosearch

Get location by id

See: Geosearch

Location batch

See: Geosearch

Updated 3 months ago