Use Case "Creation and prequalification of a PQ"

The first step is to create a PQ for a reserve unit or reserve group. To do this, the IDs of the reserve unit/reserve group must be determined. The following request has to be done for a reserve unit:

It is similar for a reserve group:

As a result of the first step, the ID of the reserve unit/reserve group for which we want to create a PQ is displayed as response and should be noted for the next steps.

Response body:

A PQ can now be created using the ID of the unit. The following request is used to create a PQ for the reserve unit:

The information on the reserve type and the reserve direction is mandatory. The requested measurements do not necessarily have to be specified. Important: There must be no existing PQ of the same type and direction for this unit.

Note: An overview of mandatory fields can be found at the end of the Swagger documentation. The schemas below show the last endpoint definition and apply across all endpoints. The mandatory information is marked with a red asterisk:

Open

After the request has been made the response body contains the GUID of the new PQ:

If a typing error occurs when entering one of the mandatory fields, the error message will inform you of this. In the following example, the “e” at the end of the “Negative” reserve direction is forgotten.

Creating a PQ for a reserve group can be carried out in the same way as a reserve unit:

The response body of the reserve group is identical to the reserve unit.

For example, if the GUID is not known to the system, the following error is displayed.

The 'message' parameter specifies what the problem is. In this case, the GUID does not exist. It must be an input error.

The PQ we have just created can now be displayed. For a reserve unit, the API request might look like this:

For an reserve group, the API call might look like this:

The response body might look like this:

There are two methods for updating PQ-API data: PUT and PATCH. The Swagger documentation specifies in the request body which parameters can be changed using the PUT method. By default, a PUT sets all parameters defined by the request body to null if they are not explicitly specified. It is therefore advisable to specify all possible parameters in a PUT request. The PQ-API offers two PUT methods for PQs. The first PUT method allows you to customize the requested measurement data. This endpoint is available for Balancing Service Providers. To process this data, all rules of the PQ-Portal apply, such as the PQ must be in status 'planned'.

The PQ is successfully updated when HTTP code 204 is returned. In this example, all possible parameters have been set with values. If a parameter had been removed from the request body (for example reactionTime), this parameter would have been set to null.

Now the PQ data look like this:

You can also use the PATCH method to modify data. For example you can use PATCH and the prequalification endpoint to change the date of expiration for a prequalification under validUntil. In principle, a PATCH works differently compared to a PUT and requires input in the request body in JSON patch rfc6902 format based on schema PatchPrequalification.

“op” = operation to perform
”path” = path to the parameter you want to modify
“from” = just needed for the operations ‘copy’ and ‘move’ (irrelevant for this example)
”value” = the value of the parameter

Several parameters can also be modified at the same time.

The example value schema of a request body looks like this:

Updating the parameter validUntil is only allowed for PQs in status prequalified.

To set the parameter validUntil to the new date 2028-01-16 the full request looks like this:

Apart from the parameter validUntil, nothing has been changed in the PQ.

The new date for validUntil is now visible in the PQ by using the following request:

Response body:

The final step is to request the PQ. If not all the requirements for prequalification are met, the response of the endpoint will indicate this within the error message. The PQ ID is required to execute the endpoint. The requested action is written into the request body:

The PQ is successfully requested when HTTP code 204 is returned.

For example, if an incorrect action is carried out (prequalify instead of request), the error message 'forbidden' indicates the reason as you can see below: