Preliminary information
Availability of the IPR
Connection and use of the service
Preliminary information
What is CoFFEE and CoFFEE-MRR?
CoFFEE (Common European Funds Platform) is the common IT platform for the management of European funds. It aims to integrate the various modules supporting the management of European funds under the competence of the General Secretariat of European Funds (SGFE) into 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 it has been designed to support other funds and/or mechanisms.
CoFFEE-MRR is a CoFFEE module that leverages technology, cross-cutting processes, information incorporation mechanisms, etc. the platform, which incorporates the necessary functionality for planning, managing and monitoring initiatives associated with the Recovery and Resilience Mechanism, and in particular the Recovery, Transformation and Resilience Plan (PRTR).
How do I request access to CoFFEE/CoFFEE-MRR?
The procedure for requesting access to Budget Administration systems is described in the
“Access Control” section of the Budget Administration Portal.
Availability of the IPR
What is the purpose of the CoFFEE API?
The electronic services are put into operation to facilitate the executing entities of the initiatives to comply with the provisions of the regulations that regulate the Plan, and in particular in Order HFP/1030/2021, of September 29, which establishes the management system of the Recovery, Transformation and Resilience Plan (Order of Management), and Order HFP/1031/2021, of September 29, which establishes the procedure and format of the information to be provided by the State, Autonomous and Local Public Sector Entities for the monitoring of the compliance of the milestones and the transformation plan.
Entities that do not have this capability can incorporate the information interactively, for which they must first request access.
Is the REST API already available to connect me?
Yes, yes, yes. The implementation status of the different endpoints can be consulted at:Status of endpoints. . . . . .
List of versions
| Date and place | Version | Environment | Link to the API | New developments |
|---|
| May 2025 | 2.0.8. | Production | Link to version 2.0.8 | New endpoint for the edition of amounts of legal instruments |
| April 2025 | 2.0.7. | Production | Link to version 2.0.7 | New endpoint for differential editing of progress report |
| April 2025 | 2.0.6. | Production | Link to version 2.0.6 | Adaptation to functional changes of CoFFEE |
| April 2025 | 2.0.5. | Replaced by v2.0.6 | Link to version 2.0.5 | Adaptation to functional changes of CoFFEE |
| February 2025 | 2.0.4 Number of cases | Replaced by v2.0.5 | Link to version 2.0.4 | Adaptation to functional changes of CoFFEE |
| December 2024 | 2.0.3. | Replaced by v2.0.4 | Link to version 2.0.3 | New legal instruments: Direct financial instruments, indirect financial instruments, implementing agreements, intermediation agreements. |
| October 2024 | 2.0.2. | Replaced by v2.0.3 | Link to version 2.0.2 | Definition of services for the recording of progress of indicators. Definition of the services for the consultation of (non-) revocation certificates. |
| June 2024 | 2.0.1. | Replaced by v2.0.2 | Link to version 2.0.1 | Definition of services for the discharge of actions, instrumental sub-projects, sub-projects and projects. Definition of services for the recording of progress and monitoring of indicators. |
| March 2024 | 2.0.0 The Commission | Replaced by v2.0.1 | Link to version 2.0.0 | |
| May ;2025 | 1.5.3 The Commission | Production | Link to version 1.5.3 | The methods of registration of recipients are declared obsolete. |
| March 2024 | 1.5.2 Duration: 1.5.2 | Production | Link to version 1.5.2 | Optional owner-code parameter in some listings and project information in sub-projects, instrumental sub-projects and actions. |
| January 2024 | 1.5.1 The Commission | Replaced by v1.5.2 | Link to version 1.5.1 | Adaptation of the definition of services to the functional changes of CoFFEE. Correction of errors. |
| November 2023 | 1.5.0 Number of cases | Not implemented | Link to version 1.5.0 | Adaptation of the definition of services to the functional changes of CoFFEE. |
| April 2022 | 1.3.1. | Not Implemented | Link to version 1.3.1 | Progress statements for indicators (possible values for qualitative indicators are also limited) and financial performance statements are treated separately. Finally, the accounting documents DO and DO/ are included. |
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 connecting to it, and also by incorporating (interactively) a file with all the data to be processed.
Naturally, CoFFEE will perform the same validations when the information is provided in bulk through the loading of a file.
What is the coding format of the JSON file that is uploaded to CoFFEE?
Connection and use of the service
How do I request access to the API and what procedure does it trigger?
If you want to integrate an external management application with CoFFEE, you should refer to the document with the instructions for compliance with the authorization to update information in CoFFEE using APIs.
The procedure can be summarized in these points:
2.La OIP will contact the requesting technical department through the mailbox CoFFEEDesarrollo@igae.hacienda.gob.es indicating the user who identifies the management application.
3.Los responsible for node information (PRTR projects, subprojects and instrumental subprojects) authorize the user who identifies the management application that serves them to access and edit node data.
4.El departmentally technical applicant sets up the electronic certificate to be used for secure communication.
How is access security achieved?
Client Web services will be authenticated via HTTPS/TLS (1.2 or higher). In particular, a certificate of seal of Administration, body or entity of public law will be used for automated administrative action, or a qualified electronic seal certificate derived from the eIDAS Regulation, issued in any case by one of the certification service providers recognized by the @Marca 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 Information and the technical contact of the body concerned.
How is a typical interaction with the service (a call to an API method)?
Once the access authorisation process has been completed, the client system is in a position to make use of the service. To this end, any interaction will be carried out under a secure communication (TLS) using the pre-agreed seal certificate.
Each call to the REST service will include in the HTTP request, in addition to the parameters indicated in the documentation of the service itself, two additional parameters (idUser and idApplication), which will contain the values that were provided during the access setup process.
Can several organizations use the same seal certificate to interact with the API?
Although it is not usual, this possibility is enabled if two access requests are processed, one for each of the organizations, and the same certificate is configured in both. In the authorization process, a different service user (idUser) will be created and assigned for each of them, and the corresponding profiles that act in each of the areas will be configured in CoFFEE.
Since each request to the service includes among its parameters the service user code (idUser), CoFFEE can determine the origin and can act accordingly, applying the corresponding security profile.
Notwithstanding the above, it must be taken into account that if one of the organizations used the idUser assigned to the other, there would be no mechanism to identify the impersonation, so this possibility will be carried out at the risk of the client organizations.
Are there any limits set for the use of the service?
The following limits have been defined:
- Maximum request size: 100MB.
- Maximum document size: 60MB.
- Maximum limit of items in a collection: 100 elements.
- Maximum number of requests per second: 5 requests.
- Maximum number of documents uploaded without association: 20 documents.
General questions on the IPR
What is the format of the dates?
The OpenApi 3.0 specification is followed which refers to the definition
RFC 3339, section 5.6, e.g.
2022-07-21.It is important to note that some requested dates should be specified in quarters.
Are all API fields mandatory?
No, only those fields that are marked as such (with a red asterisk) are mandatory.
In relation to indicator progress statements: the “date” field (the progress reference date), does it have to be the current date?
The reference date for the progress of an indicator is the date on which the value of the indicator being updated is deemed to have been reached, and must therefore be earlier than or equal to the current date, i.e. future dates are not permitted.
Why in the case of quantitative indicators is “variation” reported and in the case of qualitative indicators is “value” reported?
Indicators are measurement of progress and may be quantitative (their value is numerical data within a range) or qualitative (they may take a value from a closed set of options).
- In the case of quantitative indicators, the variation from the previous value of the indicator should be reported. For example, if the indicator is “Number of electric vehicles registered” and has gone from 1000 to 3000 vehicles, “2000” will be declared.
- In the case of qualitative indicators, the new value that it has taken from among the possible ones must be reported (start, ongoing and completed).
The reason why the variation is provided for the quantitative indicators is that the system allows a justification (textual and, optionally, accompanied by files) to be incorporated. It is understood that the increased (or decreased) value of an indicator is being justified at the time of the declaration, rather than the final value achieved (in the above example, 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 reference to a legal instrument?
Statements of accounting execution specify a reference to the legal instrument under which the statement is made. The typical case is a contract or a subsidy, but all the instruments envisaged must be capable of being identified.
The reference is therefore a code identifying the specific legal instrument in the field of Action for which execution is recorded.
The reference usually coincides with the code of the instrument itself that is established by the person who registers it in CoFFEE (either by screen, mass loading, ...).
For example, in the case of a grant registered in CoFFEE with the BDNS code "576282", the reference is exactly that same code. Or a contract (not PLACSP) that has been registered in CoFFEE with the contract code "2023OIP45544", will have that same code as a reference.
However, there is a more complex case which is that of PLACSP contracts, and which is dealt with specifically in the following issue.
How does a contract that is registered on the Public Sector Contracting Platform (PLACSP) differ from one that is not?
PLACSP contracts are identified by three codes: contracting authority code, tendering code, and contract code (see below for a detailed explanation). Non-PLACSP contracts are identified by a single code.
In contract registration entries in CoFFEE, the two types of contract are identified separately.
Since references to legal instruments are made through a single field, in the case of PLACSP contracts (which, as indicated, 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 contracting, tendering and contract body codes of PLACSP?
The contracting authority code is an identifier used by the Public Sector Contracting Platform (PLACSP) associated with each of the contracting authorities (in PLACSP it is referred to as “Platform ID”). Each contracting authority may consult its own on the administrator screen of the PLACSP “contracting authority administrator” profile.
In addition, the Directorate-General for State Heritage periodically publishes the list of codes in an
Excel sheet which is being updated.
In the case of PLACSP and for each contracting authority, the tendering and contract codes uniquely identify a contract that is incorporated into the Public Sector Contracts Platform:
The tendering code corresponds to the File Number in PLACSP, which is the file number provided by each contracting authority.
The contract code corresponds to the PLACSP Contract. It is also a value that is determined by the contracting authority. It corresponds to each contract within the dossier.
In any event, both are values provided by the manager to PLACSP. Both can be seen in the following image.
When is the “Other Funding Sources” field completed?
Information on other sources of information will be completed when the action to which the operation relates is funded by some other source, in addition to funding from the Recovery and Resilience Mechanism. In this case, the mechanism or fund that financed the operation will be identified.
Prominent changes from v1.3.1 to v1.5
The highlighted changes are listed according to the type of data:
- All types:
- codeInitiative is now codeAction
- Measure:
- dateHome its value is one quarter
- dateFin its value is one quarter
- Contract:
- contract PLACSP is now Instrument Code, Tender Code and Organo Code
- contract NoPLACSP is now codeInstrument
- Subsidy:
- Convocation BDNS is now codeInstrument
- Initiative:
- Separated into Project, Subproject, SubprojectInstrumental and Action.
- dateHome its value is one quarter
- dateFin its value is one quarter
- Financial Statement
- DeclarationProgressIndicator
- codeInitiative is now called codeOriginProgress
As a general rule, missing camps do not need to be reported.
Highlighted changes from v1.5.0 to v1.5.1
- Route:
- Updated POST/execution/other-instruments/recipient path
- The detailed routes of a legal instrument have been updated. The {reference} parameter is converted to a query parameter. For example, GET /structure/actions/{code}/conventions/{reference} becomes GET /structure/actions/{code}/conventions/detail?reference={reference}
- Action:
- The field transferOfEconomic ResourcesOfAction Subproject has been updated, it becomes optional.
- The Critical Objectives field has been added to Action.
- The type of the Economic Action Resources field has been updated.
- Sub-project:
- The costEstimate of Subproject Economic Resources field has been removed.
- Instrumental Subproject:
- The costEstimated Financial Resources field of Instrumental Subproject has been removed.
Prominent changes from v1.5.1 to v1.5.2
- OwnerCode The ownerCode parameter becomes optional in the following paths:
- /v1.5/structure/projects
- /v1.5/structure/subprojects
- /v1.5/structure/instrumental sub-projects
- /v1.5/structure/actions
If not included, the list will contain all items of the corresponding type to which the user has access.
- Project The sub-projects, instrumental sub-projects and actions include a summary of the project to which they belong (project ownership).
Prominent changes from v2.0.0 to v2.0.1
- Legal instruments.
- The methods of updating PATCH by PUT have been changed for the nine types of legal instruments.
- The role fields of the ChangeSetter, ChangeTaker and ChangeTaker schemas have been changed. The description is now returned and not an object.
- The name of the SinVAT to SinVAT field has been updated.
- The UID has been added to the requests for an operating officer.
- Fixed a bug in instrument profile requests that doesn’t involve expense that didn’t show the right path.
- An endpoint has been added to the legal instruments to override a request for an operating officer.
- An endpoint has been added to the legal instruments to obtain the data of a request for an operating officer.
Prominent changes from v2.0.1 to v2.0.2
- Progress on indicators
- The url of progress reports to progress indicators is modified.
- The code of the node to which the report belongs is included in the url.
- The necessary endpoints for the paginated consultation of documents are included.
- Legal instruments.
- The fields ‘NonVatFirst Level’ and ‘TotalFirst Level’ are returned in the information of a legal instrument.
- The edition of the fieldLot in contractors is allowed.
- Milestones and objectives.
- ｟ADMIN｠ Se definen e implementan los endpoints de consulta de certificados de (no) revocación.
- Economic resources
- The endpoints for the consultation of economic resources are included.
Prominent changes from v2.0.2 to v2.0.3
- Progress on indicators
- New types of editing progress reports.
- Legal instruments
- Direct financial instrument.
- Indirect financial instrument.
- Implementing Agreement.
- Brokering agreement
- New types of viewer publishing.
- New field date of creation.
- Milestones and objectives.
- Modification of the endpoints for registration and editing.
- Follow-up to the plan
- Modification of PUT /subprojects/{code}/submeasures/{submeasure} by POST /subprojects/{code}/submeasures/{submeasure}
Prominent changes from v2.0.3 to v2.0.4
- Milestones and objectives.
- New type of document 'Additional documentation to the certificate'
- Allow multiple documents in first-level controls of a certificate
- GET /milestones/{code}/tracking/certificates/{uid-certificate}/control-firstlevel
- GET /milestones/{code}/tracking/certificates/{uid-certificate}/control-firstlevel/{uid-document}
- GET /milestones/{code}/tracking/certificates/{uid-certificate}/control-firstlevel/{uid-document}/content
- Improvement in the reporting of documents associated with an achievement:
- GET /milestones/{code}/tracking/documents
- GET /hitos/objectives/{code}/tracking/documents/{uid-document}
It includes:- Origin of the document
- In signed certificate
- Imported at a higher level
- State of (no) revocation
- GET /milestones/{code}/tracking/state-revocation
- Confirmation cycle associated with a certificate of (no) revocation
- GET /hitos/objectives/{code}/tracking/certificates/revocation/{uid-certificate}
- Follow-up to the plan
- State transition information for P, SP and SPI.
- GET /projects/{code}/historico-states
- GET /subprojects/{code}/historico-states
- GET /instrument subprojects/{code}/historico-states
- Documents
- Endpoint for consultation of uploaded but not associated documents.
Prominent changes from v2.0.4 to v2.0.5
- Milestones and objectives.
- New type of spreadsheet in HGC, HGnC and CID
- New type of document Index of verification mechanisms
- Endpoints for lower node verification mechanisms
- GET /target-milestones/{code}/tracking/bottom-level/documents
- GET /targets/{code}/trace/bottom-level/documents/{uid-document}
- GET /targets/{code}/tracking/bottom-level/documents/{uid-document}/content
- POST /targets/{code}/trace/bottom-level/documents/{uid-document}/import
- DELETE /targets/{code}/trace/bottom-level/documents/{uid-document}
- Legal instruments.
- TotalFirstlevel is added in direct and indirect financial legal instruments.
- Corrected the code of the Contract Type "COSECPUPR - Collaboration between the public and private sectors"
- Actions.
- Revision of mandatory fields.
- New endpoint for changing a legal instrument for action.
- POST /actions/{code}/legal instruments/{single-code}/move/{target-code}
- Indicators.
- The field "CumulativeProgress value" returns -1 in the case of having different values in some milestone or target
- Documents.
- Document names limited to 180 characters
Prominent changes from v2.0.5 to v2.0.6
- Legal instruments.
- New field ‘Gross equivalent subsidy’ for financial beneficiaries of IFD and IFI-type legal instruments
Prominent changes from v2.0.6 to v2.0.7
- Progress of indicators.
- New endpoint for differential report editing
- POST /Progress of indicators/{code}/reports/{uid-report}/change-differentials
- Follow-up to the plan.
- New endpoints for the monitoring of measures
- GET /measures/{code}/tracking/documents
- GET /measures/{code}/tracking/reports
- GET /measures/{code}/tracking/users
- GET /measures/{code}/follow-up/request-of-responsibility
Prominent changes from v2.0.7 to v2.0.8
- Legal instruments
- New endpoints for the edition of IIJJ amounts with historical
- GET /contract/{single-code}/changes
- POST /contract/{single-code}/changes
- GET /convention/{single-code}/changes
- POST /convention/{single-code}/changes
- ...
- Follow-up to the plan
- New endpoints for the monitoring of measures
- GET /measures/{code}/tracking/documents
- GET /measures/{code}/follow-up/reports
Prominent changes from v2.0.8 to v2.0.9
- Legal instruments
- Inclusion of payment scenarios in indirect financial instruments
General questions about the v2.0 API
How do I obtain the single code of a legal instrument?
The single code of a legal instrument is obtained in three ways:
- Discharge of legal instrument: In the reply to the discharge operation, the single code assigned to the legal instrument is returned. For example:
POST /v2.0/contracts - Consultation of legal instruments for a given action: the list of legal instruments includes the single code for each legal instrument.
GET /v2.0/actions/{code}/legal instruments - Single code consultation: there is a usefulness in obtaining the single code of a legal instrument on the basis of the code of action and the reference of the legal instrument.
GET /v2.0/legal instruments/utilities/single-code
How is the upload of documents carried out?
The upload of documents consists of two steps:
- Upload of the document: A new document is added to the system and the locator needed for other operations is obtained. The document is created with the PENDING type. Documents uploaded and 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 with an element. The association indicates the location of the document, the effective type and the additional metadata. The service used depends on the element, for example, to add a document to a contract, the service is:
POST /v2.0/contracts/{single-code}/documents
If you want to associate the same document with several elements, you only need to upload the document once and you can use the locator as many times as you need.
Other doubts
I have functional doubts about the management of the Recovery Transformation and Resilience Plan and its management system, where can I address it?
The description of the operation of the Plan is articulated with two Ministerial Orders:
- Order HFP/1030/2021, of 29 September, configuring the management system of the Recovery, Transformation and Resilience Plan.
- Order HFP/1031/2021, of 29 September, establishing the procedure and format of the information to be provided by the State, Autonomous and Local Public Sector Entities for the monitoring of the fulfilment of milestones and objectives and of budgetary and accounting execution of the measures of the components of the Recovery, Transformation and Resilience Plan.
I have more technical doubts about the API, where can I address it?
For all other technical questions about the CoFFEE REST API, you can write a message to the support email address@soportesgffee.zendesk.com