Overview
With the add-on FCFS Shipper API Service, you can book Regular FCFS capacity at different network points. You can test this functionality on the Swagger platform. For those purposes, the KON environment will be made available to you.
Overall, the booking process consists in the following steps:
I. Network Point Identification (Optional): you should first request the ID number of the network point at which you wish to book regular FCFS capacity;
II. Availability Check: once you know the right network point ID, you must check the availability of capacity at that location, which will yield a unique Booking Process ID. PRISMA will send the availability message to the TSO, a response to which may take up to three minutes to arrive.
III. Booking Process Status Check: after you get the Booking Process ID you must use it to retrieve the availability response from the platform. This will, in turn, yield "Alternative IDs," which will represent possible booking options. Note that your original request may be one of those options despite the name (Alternative);
IV. FCFS Booking Request: now, with the Alternative ID, you can submit the booking request. At this point the booking request will be transmitted to the TSO and the transaction will be concluded within three minutes, if the TSO uses a synchronous booking process. If, however, the TSO indicates a need for a manual approval, you can only find out the status of your booking request in step V;
V. Final Booking Status Check: after PRISMA receives a final response message from the TSO, you can use the Booking Process ID to check the final status of your booking request.
The diagram below illustrates this process:
Instructions
To book Regular FCFS through the Shipper API, you must first retrieve the Bearer token to be used for authentication of API calls (either from Swagger documentation, your system or other tools).
To do so, do as follows:
1. After subscribing to the Shipper API service with the FCFS add-on, log into your admin account;
2. Click on the gear icon at the top right corner of the page;
3. Then, on the drop-down menu, click on "Premium Services;"
4. Scroll down and copy the API bearer token to the clipboard by clicking on "Copy to Clickboard."
5. Then, go to the Swagger page and click on "Authorize;"
6. Now, use the copied token to authorize your access;
Once you've authorized the API use, you can begin the Regular FCFS booking process.
I. Network Point Identification (Optional)
If you don't know the network point at which you'd like to book regular FCFS capacity, you can use the Shipper API to retrieve it. The most accurate way of doing so is to query for the specific Network Point Type.
On Swagger, do as follows:
1. After authorizing your use of Swagger, expand the "Get/Network Point" bar and click on "Try It Out;"
2. Then, click on the "connectionPointType" drop-down menu and select the relevant network point;
3. Now, choose the direction of the network point;
4. Finally, click on "Execute."
You will then be able to see the results in the "Response Body:"
You can use the "ID" to submit your regular FCFS booking.
II. Regular FCFS Availability Check
Once you know the network point at which you'd like to book regular FCFS capacity, you can submit an availability query.
Before testing the feature, you can check which entries are available and which fields are mandatory by click on "Model" above the parameters field in the expanded "Post/FCFSBooking/Regular/Check-Availability" tab:
Of all the parameters, Network Point ID, Quantity Value, Quantity Unit, Runtime Start and End and User Email are mandatory.
Now, to check the availability, do as follows:
1. After authorizing your use of Swagger, expand the "Post/FCFSBooking/Regular/Check-Availability" tab and click on "Try It Out;"
2. Then, freely edit the parameters in the json file and delete the irrelevant lines in accordance with your needs.
3. Finally, click on "Execute."
If your availability query is successful, you will receive a Code 200 message with a Booking Process ID.
The Booking Process ID is the code found in the "Response Body" field:
III. Booking Process Status Check
With the Booking Process ID, you must then submit status check message. This is a necessary step to retrieve the Alternative ID - that is, the message with an offer from the TSO. This message may take up to three minutes to reach the PRISMA system.
To do a process status check, do as follows:
1. After authorizing your use of Swagger, expand the "Get/fcfs-booking/regular/fcfs-process-state/{bookingprocessID}" and click on "Try It Out;"
2. Enter the Booking Process ID in the appropriate field;
3. Enter the email under which you submitted the availability check;
4. Finally, click on "Execute."
As before, the results will be displayed in the Response section. If your query is successful, you will receive a Code 200 message with one or more Alternative ID. One of those could be your original request, but if such a request is impossible to fulfill, other alternatives might be presented to you.
Then, choose the Alternative ID that best suits your needs and proceed to the next step:
At the top of the response, you can also view whether a Balancing Group or Portfolio Code are mandatory to proceed with the booking request as well as which code can be used:
IV. Regular FCFS Booking Request
With the Alternative ID of the offer you wish to book, you can proceed to the regular FCFS booking request, properly so called. If the TSO from which you wish to book regular FCFS capacity does not require manual approval, your transaction will be concluded within three minutes. If, in contrast, the TSO requires manual approval, the process may take longer.
As in step II, you can check which details are available and/or mandatory in the "Post/fcfs-booking/regular/book-capacity" by clicking on "Model:"
All fields marked with a red asterisk are mandatory. At this stage, the user email, the Network Point ID, the Booking Process ID and the Alternative ID are mandatory. If you do not wish to request capacity upgrade, you may delete those lines from the json file.
Now, to submit your regular FCFS booking request, do as follows:
1. After authorizing your use of Swagger, expand the "Post/fcfs-booking/regular/book-capacity" tab and click on "Try It Out;
2. Now, edit the values in the json message with the correct details and delete the irrelevant lines in accordance with your needs;
3. Finally, click on "Execute."
The resulting message can be viewed in the "Response" section:
V. Final Booking Status Check
At last, you must once again check the status of your booking request to disclose the TSO's final resolution. By doing so, you can ascertain whether your booking request was ultimately approved.
To do a process status check, do as follows:
1. After authorizing your use of Swagger, expand the Get/fcfs-booking/regular/fcfs-process-state/{bookingprocessID} and click on "Try It Out;"
2. Enter the Booking Process ID in the appropriate field;
3. Enter the email under which you submitted the availability check;
4. Finally, click on "Execute."
If the booking is successfully processed by the TSO, the status in the response will be "Booked:"
