Public API

---

The public API is the only interface to use the Central Business Process Engine that is the core unit of infrastructure. The API is a CQRS interface that provides programmatic access to BPE. It provides predictable URLs for accessing resources, and uses built-in HTTP features to receive commands and return responses. This makes it easy to communicate with. The API accepts JSON or form-encoded content in requests. It returns JSON content in all of its responses, including errors.

CQRS approach

In traditional architectures, the same data model is used to query and update a database. That's simple and works well for basic CRUD operations. In more complex applications, however, this approach can become unwieldy. For example, on the read side, the application may perform many different queries, returning data transfer objects (Data Transfer Objects or DTOs) with different shapes. Object mapping can become complicated. On the write side, the model may implement complex validation and business logic. As a result, you can end up with an overly complex model that does too much. Another potential problem is that read and write workloads are often asymmetrical, with very different performance and scale requirements.

Command and Query Responsibility Segregation (CQRS) - an architecture which addresses these problems by separating reads and writes into separate models, using commands to update data, and queries to read data.

• Commands should be task based, rather than data centric. Commands may be placed on a queue for asynchronous processing, rather than being processed synchronously.
• Queries never modify the database. A query returns a DTO that does not encapsulate any knowledge.

Compared to the single data model used in CRUD-based systems, the use of separate query and update models for the data in CQRS-based systems simplifies design and implementation.

For greater isolation, the read and the write data could be physically separated. In that case, the read database can use its own data schema that is optimized for queries. For example, it can store a materialized view of the data, in order to avoid complex joins or mappings. It might even use a different type of data store. If separate read and write databases are used, they must be kept in sync. Typically this is accomplished by having the write model publish an event whenever it updates the DB.

Command API

This section explain how the interfaces to the provided services are called.

Request example

All requests for Form Service are use POST-method (same as for parent Operation Service)

Specific Params

Set of specific parameters required in particular case. Described below.

Response examples

For all valid queries, the response will have a common structure:

For all invalid queries, the response will have a common structure:

Activities

This section describes the array of activities that can be performed through the API in each of the processes stages.

Budgeting

Budgeting is a stage where CA should assess and define the scope of his needs as well as disclose and describe existing fundings for each defined need. With this description CA will allow system to validate all future contracting processes from assessed needs and available funding perspective as well as control and disclose the progress of execution of this or that expenditure item, analyzing planned and announced procedures, conducted and executed or/and terminated contracts and made transactions.

