Gather information when approaching at the forecourt Deprecated

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.

  • Create payment tokens for the paymentMethods of the user that are also supported at the gas station and pre-authorize the calculated maximum amount of money (background task).

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.

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

        • 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

    • included array[object]
      One of:
      GasStation object FuelPrice object Pump object PaymentMethod object PaymentMethodKind 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
  • 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/2020-4/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"
        }
      },
      "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": "6b5bff6f-74e1-40a1-9da0-72305292d939",
      "type": "fuelPrice",
      "attributes": {
        "price": 1.399,
        "currency": "EUR",
        "fuelType": "ron95e5",
        "productName": "Super E5"
      }
    },
    {
      "id": "f563e0ee-ba9a-4869-8fe7-42639fcf375d",
      "type": "fuelPrice",
      "attributes": {
        "price": 1.379,
        "currency": "EUR",
        "fuelType": "ron95e10",
        "productName": "Super E10"
      }
    },
    {
      "id": "cb1afd35-f531-4606-abc8-e1cfbc1f96f5",
      "type": "fuelPrice",
      "attributes": {
        "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 (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": {}
    }
  ]
}