FAQs about the API

Preliminary Information

• What is CoFFEE and CoFFEE-MRR?
• How to apply to access CoFFEE/CoFFEE-MRR?

Availability of the API

• What is the CoFFEE API for?
• Is the REST API already available to connect to?
• What is the latest version available?
• How to request access to the API?
• How do I obtain the access security token provided by the Budgetary Information Technology service (TokenserSeguro), which is necessary for the e-services connection to the CoFFEE API?
• Are there alternative mechanisms to the API for providing information to the platform?
• How do I upload the JSON file to the CoFFEE platform?
• Who has to upload the file or files to the platform?
• What format is used for sending information
• What is the encoding format of the JSON file that is loaded into CoFFEE?

General questions about the API

• What is the format of the dates?
• Are all API fields mandatory?
• Can I send multiple financial statements in the same POST call?
• What do I enter in the administration section?
• What is the initiative code and how do I obtain it?
• What is the indicator code and how do I obtain it?
• Regarding indicator progress statements: does the "date" field (the progress reference date) have to be the current date?
• ¿Why is "change" reported for quantitative indicators and "value" for qualitative indicators?
• ¿What is the "justification" field and how to fill it in?
• Concerning the accounting execution reports: can the field "accounting date" (The reference date of the progress) be a date that falls after the current date?
• What is the BDNS call-up code?
• What are the PLACSP contracting authority, tendering authority and contract codes?
• When is the "Other sources of financing" field completed?
• Do I have to report the accounting execution report (annex I of Order HFP/1031/2021) and milestone/objective achievement (section three of Order HFP/1031/2021) in a single file?
• Can I report MRR funding for several years in the same file?
• In the definition of the API, the "Initiative code (Implementation of the Plan)" is indicated as a field to be completed in the case of sending accounting information. According to Order HFP/1031/2021, accounting monitoring is at the action level. Are these two concepts similar?
• In the definition of the API, the "Initiative code (Implementation of the Plan)" is indicated as a field to be completed for sending accounting information, while for sending information on the achievement of milestones/objectives, "Code of the initiative (the most disaggregated level in the structure) in which the progress of the indicator has taken place" is indicated. Why is this?
• In the case of sending accounting information: Do the contracts/grants to be included have to be registered in CoFFEE prior to the submission of information?
• In the case of sending accounting information, do the third parties (beneficiaries, contractors, etc.) to be included have to be registered in CoFFEE prior to sending the information?
• In the case of "barred" accounting phases (A/, D/, O/, AD/, ADO/, PR/, RE/), are the amounts to be shown positive or negative?
• Once the accounting execution or indicator progress information has been sent: Will I receive any acknowledgement of receipt?

Preliminary Information

What is CoFFEE and CoFFEE-MRR?

Availability of the API

What is the CoFFEE API for?

Is the REST API already available to connect to?

The availability of the API is shown in the CoFFEE "Exchange formats" space in the Information Systems Catalogue.

What is the latest version available?

The different versions and their status are available in the CoFFEE "Exchange Formats” space in the Information Systems Catalogue.

How to request access to the API?

Access to the API can be requested via the "Request this web service" option of the "CoFFEE Exchange Service" web service in the Web Services Catalogue on the Budget Administration Portal. 

How do I obtain the access security token provided by the Budgetary Information Technology service (TokenserSeguro), which is necessary for the e-services connection to the CoFFEE API?

Once authorised to use the API, the procedure for integrating with Tokenser and obtaining the token is described in the document Procedure for requesting access by external entities to the Budgetary Information Technology (pdf), in the Web Services Catalogue on the Budget Administration Portal.

Are there alternative mechanisms to the API for providing information to the platform?

Are all API fields mandatory?

No, only those fields that are marked as such (with a red asterisk) are mandatory.

Can I send multiple financial statements in the same POST call?

Yes, each call can contain as many statements as you wish from the same taxpayer (a single taxpayer), as specified in the "Declaration of Enforceability" data type of the schema.

What do I enter in the administration section?

This is the DIR3 code of the administration to which the taxpayer belongs (highest level of the DIR3 hierarchy), therefore the DIR3 code of the General State Administration, Autonomous Communities, city council, ...

What is the initiative code and how do I obtain it?

"Initiative" is the term used to refer generically to any element of the structure on which information can be obtained or provided (component, measure, project, sub-project...). When the downstream elements of PRTR measures (projects, sub-projects...) have passed the approval cycle according to the methodology established in the Order HFP/1030/2021, the CoFFEE system will assign them a definitive code.

The code of the initiative can be obtained through the API itself or by accessing CoFFEE interactively. For example, you can obtain the list of measures of the plan through the GET structure/measures method and once you have the code of the measure, you can obtain the projects related to it with a GET /structure/measures/{code}.

Alternatively, and especially in the early stages of production, the Secretariat General of European Funds itself could provide the codes assigned to the elements.

What is the indicator code and how do I obtain it?

The indicator code can be obtained through the API itself or by accessing CoFFEE interactively. For example, with the GET/structure/indicators method you get the list of indicators of a plan element.

Regarding indicator progress statements: does the "date" field (the progress reference date) have to be the current date?

The progress reference date of an indicator is the date on which the value of the indicator being updated is considered to have been reached, and therefore must be the current date or before, i.e. no future dates are allowed.

Why is "change" reported for quantitative indicators and "value" for qualitative indicators?

Indicators are measures of progress and can be quantitative (their value is a numeric figure within a range) or qualitative (they can take a value from a closed set of options)