All needs could be divided into separate expenditure items - groups of needs united under common classification and procuring period for each specific buyer. For example: buyer needs to procure 25 different kinds of furniture (on this stage - doesn't matter which exactly) during next year - all these needs are expenditure item «Furniture» under CPV-code 391. Thus, from technical point of view such groups, expenditure items, are aggregated data-sets, based on common CPV-code and budget period (most often - year). Each defined expenditure item, on a annual financial plans’ level, has available fundings. Thus, next step of budgeting is description of such available fundings. The ‘amount’ available under this expenditure item for this period is the sum of all sources of funding and its amounts, identified for this expenditure item.

Expenditure Item (EI)

Create ei

country

Identifier of country of jurisdiction according to ‘country’ codelist

Update ei

ocid	OCID of EI to be updated

Funding Source (FS)

Create fs

ocid	OCID of parent EI

Update fs

ocid	OCID of parent EI
fs-ocid	OCID of FS to be updated

Planning

Once the EI and its FSs defined and described, CA is able to plan and schedule needed procurements - contracting processes for this subject classification - CPV group. Particular EI should be indicated as a ground (meta-parent) of future contracting process. Then, depending of CAs procurement strategy, Periodic Notice or Prior Information Notice could be prepared and published. Within this notice (PN or PIN) allocated by CA himself budget must be specified as a set of identified from the list of available under used EI funding sources together with allocated amounts - separate for each selected FS. The sum of all specified amounts of all indicated funding sources is a budget of future contract that will be conducted under this contracting process.

Planning Notice (PN)

Create pn

country	Identifier of country of jurisdiction according to ‘country’ codelist
pmd	Identifier procurementMethodDetails according to ‘pmd’ codelist

Update pn

ocid	OCID of parent Contracting Process
pn-ocid	OCID of PN to be updated

Announcement

Depending on type of procedure, method of procurement, geography and the legal basis, the attribute composition of the model can be adjusted, but its general logic remains unchanged for all types of procedures. The contracting process based on competitive procedure is commonly carried out in the following sequence:

Business Process Diagram

Creating a tender, CA determines key fields of the yet-to-be announced procurement, uploads tender documentation, with the requirements to the procurement object indicated as that which determines winner evaluation criteria.

Contract Notice (CN)

Create cn

country	Identifier of country of jurisdiction according to ‘country’ codelist
pmd	Identifier procurementMethodDetails according to ‘pmd’ codelist

Create cn based on pn

ocid	OCID of parent Contracting Process
pn-ocid	OCID of PN to be updated

Update cn

ocid	OCID of parent Contracting Process
cn-ocid	OCID of CN to be updated

Clarification

Clarification period is separately distinguished in the procurement procedure during which participants can ask questions regarding the procurement requirements, demand issue resolution, and submit a claims, while CA can provide answers to questions and introduce changes into the procurement conditions. The duration of the clarification period and offer submission is determined by CA but in any case can not be less than those, prescribed by Law.

Create enquiry

ocid	OCID of parent Contracting Process
cn-ocid	OCID of CN to be updated

Create answer

ocid	OCID of parent Contracting Process
cn-ocid	OCID of CN to be updated
enquiry-id	ID of parent enquiry

Submission

Once the clarification period is over the CA can no longer introduce changes into the Contract Notice. Economic Operators submit offers that are confidential.

Create bid

ocid	OCID of parent Contracting Process
cn-ocid	OCID of CN to be updated

Update bid

An Economic Operator may modify its electronic bid by submitting online within submission deadlines a new information regarding previously submitted offer in accordance to the electronic submission procedures.

ocid	OCID of parent Contracting Process
cn-ocid	OCID of CN to be updated
bid-id	ID of the bid

Update winning bid

ocid	OCID of parent Contracting Process
cn-ocid	OCID of CN to be updated
bid-id	ID of the bid

Withdraw bid

An Economic Operator may withdraw his electronic bid by submitting online within submission deadlines a request for cancellation of previously submitted offer.

ocid	OCID of parent Contracting Process
cn-ocid	OCID of CN to be updated
bid-id	ID of the bid

Awarding

Once the submission period is over and participants can not longer submit or update their bids, system will disclose all submitted bids, generate set of qualification envelopes (awards) and launch the awarding period for this contracting process. System will automatically verify eligibility (based on available via external bus data) of each tenderer whose bid was disclosed according to rules of dispatch under current procurement method.

Those bids that have been passed eligibility check, will go to the technical qualification. All the other that failed go to automatic exclusion. In case if after submission period end there is nothing to disclose (no bids were submitted) or all submitted bids failed, system will automatically change this specific lot of this contracting process to status “unsuccessful”.

Create award

ocid	OCID of parent Contracting Process
cn-ocid	OCID of CN to be updated

Update award

CA sequentially reviews bids that are eligible considering its technical compliance, beginning with first, suggested by the system. Depending on award criteria (priceOnly/costOnly/MEAT) system will rank eligible bids and suggest them in order of admissibility: from the most to the least acceptable by applicable criteria. If the most acceptable bid is in compliance with the CA’s technical requirements, CA determines this offer as a qualified and goes to next step - financial evaluation. If it is not, CA confirms his decision to disqualify the participant, and declines such an offer. Then the system suggests to qualify the next offer from the acceptance perspective.

If qualified offer is in compliance with the CA’s financial requirements, CA determines this offer as a winner. If it is not in compliance, CA confirms his decision to disqualify the offer on this (evaluation) stage, and declines such an offer. Then the systems suggests to qualify the next offer  from the acceptance perspective.

If all the offers were declined by CA either on qualification step or on evaluation one and upon the completion of complaining process (review period) this specific lot of this contracting process automatically changes to ‘unsuccessful’.

ocid	OCID of parent Contracting Process
cn-ocid	OCID of CN to be updated
award-id	ID of award to be updated

Submit awarding protocol

Once winner is selected for each lot, CA submits the evaluation protocol which, in its turn, indicates the end of awarding process. As a result of submission of evaluation protocol, system will automatically generate a set of Submission for each awarded lot, change evaluation stage to ‘awarded’ and launch the complaining process - review period.

ocid	OCID of parent Contracting Process
cn-ocid	OCID of CN to be updated
lot-id	ID of the parent lot

Update Contract Award Notice

ocid	OCID of parent Contracting Process
cn-ocid	OCID of CN to be updated
can-id	ID of the CAN to be updated

Confirm Contract Award Notice

ocid	OCID of parent Contracting Process
cn-ocid	OCID of CN to be updated
can-id	ID of the CAN to be updated

Cancel Contract Award Notice

ocid	OCID of parent Contracting Process
cn-ocid	OCID of CN to be updated
can-id	ID of the CAN to be updated

Contracting 

Create awarded contract

ocid	OCID of parent Contracting Process
ac-ocid	OCID of the contract to be updated

Update awarded contract

ocid	OCID of parent Contracting Process
ac-ocid	OCID of the contract to be updated

Issue contract to be approved

ocid	OCID of parent Contracting Process
ac-ocid	OCID of the contract to be issued

Approve contract

ocid	OCID of parent Contracting Process
ac-ocid	OCID of the contract to be approved
request-id	ID of initial

Activate approved contract

ocid	OCID of parent Contracting Process
ac-ocid	OCID of the contract to be activated

Cancel awarded contract

ocid	OCID of parent Contracting Process
ac-ocid	OCID of the contract to be cancelled

Query API

Public Point is a service that displays records and data-sets in read-only mode. Only information allowed for publication by the current legislation is displayed (i.e. it does not show bids of the bidders until the opening session (disclosure) of the bids.

AccessPoint

All of the document uploading API endpoints follow the same set of rules and uses single access point.

Flow Description

Retrieving data

To retrieve a list of data or individual entity data-set use GET-request parameterized with one or more options sent to corresponding end-point.

• offset - timestamp of latest updates
• limit - quantity of elements per each package of data
• order - criteria for sorting results

Getting list of all data

By default all data returned from public point are sorted by modification time (from oldest to newest).

Limiting number of Tenders returned

You can control the number of data entries in the entity feed (batch size) with limit parameter. If not specified, data is being returned in batches of 100 elements.

Batching

The response contains ‘offset’ element. This is the parameter you have to add to the original request you made to get next page. If next page request returns no data (i.e. empty array) then there is little sense in fetching further pages.

Synchronizing

It is often necessary to be able to synchronize changes of Central Unit with local database. The default sorting “by modification date” together with Batching mechanism allows one to implement synchronization effectively. The synchronization process can go page by page until there is no new data returned. Then the synchronizer has to pause for a while to let Central Unit register some changes and attempt fetching subsequent page.

Getting individual entity information

To get a individual entity data set (as Record Package) provide your GET-request with unique ID of particular entity: