Gobierno de España. Ministerio de Hacienda y Función Pública. Abre nueva ventana Secretaría de Estado de Presupuestos y Gastos
Administración Presupuestaria

FAQs about the API

FAQs on the electronic information exchange services for the Recovery, Transformation and Resilience Plan.

Preliminary Information

Availability of the API​​

General questions about the API

Preliminary Information

What is CoFFEE and CoFFEE-MRR?

CoFFEE (Common Platform for European Funds) is the common IT platform for the management of European funds. It is aimed at integrating the various modules that support the management of European funds under the responsibility of the Secretariat General for European Funds (SGEF) in the multiannual financial framework 2021-2027 (MFF 21-27). It is the evolution of the information systems that support the management of the European Regional Development Fund (ERDF) in the financial frameworks prior to 2021-2027, but has been designed to support other funds and/or mechanisms.
CoFFEE-MRR is a CoFFEE module that takes advantage of the platform's technology, cross-cutting processes, information incorporation mechanisms, etc., and incorporates the necessary functionality for the planning, management and monitoring of the initiatives associated with the Recovery and Resilience Mechanism, and specifically the Recovery,Transformation and Resilience Plan (RRRP).

How to apply to access CoFFEE/CoFFEE-MRR?

The procedure for requesting access to the Budget Administration systems is described in the "Access Control" section of the Budget Administration Portal.

Availability of the API

What is the CoFFEE API for?

The electronic services are put into operation to make it easier for the entities executing the initiatives to comply with the provisions of the regulations governing the Plan, and in particular Order HFP/1030/2021, of 29 September, which sets up the management system of the Recovery, Transformation and Resilience Plan (Management Order), as well as Order HFP/1031/2021, of 29 September. The latter establishes the procedure and format for the information to be provided by the State, Autonomous Community and Local Public Sector Entities for monitoring compliance with the milestones and objectives and budget execution and accounting of the measures of the components of the Recovery, Transformation and Resilience Plan (Exchange Order). It is aimed at entities that have the capacity and resources to connect their own management systems with CoFFEE to provide the required information.
Entities that do not have this capacity can incorporate the information interactively, for which they must first request access.

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?

Yes, depending on the type of information to be reported, the system will provide mechanisms for the information to be provided interactively by the users who connect to it, and also through the (interactive) incorporation of a file with all the data to be processed.​
The format of the file to be incorporated for each operation is the same as the schema set out by the API for the same operation.
If you wish to check the file against the schema before submitting it to the platform, this can easily be done using an online JSON document validation tool.
  • On the left side of the main screen, copy the complete content of the document with the schema.
  • On the right side, copy the content of the JSON document to be validated.
Of course, CoFFEE will perform the same validations when uploading the file.

How do I upload the JSON file to the CoFFEE platform?

This option is not yet available on the platform. The Secretariat General for European Funds will notify you via the website, if this has not been done by other means, when this option for uploading accounting files is available.

Who has to upload the file or files to the platform?

If the information is uploaded in bulk using a file instead of using the electronic services, the information will be uploaded by the executing entity itself.​

What format is used for sending information?

The format chosen for the exchange of information is JSON, whose characteristics make it possible to provide structured information in a much more flexible way than an exchange based on textual information with separators (CSV) or similar.​
The JSON specification can be found on the website of the ECMA, an organisation founded in 1961 to standardise computerised systems in Europe. The ​JSON organisation's website includes a brief reference to the format, as well as links to utilities, libraries and tools that facilitate the editing and processing of JSON.
JSON files can be validated against a schema to validate the data they contain.

What is the encoding format of the JSON file that is loaded into CoFFEE?

The encoding is UTF-8.

General questions about the API​

What is the format of the dates?

The OpenApi 3.0 specification is followed which refers to the RFC 3339 definition, section 5.6​, for example 2022-07-21.

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.
PLACSP1.PNG 
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.
PLACSP2.PNG  

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.​

Other concerns

I have functional doubts about the management of the Recovery, Transformation and Resilience Plan and its management system, where can I go?

The description of the functioning of the Plan is articulated in two Ministerial Orders:
  • Order HFP/1030/2021, of 29 September, which sets up the management system of the Recovery, Transformation and Resilience Plan.
  • Order HFP/1031/2021, of 29 September, which establishes the procedure and format of the information to be provided by the State, Autonomous and Local Public Sector Entities for monitoring compliance with milestones and objectives and budgetary and accounting execution of the measures of the components of the Recovery, Transformation and Resilience Plan.

I have further technical queries related to the API. Where can I address them?

For all other technical queries about the CoFFEE REST API, you can write a message to the support email address CoFFEE-Desarrollo@igae.hacienda.gob.es
This mailbox will only deal with technical queries related to the exchange of information with the platform.