Gobierno de España. Ministerio de Hacienda y Función Pública. Abre nueva ventana
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

Access and use of the service

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.

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.
Naturally, CoFFEE will perform the same validations when the information is provided in bulk by uploading a file.

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

The encoding is UTF-8.

Access and use of the service

How do I request access to the API and what procedure does it trigger?

Access to the API can be requested via the "Request this web service" option of the web service "CoFFEE-MRR Exchange Service" in the Web Service Catalogue of the Budget Management Portal, as soon as the service is announced as available.
The procedure can be summarised as follows:
1. The person responsible for the system to be integrated with CoFFEE requests access; during the process the electronic certificate to be used for secure communication is specified.
2. A CoFFEE functional manager at the Secretariat General for European Funds (SGFE), after verifying the legitimacy of the applicant, approves the authorisation.
3. A "service user" code is assigned by the technical services of the Budgetary Informatics Office. In cooperation with the SGFE, an access profile is assigned within CoFFEE for that service user, which determines the scope of information which can be worked on through the electronic exchange.
4. The technical contact of the system to be integrated with CoFFEE is provided with the service user code (called "idUser"), as well as a code identifying the service itself ("idApplication"), to be kept for future uses of the service.

How is secure access achieved?

Client Web services shall be authenticated via HTTPS/TLS (1.2 or higher). Specifically, an Administration, public law entity or body seal certificate shall be used for automated administrative actions, or a qualified electronic seal certificate derived from the eIDAS Regulation, issued in any case by any of the certification service providers recognised by the @Firma service.

During the organisational process of access authorisation, the certificate to be used by the client end of the service is agreed between the Office of Budgetary Informatics and the technical contact of the agency concerned

What does a typical interaction with the service (a call to an API method) look like?

Once the access authorisation process has been completed, the client system is ready to use the service. For this purpose, all interaction will be carried out under secure communication (TLS) using the pre-agreed seal certificate.
Each call to the REST service shall include in the HTTP request, in addition to the parameters indicated in the documentation of the service itself, two additional parameters (idUser and idApplication), containing the values provided during the access configuration process.

Can multiple organisations use the same seal certificate to interact with the API?

Although unusual, this possibility is enabled if two access requests are processed, one for each of the organisations, and the same certificate is configured in both. In the authorisation process, a different service user (idUser) will be created and assigned to each of them, and the corresponding profiles acting in each of the domains will be configured in CoFFEE.
Since each request to the service includes among its parameters the service user code (idUser), CoFFEE will be able to determine the origin and will be able to act accordingly, applying the corresponding security profile.
Notwithstanding the above, it should be noted that if one of the organisations were to use the idUser assigned to the other, there would be no mechanism to identify the impersonation, so this option will be at the risk of the client organisations.

Are there limits on the use of the service?

The following limits have been defined:
  • Maximum request size: 100MB.
  • Maximum document size: 60MB.
  • Maximum number of items in a collection: 100 items.
  • Number of requests per minute: to be established.

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.
It is important to note that some requested dates must be specified in quarters.

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.

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.

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 reference of a legal instrument?

Declarations of accounting performance specify a reference to the legal instrument under which the declaration is made. The typical case is a contract or a grant, but all envisaged instruments must be identifiable.
The reference is therefore a code identifying the specific legal instrument within the scope of the Action for which the execution is registered.
Usually the reference coincides with the instrument code itself, which is established by the person who registers it in CoFFEE (by screen, bulk upload, ...).
For example, in the case of a grant registered in CoFFEE with the BDNS code "576282", the reference is exactly the same code. Or a contract (non-PLACSP) that has been registered in CoFFEE with the contract code "2023OIP45544", will have the same code as a reference.
However, there is the more complex case of PLACSP contracts, which is specifically addressed in the next question.

How is a contract that is registered on the Public Procurement Platform (PLACSP) differentiated from one that is not?