• In the case of quantitative indicators, the change since the previous value of the indicator should be reported. For example, if the indicator is "Number of electric vehicles registered" and the indicator has changed from 1000 to 3000 vehicles, it should be reported "2000” vehicles.

• In the case of qualitative indicators, the new value taken from the possible ones (start, in progress and finished) must be reported.

The reason why the variation is provided for quantitative indicators is that the system allows for a justification (textual and, optionally, accompanied by files). It is understood that at the time of declaration, the increased (or decreased) value of an indicator is being justified, and not the final value achieved (in the example above, the 2000 vehicles that have been registered are justified).

In the case of qualitative indicators, there is a change in their status, and therefore the status achieved is declared.

What is the "justification" field and how to fill it in?

This is an optional field, in case you would like to attach a text and one or more documents or files justifying the information provided.

Concerning the accounting execution reports: can the field "accounting date" (The reference date of the progress) be a date that falls after the current date?

The accounting date must be the current date or before, i.e. no future dates are allowed.

What is the BDNS call-up code?

The BDNS call code is provided by the BDNS itself in the response to the manager when it is declared and must therefore be known by the latter. It is currently a sequential value of 6 digits, and may go up to 7 digits in the future.

What are the PLACSP contracting authority, tendering authority and contract codes?

El The contracting authority code is an identifier used by the Public Sector Contracting Platform (PLACSP) associated with each contracting authority (in PLACSP it is called "Platform ID"). Each contracting body can consult its own in the administrator screen of the PLACSP "contracting body administrator" profile.

 

In addition, the Directorate-General for State Assets periodically publishes the list of codes in an Excel sheet that they update.

In the case of PLACSP and for each contracting body, the tender and contract codes are those that uniquely identify a contract that is incorporated into the Public Sector Procurement Platform:

The tender code corresponds to the File Number in the PLACSP, which is that provided by each contracting body.

The contract code corresponds to the Contract in the PLACSP. It is also a value determined by the contracting authority. It corresponds to each contract within the dossier.

In any case, both are values provided by the manager to the PLACSP. Both can be seen in the following image.

 

When is the "Other sources of financing" field completed?

Data on other sources of information will be filled in when the action to which the operation corresponds is financed by some other source, in addition to the funding from the Recovery and Resilience Facility. In this case, the mechanism or fund that has financed the operation shall be identified.

Do I have to report the accounting execution report (annex I of Order HFP/1031/2021) and milestone/objective achievement (section three of Order HFP/1031/2021) in a single file?

The format has been defined in such a way that it can be used both at the present time for sending the information on the implementation of the 2020 financial year, as well as that of 2021, and subsequent implementation, and also for the declaration of the progress of indicators, both on file and via the electronic services. That is why the scheme includes all data structures. There is no obligation to submit all of it simultaneously, as reflected in the schema as the elements are optional. In fact, it will normally be submitted separately, since the information will most likely come from different systems: the information on the progress of indicators, from the management system, and that on accounting performance, from the accounting system.

Can I report MRR funding for several years in the same file?

Yes, the JSON format allows nesting and allows several occurrences of the field "financingMRR” to be sent in the same file:

"financingMRR": [

{ "annuity": 2021, "chapter": "6", "amount": 100,000.00 },

{ "annuity": 2022, "chapter": "6", "amount": 23,000.00 }]

In the definition of the API, the "Initiative code (Implementation of the Plan)" is indicated as a field to be completed in the case of sending accounting information. According to Order HFP/1031/2021, accounting monitoring is at the action level. Are these two concepts similar?

In the case of sending accounting information, as indicated in Order HFP/1031/2021, each accounting operation will be associated with an action, so code Initiative corresponds to the code of that action.

In the definition of the API, the "Initiative code (Implementation of the Plan)" is indicated as a field to be completed for sending accounting information, while for sending information on the achievement of milestones/objectives, "Code of the initiative (the most disaggregated level in the structure) in which the progress of the indicator has taken place" is indicated. Why is this?

The Secretariat General of European Funds, as Authority Responsible for the Plan, determined that the accounting is recorded at the Action level, while the remission of information on the progress of the indicators will be done at the last level of decomposition of each project by lines of action (action, activity or task), all in accordance with Order HFP/1031/2021.

For the purposes of the system, the term "initiative" is used generically.

 

In the case of sending accounting information: Do the contracts/grants to be included have to be registered in CoFFEE prior to the submission of information?

If, when making a execution report, there is no contract associated with the action, the one specified will be assigned at that moment. If there was already an associated contract, and it is not the same, then an error will be returned.

Notwithstanding the above, it is possible that in the future more than one contract or grant associated with the same action may be admitted.

In the case of sending accounting information, do the third parties (beneficiaries, contractors, etc.) to be included have to be registered in CoFFEE prior to sending the information?

If there is no third party associated to the contract/grant when making a declaration of execution, the specified third parties will be assigned at that moment.

On the other hand, the services provide operations to provide grant beneficiaries as well as contractors and subcontractors to grants and contracts, respectively, after their registration in the system

In the case of "barred" accounting phases (A/, D/, O/, AD/, ADO/, PR/, RE/), are the amounts to be shown positive or negative?

No. Amounts in swept documents are always positive; the slash already indicates that the amounts will be treated as negative for accounting purposes.

Once the accounting execution or indicator progress information has been sent: Will I receive any acknowledgement of receipt?

Yes, the system will provide an electronic acknowledgement of receipt to allow traceability of transactions.