Gather information when approaching at the forecourt

POST /gas-stations/{gasStationId}/approaching
OAuth2 Oidc

This request will:

  • Return a list of paymentMethods of the user which can be used at the gas station.

  • Return up-to-date price information (price structure) at the gas station.

  • Return a list of pumps available at the gas station together with the current status (free, inUse, readyToPay, outOfOrder). No pumps might be returned if the list of payment methods is empty.

The approaching is a necessary first api call for connected fueling. Without a valid approaching the get pump and wait for status change calls may be answered with a 403 Forbidden status code. An approaching is valid for one fueling only and can't be reused. If a long (not further disclosed time) has passed, the approaching is also invalidated. So if the client is receiving a 403 Forbidden on the above mentioned calls, a new approaching has to be issued, this can be done transparent to the user. Other than authorization, the most common error states encountered should be:

  • 404, if the gas station does not exist or ConnectedFueling is not available at this station
  • 502, if there was a communication failure with a third party (e.g. the gas station in question fails to respond). Retry is possible
  • 503, if ConnectedFueling is available, but the site is offline

Path parameters

Query parameters

  • compile[openingHours] boolean

    Reduces the opening hours rules. After compilation, only rules with the action open will remain in the response.

    Values are true or false.

Responses

  • 201 application/vnd.api+json

    Created

    Hide response attributes Show response attributes object
    • data object
      Hide data attributes Show data attributes object
      • type string

        Value is approaching.

      • id string(uuid)

        Approaching ID

      • relationships object
        Hide relationships attributes Show relationships attributes object
        • gasStation object
          Hide gasStation attribute Show gasStation attribute object
          • data object
            Hide data attributes Show data attributes object
            • type string

              Value is gasStation.

            • id string(uuid)

              Gas Station ID

        • gasStationNote object
          Hide gasStationNote attribute Show gasStationNote attribute object
          • data object
            Hide data attributes Show data attributes object
            • type string

              Value is gasStationNote.

            • id string(uuid)

              Gas Station Note's ID

        • paymentMethods object
          Hide paymentMethods attribute Show paymentMethods attribute object
          • data array[object]
            Hide data attributes Show data attributes object
            • type string

              Value is paymentMethod.

            • id string(uuid)

              Payment Method ID

        • unsupportedPaymentMethods object
          Hide unsupportedPaymentMethods attribute Show unsupportedPaymentMethods attribute object
          • data array[object]
            Hide data attributes Show data attributes object
            • type string

              Value is paymentMethod.

            • id string(uuid)

              Payment Method ID

        • supportedPaymentMethodKinds object
          Hide supportedPaymentMethodKinds attribute Show supportedPaymentMethodKinds attribute object
          • data array[object]
            Hide data attributes Show data attributes object
            • type string

              Value is paymentMethodKind.

            • id string

              Payment method kind

        • unsupportedPaymentMethodKinds object
          Hide unsupportedPaymentMethodKinds attribute Show unsupportedPaymentMethodKinds attribute object
          • data array[object]
            Hide data attributes Show data attributes object
            • type string

              Value is paymentMethodKind.

            • id string

              Payment method kind

        • transactions object
          Hide transactions attribute Show transactions attribute object
          • data array[object]
            Hide data attributes Show data attributes object
            • type string

              Value is transaction.

            • id string

              transaction ID

    • included array[object]
      One of:
      GasStation object GasStationNote object FuelPrice object Pump object PaymentMethod object PaymentMethodKind object Transaction object
  • 400 application/vnd.api+json

    Bad request

    Hide response attribute Show response attribute object
    • errors array[object]
      Hide errors attributes Show errors attributes object
      • id string

        A unique identifier for this particular occurrence of the problem.

      • links object
        Hide links attribute Show links attribute object
        • about string

          A link that leads to further details about this particular occurrence of the problem.

      • status string

        the HTTP status code applicable to this problem, expressed as a string value.

      • code string

        an application-specific error code, expressed as a string value.

      • title string

        A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

      • detail string

        a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

      • source object

        An object containing references to the source of the error.

        Hide source attributes Show source attributes object
        • pointer string

          A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].

        • parameter string

          A string indicating which URI query parameter caused the error.

      • meta object

        a meta object containing non-standard meta-information about the error.

        Hide meta attribute Show meta attribute object
  • 401 application/vnd.api+json

    OAuth token missing or invalid or a linked identity is missing.

    Linked identity missing is a special case where you need to make sure that the user has additionally logged in / authorized with a third-party.

    This is not relevant for most use-cases.

    The specific error code that identifies a missing linked identity is missing-linked-identity

    Example:

      {
      "errors": [
          {
              "id": "cbgmhslmp1o9or9kh1p0",
              "title": "Missing linked identity for authorized access",
              "detail": "Linked identity is needed to access this resource, please check why the user does not have a linked identity",
              "status": "401",
              "code": "missing-linked-identity"
          }
      ]
  }
    Hide response attribute Show response attribute object
    • errors array[object]
      Hide errors attributes Show errors attributes object
      • id string

        A unique identifier for this particular occurrence of the problem.

      • links object
        Hide links attribute Show links attribute object
        • about string

          A link that leads to further details about this particular occurrence of the problem.

      • status string

        the HTTP status code applicable to this problem, expressed as a string value.

      • code string

        an application-specific error code, expressed as a string value.

      • title string

        A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

      • detail string

        a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

      • source object

        An object containing references to the source of the error.

        Hide source attributes Show source attributes object
        • pointer string

          A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].

        • parameter string

          A string indicating which URI query parameter caused the error.

      • meta object

        a meta object containing non-standard meta-information about the error.

        Hide meta attribute Show meta attribute object
  • 404 application/vnd.api+json

    Resource not found

    Hide response attribute Show response attribute object
    • errors array[object]
      Hide errors attributes Show errors attributes object
      • id string

        A unique identifier for this particular occurrence of the problem.

      • links object
        Hide links attribute Show links attribute object
        • about string

          A link that leads to further details about this particular occurrence of the problem.

      • status string

        the HTTP status code applicable to this problem, expressed as a string value.

      • code string

        an application-specific error code, expressed as a string value.

      • title string

        A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

      • detail string

        a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

      • source object

        An object containing references to the source of the error.

        Hide source attributes Show source attributes object
        • pointer string

          A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].

        • parameter string

          A string indicating which URI query parameter caused the error.

      • meta object

        a meta object containing non-standard meta-information about the error.

        Hide meta attribute Show meta attribute object
  • 406 application/vnd.api+json

    The specified accept header is invalid

    Hide response attribute Show response attribute object
    • errors array[object]
      Hide errors attributes Show errors attributes object
      • id string

        A unique identifier for this particular occurrence of the problem.

      • links object
        Hide links attribute Show links attribute object
        • about string

          A link that leads to further details about this particular occurrence of the problem.

      • status string

        the HTTP status code applicable to this problem, expressed as a string value.

      • code string

        an application-specific error code, expressed as a string value.

      • title string

        A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

      • detail string

        a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

      • source object

        An object containing references to the source of the error.

        Hide source attributes Show source attributes object
        • pointer string

          A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].

        • parameter string

          A string indicating which URI query parameter caused the error.

      • meta object

        a meta object containing non-standard meta-information about the error.

        Hide meta attribute Show meta attribute object
  • 410 application/vnd.api+json

    Resource is gone

    Hide response attribute Show response attribute object
    • errors array[object]
      Hide errors attributes Show errors attributes object
      • id string

        A unique identifier for this particular occurrence of the problem.

      • links object
        Hide links attribute Show links attribute object
        • about string

          A link that leads to further details about this particular occurrence of the problem.

      • status string

        the HTTP status code applicable to this problem, expressed as a string value.

      • code string

        an application-specific error code, expressed as a string value.

      • title string

        A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

      • detail string

        a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

      • source object

        An object containing references to the source of the error.

        Hide source attributes Show source attributes object
        • pointer string

          A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].

        • parameter string

          A string indicating which URI query parameter caused the error.

      • meta object

        a meta object containing non-standard meta-information about the error.

        Hide meta attribute Show meta attribute object
  • 415 application/vnd.api+json

    The specified content type header is invalid

    Hide response attribute Show response attribute object
    • errors array[object]
      Hide errors attributes Show errors attributes object
      • id string

        A unique identifier for this particular occurrence of the problem.

      • links object
        Hide links attribute Show links attribute object
        • about string

          A link that leads to further details about this particular occurrence of the problem.

      • status string

        the HTTP status code applicable to this problem, expressed as a string value.

      • code string

        an application-specific error code, expressed as a string value.

      • title string

        A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

      • detail string

        a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

      • source object

        An object containing references to the source of the error.

        Hide source attributes Show source attributes object
        • pointer string

          A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].

        • parameter string

          A string indicating which URI query parameter caused the error.

      • meta object

        a meta object containing non-standard meta-information about the error.

        Hide meta attribute Show meta attribute object
  • 500 application/vnd.api+json

    Internal server error

    Hide response attribute Show response attribute object
    • errors array[object]
      Hide errors attributes Show errors attributes object
      • id string

        A unique identifier for this particular occurrence of the problem.

      • links object
        Hide links attribute Show links attribute object
        • about string

          A link that leads to further details about this particular occurrence of the problem.

      • status string

        the HTTP status code applicable to this problem, expressed as a string value.

      • code string

        an application-specific error code, expressed as a string value.

      • title string

        A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

      • detail string

        a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

      • source object

        An object containing references to the source of the error.

        Hide source attributes Show source attributes object
        • pointer string

          A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].

        • parameter string

          A string indicating which URI query parameter caused the error.

      • meta object

        a meta object containing non-standard meta-information about the error.

        Hide meta attribute Show meta attribute object
  • 502 application/vnd.api+json

    Error occurred while communicating with PACE services

    Hide response attribute Show response attribute object
    • errors array[object]
      Hide errors attributes Show errors attributes object
      • id string

        A unique identifier for this particular occurrence of the problem.

      • links object
        Hide links attribute Show links attribute object
        • about string

          A link that leads to further details about this particular occurrence of the problem.

      • status string

        the HTTP status code applicable to this problem, expressed as a string value.

      • code string

        an application-specific error code, expressed as a string value.

      • title string

        A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

      • detail string

        a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

      • source object

        An object containing references to the source of the error.

        Hide source attributes Show source attributes object
        • pointer string

          A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].

        • parameter string

          A string indicating which URI query parameter caused the error.

      • meta object

        a meta object containing non-standard meta-information about the error.

        Hide meta attribute Show meta attribute object
  • 503 application/vnd.api+json

    Error occurred while communicating with gas station network

    Hide response attribute Show response attribute object
    • errors array[object]
      Hide errors attributes Show errors attributes object
      • id string

        A unique identifier for this particular occurrence of the problem.

      • links object
        Hide links attribute Show links attribute object
        • about string

          A link that leads to further details about this particular occurrence of the problem.

      • status string

        the HTTP status code applicable to this problem, expressed as a string value.

      • code string

        an application-specific error code, expressed as a string value.

      • title string

        A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

      • detail string

        a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

      • source object

        An object containing references to the source of the error.

        Hide source attributes Show source attributes object
        • pointer string

          A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].

        • parameter string

          A string indicating which URI query parameter caused the error.

      • meta object

        a meta object containing non-standard meta-information about the error.

        Hide meta attribute Show meta attribute object