PLACSP contracts are identified by three codes: contracting authority code, tender code, and contract code (see next question for a detailed explanation). Non-PLACSP contracts are identified by a unique code.
In the contract registration entries in CoFFEE, the two types of contracts are identified separately.
Since references to legal instruments are made through a single field, in the case of PLACSP contracts (which, as indicated above, have three codes) the reference corresponds to the concatenation of the three values using the separator "~" between them, even if the fields were empty.

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.

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?

Yes, it is necessary for third parties to be registered in CoFFEE prior to the submission of accounting information. The API provides the necessary services.

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?

Yes, it is necessary for third parties to be registered in CoFFEE prior to the submission of accounting information. The API provides the necessary services.

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

Amounts in deleted 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.

Notable changes from v1.3.1 to v1.5

The highlighted changes are listed according to the type of data:
  • All types:
    • codigoInitiativa is now codigoActuation
  • Measurement:
    • fechaInicio its value is a quarter
    • fechaFin its value is one quarter
  • Contract:
    • contratoPLACSP is now Instrument code, Tender code and Body code
    • contratoNoPLACSP is now codigoInstrumento
  • Subsidy:
    • convocatoriaBDNS is now codigoInstrumento
  • Initiative:
    • Separated into Project, Subproject, Subproject-Instrumental and Action.
    • fechaInicio its value is a quarter
    • fechaFin its value is one quarter
  • DeclaracionFinanciera
  • DeclaracionProgresoIndicador
    • codigoInitiative now called codigoOrigenProgreso
As a general rule, missing fields do not need to be reported.

Notable changes from v1.5.0 to v1.5.1

  • Path:
    • The POST path /execution/other-instruments/targets has been updated
    • The detailed routes of a legal instrument have been updated. The {reference} parameter becomes a query parameter. For example, GET /structure/proceedings/{code}/agreements/{reference} becomes GET /structure/proceedings/{code}/agreements/details?reference={reference}
  • Performance:
    • The field transferenciaDeRecursosEconomicosAOtroSubproyecto for Action has been made optional.
    • The hitosObjetivosCriticos field has been added to Action.
    • The type of the resourcesEconomics for Action field has been updated.
  • Subproject:
    • The field costeEstimado of recursosEconomicos of Subproject has been removed.
  • SubproyectoInstrumental:
    • The field costeEstimado of recursosEconomicos of SubproyectoInstrumental has been removed.

Notable changes from v1.5.1 to v1.5.2

  • codigoPropietario The codigoPropietario parameter becomes optional in the following routes:
    • /v1.5/estructura/proyectos
    • /v1.5/estructura/subproyectos
    • /v1.5/estructura/subproyectos-instrumentales
    • /v1.5/estructura/actuaciones

    If not included, the list shall contain all items of the corresponding type to which the user has access.

  • project Sub-projects, instrumental sub-projects and actions include a summary of the project to which they belong (propiedad proyecto).

General questions about API v2.0

How do I obtain the unique code of a legal instrument?

The unique code of a legal instrument is obtained in three ways:
  • Registration of legal instrument: the unique code assigned to the legal instrument is returned in the response of the registration operation. For example: POST /v2.0/contratos
  • Consultation of legal instruments of an action: the list of legal instruments includes the unique code of each legal instrument. GET /v2.0/proceedings/{code}/juridical-tools
  • Unique code query: there is a utility to obtain the unique code of a legal instrument from the action code and the reference of the legal instrument. GET /v2.0/instrumentos-juridicos/utilidades/codigo-unico

How do I upload documents?

There are two steps to uploading documents:
  • Document upload: A new document is added to the system and the locator required for further operations is obtained. The document is created with the type PENDING. Uploaded documents not associated with an item will be deleted periodically. The service used is: POST /v2.0/documents
  • Association of the document with an element: The document uploaded in the previous point is associated to an element. The association indicates the document location, the effective type and additional metadata. The service used depends on the element, e.g. to add a document to a contract, the service is: POST /v2.0/contratos/{codigo-unico}/documentos.
If you want to associate the same document to several elements, you only need to upload the document once and you can use the locator as many times as necessary.

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.