Bidding Integration Tutorial
Introduction
Integrating with Piclo for our ‘Bidding flow’ has a few touch points. This tutorial will guide you through these, starting from establishing when you have a Bidding Opportunity, bidding into a Competition and finally fetching Competition Results to see if your bids were successful or not.
Prerequisites
- You have machine user credentials and you know how to authenticate.
- If not, check here for machine user credentials: https://docs.picloflex.com/#section/Overview/Getting-access
- Check here on how to generate a Bearer token: https://docs.picloflex.com/#tag/authtoken
- You have Assets which are qualified for an open Competition.
Bidding Diagram
Steps
1. Establish you have a Bidding Opportunity
The first step of this ‘flow’ is to be aware when there is a Competition open that you are qualified to bid into. There are a couple of ways to do this.
a. Via API
This is a simple get request to the V1 Bidding Opportunities API, to fetch any Competitions which are currently open that you are qualified to bid into:
curl --request GET https://api.picloflex.com/bidding-opportunities/v1/ --header 'Authorization: Bearer XXXXXX'
The Bidding Opportunities returned provide basic info on the Assets that are qualified to bid into a Competition; notably the individual Flex and Planned Asset ID’s, and their total combined capacity.
Since this is an API, you will need to poll this endpoint to regularly check for new opportunities. We encourage you to poll considerately, no more than once an hour (which is comfortably less than the shortest bidding window in use on Piclo Flex - at the time of writing).
b. Via Webhook
Coming soon👷🏗️
2. Fetch data to be used in Bid
Before submitting a Bid, you will need to find out more information on the Competition you are qualified to bid into. Also, you may want to fetch information on your Assets that are qualified to bid into this Competition (if you want to submit Asset-specific Bids you will need to know the maximum capacity of those Assets).
a. Fetch Competition details
At the next step you will see that in order to bid you submit a “Ballot” at the Competition level, containing “Bids” for each of the Competition’s Service Windows. Therefore, the key bits of information you will need to obtain are:
- The Competition
type - Each Service Window
id - The
capacity_requiredfor each service window
These can be fetched by using the competition_id returned from the previous step (fetching/ receiving Bidding Opportunities), by being passed into the V1 Fetch Competition by ID endpoint:
curl --request GET https://api.picloflex.com/competitions/v1/{Competition ID}/ --header 'Authorization: Bearer XXXXXX'
You may also be interested in other fields returned to help guide your logic around bidding, such as:
availability_guide_priceand theutilisation_guide_priceof the competition- The time the Competition is
closed - The
need_directionof the Competition - Service Period/ and Service Window
startandenddates and times
b. Fetch your Asset details
You may also want to ‘cross-check’ your qualifying Assets’ capabilities, as stored in Piclo Flex. You can do this by passing the flex Asset ID’s from the Bidding Opportunities step to either the V1 Flex Asset endpoint:
curl --request GET https://api.picloflex.com/assets/v1/{Flex Asset ID}/ --header 'Authorization: Bearer XXXXXX'
Or for Planned Assets, the V1 Planned Asset endpoint:
curl --request GET https://api.picloflex.com/planned-assets/v1/{Planned Asset ID}/ --header 'Authorization: Bearer XXXXXX'
If performing Asset-specific bidding at the next step, you will not be able to bid with a capacity that exceeds the Assets max capacity - so it could be useful to validate this before formulating your bid.
3. Bidding
Ballot/ Bid Relationship
The main part of this flow is to bid into an open Competition. To do so, you will need to create a Ballot against the Competition, with Bids for each Service Window. A Ballot represents the group of Bids that a Flex Provider has submitted for a given Competition. All Bids should be submitted together for a Competition, covering all Service Windows you wish to bid into.
If you want to re-submit a Bid for one Service Window amongst many for a given Competition, you need to supply all the other Bids for that Competition in the post request too. Only the latest submitted Ballot for a Competition will be "active".
If a Competition already has a Ballot submitted against it - with a different combination of Assets - then submitting a Ballot will not be allowed (and result in a 400 ). If you wish to re-submit a Ballot, you must use exactly the same set of Assets used in a previous Ballot.
Competition Type & Rates
All rates corresponding to the Service Window's "parent" Competition type must be supplied. For example, a Service Window which belongs to an "Availability & Utilisation" Competition type - an availability and utilisation rate must both be supplied (a service_fee rate should not be supplied).
Asset Specification
When submitting a Ballot for a Competition, if no Assets are explicitly specified, all of your Flex and Planned Assets that qualify for the specified Competition are included in the Service Window Bids. You can optionally choose to specify precisely which Flex and Planned Assets you wish to submit a Ballot with. Assets are associated at the Ballot 'level' i.e. this set of Assets are for all Bids in the Ballot.
Capacity
A final thing to note is around the Bid capacity . The Bid capacity for each Service Window cannot exceed the capacity_required for that Service Window. Also, the Bid capacity for each Service Window cannot exceed the corresponding capacity for either all of your qualifying assets (or specified assets). In either case, you will receive a 400, Bad Request if you violate this requirement.
To create a Ballot you can call the V1 Ballots endpoint, (e.g. not passing specific Assets, so bidding with all qualified Assets):
curl --request POST https://api.picloflex.com/bids/v1/competitions/{Competition ID}/ballots/ \
–-data ‘{"competition_id": <Competition ID>, "bids":[{"service_window_id": <Service Window ID>,"capacity": "9.32","max_runtime": "1T01:30:00","rates":[{"type": "availability","value": "123.45"}]}]}’ \
--header 'Authorization: Bearer XXXXXX' \
-–header 'Content-Type: application/json'
4. Checking Competition Results
The final step of this flow is to check if your Bids were accepted or rejected. After the Competition closes, System Operators will decide which Bids they have received to accept or reject. Once they have done this, there are a couple of ways to find out the results:
a. Via API
You can fetch the results for a specific Competition by passing the competition_id to the V1 Bid Results Endpoint:
curl --request GET https://api.picloflex.com/competitions/v1/{Competition ID}/ --header 'Authorization: Bearer XXXXXX'
This returns a payload detailing which Bids were accepted or rejected for this particular Competition.
Since this is an API, and there is a non-defined period of time after a Competition closes and the System Operator provides a decision on the Bids, you will need to poll this endpoint. Please do this respectfully, we suggest no more than once a day would probably be sufficient.
b. Via Webhook
Coming soon👷🏗️