POST /gas-stations/{gasStationId}/approaching 
curl \
 -X POST https://api.pace.cloud/fueling/2024-1/gas-stations/93db55b6-a9ab-4597-a253-49a1718cea0a/approaching \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response examples (201) 
{
  "data": {
    "id": "c3f037ea-492e-4033-9b4b-4efc7beca16c",
    "type": "approaching",
    "relationships": {
      "gasStation": {
        "data": {
          "id": "93db55b6-a9ab-4597-a253-49a1718cea0a",
          "type": "gasStation"
        }
      },
      "gasStationNote": {
        "data": {
          "id": "eb7a24cd-39c4-425d-8efd-36df7ef016cb",
          "type": "gasStationNote"
        }
      },
      "paymentMethods": {
        "data": [
          {
            "id": "6e30ccd1-0f76-4208-bd3d-a804f810cba8",
            "type": "paymentMethod"
          }
        ]
      },
      "unsupportedPaymentMethods": {
        "data": [
          {
            "id": "38ce6b10-c515-4316-9c40-64e1382b07b3",
            "type": "paymentMethod"
          }
        ]
      },
      "supportedPaymentMethodKinds": {
        "data": [
          {
            "id": "sepa",
            "type": "paymentMethodKind"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "93db55b6-a9ab-4597-a253-49a1718cea0a",
      "type": "gasStation",
      "attributes": {
        "address": {
          "city": "Karlsruhe",
          "street": "Haid-und-Neu-Str.",
          "houseNo": "18",
          "postalCode": "76131",
          "countryCode": "DE"
        },
        "latitude": 49.013,
        "amenities": [
          "restaurant",
          "wifi",
          "toilets"
        ],
        "longitude": 8.425,
        "stationName": "PACE Station",
        "openingHours": {
          "rules": [
            {
              "days": [
                "monday",
                "tuesday",
                "wednesday",
                "thursday",
                "friday"
              ],
              "timespans": [
                {
                  "to": "23:00",
                  "from": "06:00"
                }
              ]
            },
            {
              "days": [
                "saturday"
              ],
              "timespans": [
                {
                  "to": "23:00",
                  "from": "07:00"
                }
              ]
            },
            {
              "days": [
                "sunday"
              ],
              "timespans": [
                {
                  "to": "22:00",
                  "from": "07:00"
                }
              ]
            }
          ],
          "timezone": "+01:00"
        },
        "paymentMethods": [
          "sepa"
        ]
      },
      "relationships": {
        "pumps": {
          "data": [
            {
              "id": "cc6eb485-3f23-48bb-aa79-f995ba35b824",
              "type": "pump"
            },
            {
              "id": "689631b2-cd75-4f01-a36e-72f77cd4f007",
              "type": "pump"
            }
          ]
        },
        "fuelPrices": {
          "data": [
            {
              "id": "6b5bff6f-74e1-40a1-9da0-72305292d939",
              "type": "fuelPrice"
            },
            {
              "id": "f563e0ee-ba9a-4869-8fe7-42639fcf375d",
              "type": "fuelPrice"
            },
            {
              "id": "cb1afd35-f531-4606-abc8-e1cfbc1f96f5",
              "type": "fuelPrice"
            }
          ]
        }
      }
    },
    {
      "id": "eb7a24cd-39c4-425d-8efd-36df7ef016cb",
      "type": "gasStationNote",
      "attributes": {
        "info": "warn",
        "name": "Hoyer CNG Notice",
        "text": "CNG is not available for Connected Fueling yet!"
      }
    },
    {
      "id": "6b5bff6f-74e1-40a1-9da0-72305292d939",
      "type": "fuelPrice",
      "attributes": {
        "unit": "liter",
        "price": 1.399,
        "currency": "EUR",
        "fuelType": "ron95e5",
        "productName": "Super E5"
      }
    },
    {
      "id": "f563e0ee-ba9a-4869-8fe7-42639fcf375d",
      "type": "fuelPrice",
      "attributes": {
        "unit": "liter",
        "price": 1.379,
        "currency": "EUR",
        "fuelType": "ron95e10",
        "productName": "Super E10"
      }
    },
    {
      "id": "cb1afd35-f531-4606-abc8-e1cfbc1f96f5",
      "type": "fuelPrice",
      "attributes": {
        "unit": "liter",
        "price": 1.239,
        "currency": "EUR",
        "fuelType": "diesel",
        "productName": "Diesel"
      }
    },
    {
      "id": "cc6eb485-3f23-48bb-aa79-f995ba35b824",
      "type": "pump",
      "attributes": {
        "status": "free",
        "identifier": "1"
      }
    },
    {
      "id": "689631b2-cd75-4f01-a36e-72f77cd4f007",
      "type": "pump",
      "attributes": {
        "status": "inUse",
        "identifier": "2"
      }
    },
    {
      "id": "6e30ccd1-0f76-4208-bd3d-a804f810cba8",
      "meta": {
        "merchantName": "PACE"
      },
      "type": "paymentMethod",
      "attributes": {
        "kind": "sepa",
        "twoFactor": true,
        "vendorPRN": "prn:cms:payment-method-vendors:3af4b4a7-33fc-4930-9c2d-6eea7e488398",
        "identificationString": "DEUTSCHEBANK XX 3000"
      }
    },
    {
      "id": "38ce6b10-c515-4316-9c40-64e1382b07b3",
      "type": "paymentMethod",
      "attributes": {
        "kind": "sepa",
        "identificationString": "ING-DiBa XX 1337"
      }
    },
    {
      "id": "sepa",
      "type": "paymentMethodKind",
      "attributes": {}
    }
  ]
}
Response examples (400) 
{
  "errors": [
    {
      "id": "string",
      "links": {
        "about": "string"
      },
      "status": "string",
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}
Response examples (401) 
{
  "errors": [
    {
      "id": "string",
      "links": {
        "about": "string"
      },
      "status": "string",
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}
Response examples (404) 
{
  "errors": [
    {
      "id": "string",
      "links": {
        "about": "string"
      },
      "status": "string",
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}
Response examples (406) 
{
  "errors": [
    {
      "id": "string",
      "links": {
        "about": "string"
      },
      "status": "string",
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}
Response examples (410) 
{
  "errors": [
    {
      "id": "string",
      "links": {
        "about": "string"
      },
      "status": "string",
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}
Response examples (415) 
{
  "errors": [
    {
      "id": "string",
      "links": {
        "about": "string"
      },
      "status": "string",
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}
Response examples (500) 
{
  "errors": [
    {
      "id": "string",
      "links": {
        "about": "string"
      },
      "status": "string",
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}
Response examples (502) 
{
  "errors": [
    {
      "id": "string",
      "links": {
        "about": "string"
      },
      "status": "string",
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}
Response examples (503) 
{
  "errors": [
    {
      "id": "string",
      "links": {
        "about": "string"
      },
      "status": "string",
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}