Preliminary information
Availability of the API
Connection and use of the service
Preliminary information
What is CoFFEE and CoFFEE-MRR?
CoFFEE (Common Platform of European Funds) is the common IT platform for the management of European funds. It aims to integrate the various modules supporting the management of European funds within the competence of the General Secretariat of European Funds (EMAS) in the multiannual financial framework 2021-2027 (MFF 21-27). This is the evolution of the information systems supporting 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 mainstreaming mechanisms, etc. the platform, incorporating the necessary functionality for the planning, management and monitoring of the 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 budgetary 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 facilitate the implementing entities of the initiatives to comply with the regulations governing the Plan, and in particular Order HFP/1030/2021 of 29 September, setting up the management system of the Recovery, Transformation and Resilience Plan (Management Order), and Order HFP/1031/2021 setting out the requirements for the
Entities that do not have such capacity can incorporate the information in an interactive manner, for which they must first request access.
Is the REST API already available to connect?
Yes. The state of implementation of the different endpoints is available in:
endpoint status.
List of versions
| Date | Version | Environment | Link to API | New developments |
|---|
| April 2025 | 2.0.7 | Production |
Link to version 2.0.7 | New endpoint for Differential Progress Report Editing |
| 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 | 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, implementation agreements, brokering agreements. |
| October 2024 | 2.0.2 | Replaced by v2.0.3 |
Link to version 2.0.2 | Definition of services for the register of progress of indicators. Definition of services for the consultation of revocation (no) 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 | Replaced by v2.0.1 |
Link to version 2.0.0 | |
| March 2024 | 1.5.2 | Production |
Link to version 1.5.2 | Optional owner in some listings and project information in sub-project, instrument sub-projects and actions. |
| January 2024 | 1.5.1 | 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 | 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 | Statements of achievement of indicators (also limiting possible values for qualitative indicators) and financial performance are treated separately. Finally, accounting documents DO and DO/ are included. |
Are there alternative mechanisms to the API to provide 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 users who connect to it, and also through the (interactive) incorporation of a file with all the data to be processed.
Naturally, CoFFEE will carry out the same validations when the information is provided on a massive basis through the loading of a file.
What is the encoding format of the JSON file being uploaded to CoFFEE?
Connection and use of the service
How do I request access to the API and what procedure does it trigger?
In the event that an external management application with CoFFEE is to be integrated, you should consult the document with the instructions for completing the authorisation to update information in CoFFEE via API.
The procedure can be summarised in these points:
2.La OIP shall contact the requesting technical department via the CoFFEEDesarrollo@igae.hacienda.gob.es mailbox indicating the user who identifies the management application.
3.Los responsible for nodes information (PRTR projects, sub-projects and instrument sub-projects) authorise the user who identifies the management application that provides them with access to and edit nodes data.
4.El the applicant technician sets out the electronic certificate to be used for safe communication.
How is access security achieved?
Client Web services shall be authenticated by HTTPS/TLS (1.2 or above). In particular, a certificate of administrative stamp, body or public law entity shall 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 recognised by the @Signature service.
During the organisational process of access authorisation, the certificate using the end-customer of the service is agreed between the Office of Budgetary Information Technology 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. For this purpose, any interaction shall be carried out under secure communication (TLS) using the pre-agreed seal certificate.
Each REST call shall include in the HTTP request, in addition to the parameters indicated in the service's own documentation, two additional parameters (idUser and idApplication), which shall contain the values that were provided during the access configuration process.
Can several organisations use the same seal certificate to interact with the API?
Although not usual, this possibility is allowed if two applications for access are processed, one for each of the organizations, and the same certificate is set out in both. The authorisation process shall create and assign a different service user (idUser) for each of them, and the corresponding profiles acting in each of the areas shall be configured in CoFFEE.
As each request to the service includes among its parameters the service user code (idUser), CoFFEE may determine the origin and may act accordingly, applying the relevant safety profile.
Notwithstanding the above, it should be borne in mind 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 number of requests: 100MB.
- Maximum document size: 60MB.
- Maximum limit of elements in a collection: 100 elements.
- Maximum number of requests per second: 5 requests.
- Maximum number of documents uploaded without associating: 20 documents.
General API questions
What is the format of the dates?
The OpenApi 3.0 specification referring to the definition
RFC 3339, Section 5.6, e.g. 2022-07-21, is followed.
It is important to note that certain requested dates should be specified in quarters.
Are all the mandatory API fields?
No, only those fields which are marked as such (with an asterisk in red) are mandatory.
In relation to declarations of achievement of indicators: the ‘date’ field (the reference date of progress), does it have to be the current date?
The reference date for the progress of an indicator is the date when the value of the indicator that is updated is considered to be reached, and therefore has to be earlier than or equal to the current date, i.e. future dates are not allowed.
Why in the case of quantitative indicators is the “variation” reported and in the case of qualitative indicators is the “value” reported?
Indicators are indicators of achievement and can be quantitative (their value is a numerical data within a range) or qualitative (they can take a value from a closed set of options)
- In the case of quantitative indicators, the variation produced from the previous value of the indicator should be reported. For example, if the indicator is “Number of electric vehicles registered” and has been moved from 1000 to 3000 vehicles, it shall be declared “2000”.
- In the case of qualitative indicators, the new value it has taken from the potential (beginning, ongoing and completed) should be reported.
The reason for the variation for quantitative indicators is that the system allows a justification to be incorporated (textual and, optionally, accompanied by files). It is understood that the increased (or decreased) value of an indicator is being justified at the time of the declaration, and not 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 reached is declared.
What is the reference of a legal instrument?
The accounting implementation declarations specify a reference to the legal instrument under which the declaration is made. The typical case is a contract or a grant, but all the instruments envisaged must be able to be identified.
The reference is therefore a code that identifies the specific legal instrument in the area of the Action for which the implementation is recorded.
The reference usually coincides with the instrument code itself set by the person who signs it up in CoFFEE (either by screen, mass load, ...).
For example, in the case of a CoFFEE discharge grant with the BDNS code '576282', the reference is exactly the same code. Or a contract (not PLACSP) that has been discharged in CoFFEE with the contract code '2023OIP45544', will have the same code as a reference.
However, there is one more complex case which is that of the PLACSP contracts, and which is specifically addressed in the next issue.
How does a contract that is discharged from the Public Sector Procurement Platform (PLACSP) differ from one that is not?
PLACSP contracts are identified by three codes: contracting authority code, tender code and contract code (see below for detailed explanation). Non-PLACSP contracts are identified by a single code.
In the discharge of contracts in CoFFEE, the two types of contracts are identified separately.
Since the references of 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 are empty.
What are the PLACSP contracting, tendering and contract codes?
The
contracting authority code is an identifier used by the Public Sector Procurement Platform (PLACSP) associated with each of the bodies (PLACSP is referred to as the “ID Platform”). Each contracting authority may consult its own on the administrator screen of the PLACSP “Contracting Entity Administrator” profile.
In addition, the General Directorate of State Heritage regularly publishes the code list in an
Excel sheet that they are updating.
In the case of PLACSP and for each contracting authority, the procurement and contract codes are those which uniquely identify a contract that is incorporated into the Public Sector Contracts Platform:
The
tender code corresponds to the Dossier Number in the PLACSP, which is the dossier number provided by each contracting authority.
The
contract code corresponds to the PLACSP Contract. It is also a value determined by the contracting authority. It corresponds to each contract within the file.
In any case, both are values provided by the manager to the PLACSP. Both can be seen in the image below.
When is the “Other Sources of Funding” field completed?
Information on other sources of information shall be completed when the action to which the operation relates is financed by another source, in addition to funding from the Recovery and Resilience Mechanism. In this case, the mechanism or fund that has financed the operation shall be identified.
Major changes from v1.3.1 to v1.5
The main changes are listed according to the type of data:
- All
types:
-
Measure:
- dateHome value is one quarter
- dateEnd value is one quarter
-
Contract:
- PLACSP is now delivered to the United Kingdom
- contract NoPLACSP is now
-
Subsidy:
-
Initiative:
- Separated in Project, Sub-project, Sub-Project, Instrument and Action.
- dateHome value is one quarter
- dateEnd value is one quarter
-
Financial statements
-
DeclarationProgress
- ☐ Initiative now called ‘OriginProgress’
As a general rule, missing fields do not need to be reported.
Major changes from v1.5.0 to v1.5.1
-
Route:
- Updated route POST /run/other-instruments/recipients
- The detailed routes of a legal instrument have been updated. The {reference} parameter is converted into a query parameter. For example, GET /structure/actions/{code}/conventions/{reference} becomes GET /structure/actions/{code}/conventions/detail?reference={reference}
-
Action:
- The transfer field has been updated DeResourcesEconomicosAOtroSub-project of Action, becomes optional.
- The field has been added to Action.
- The type of the Economicos de Actuación resource field has been updated.
-
Sub-project:
- The costEstimated Sub-Project Economic Resources Field has been removed.
-
Sub-projectInstrumentation:
- The Estimated Cost Savings Field of Sub-Project Instrumentation has been removed.
Major changes from v1.5.1 to v1.5.2
- The
Owner parameter shall be optional on the following routes:
- /v1.5/structure/projects
- /v1.5/structure/sub-projects
- /v1.5/structure/instrument sub-projects
- /v1.5/structure/actions
If not included, the list shall contain all the elements of the type to which the user has access.
- Project
sub-projects, instrument sub-projects and actions include a summary of the project to which they belong
(project property).
Featured changes from v2.0.0 to v2.0.1
-
Legal instruments.
- The PATCH update methods have been changed to PUT for the nine types of legal instruments.
- The fields have been changed in the Contractor/Change, Recipient/Change and Recipient/Change schedules. The description is now returned and not an object.
- The name of the field is updated immediately.
- The uid has been added to the requests for operational officer.
- A bug has been fixed in requests for instrument profile that does not involve expenditure that did not show the right route.
- An endpoint has been added to the legal instruments to cancel an application for an operating officer.
- An endpoint has been added to the legal instruments to obtain data from an application for an operating officer.
Major changes from v2.0.1 to v2.0.2
-
Progress of indicators
- The URL of the progress to progress/indicators is modified.
- The code of the node to which the report belongs is included in the url.
- The endpoints required for the paginated consultation of documents are included.
-
Legal instruments.
- The fields are returned immediately SinIva FirstLevel and immediately TotalFirstLevel in the information of a legal instrument.
- The numLot field is allowed to be edited in contractors.
-
Milestones and objectives.
- 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.
Featured changes from v2.0.2 to v2.0.3
-
Progress of indicators
- New types of editing progress reports.
-
Legal instruments
- Direct financial instrument.
- Indirect financial instrument.
- Implementing Agreement.
- Brokering agreement
- New types of recipient editing.
- New field date of creation.
-
Milestones and objectives.
- Modification of endpoints for discharge and editing.
- Monitoring
of the plan
- Modification of PUT /sub-projects/{code}/sub-measures/{sub-measure} by POST /sub-projects/{code}/sub-measures/{sub-measure}
Featured 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 checks of a certificate
- GET /objectives/{code}/tracking/certificates/{uid-certificate}/control first-level
- GET /objectives/{code}/tracking/certificates/{uid-certificate}/control/first-level/{uid-document}
- GET /objectives/{code}/tracking/certificates/{uid-certificate}/control/first-level/{uid-document}/content
- Improved information on documents associated with an achievement:
- GET /objectives/{code}/tracking/documents
- GET /objectives/{code}/tracking/documents/{uid-document}
Includes:
- Origin of the document
- On a signed certificate
- Imported at higher level
- Status of (no) revocation
- GET /objectives/{code}/tracking/state-revocation
- Confirmation cycle associated with a certificate of (no) revocation
- GET /Objectives/{code}/Tracking/Certification-Revocation/{uid-certificate}
- Monitoring
of the plan
- Transitional status information for P, SP and SPI.
- GET /projects/{code}/historico-states
- GET /sub-projects/{code}/historico-states
- GET /sub-projects/{code}/historico-states
-
Documents
- Endpoint for consultation of uploaded but not associated documents.
Major 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 /objectives/{code}/tracking/level/bottom/documents
- GET /objectives/{code}/tracking/level/bottom/documents/{uid-document}
- GET /objectives/{code}/tracking/level/bottom/documents/{uid-document}/content
- POST /objectives/{code}/tracking/level/bottom/documents/{uid-document}/import
- DELETE /h-objectives/{code}/tracking/level/bottom/documents/{uid-document}
-
Legal instruments.
- It is added immediately TotalFirstLevel in direct and indirect financial legal instruments.
- Corrected Contract Type Code 'COSECPUPR - Public-Private Partnership'
-
Proceedings.
- Revision of mandatory fields.
- New endpoint to change a legal instrument for action.
- POST /actions/{code}/instrument-juridicos/{den-unico}/mover/{den-destination}
-
Indicators.
- The "Cumulative Progress" field returns -1 in the case of having different values at any milestone or objective
-
Documents.
- Document names limited to 180 characters
Major changes from v2.0.5 to v2.0.6
-
Legal instruments.
- New field 'Equivalent gross grant' for financial beneficiaries of IFD and IFI type legal instruments
Featured changes from v2.0.6 to v2.0.7
-
Progress of indicators.
- New endpoint for differential report editing
- POST /progress/indicators/{code}/reports/{uid-report}/changes/differentials
-
Monitoring of the plan.
- New endpoints for monitoring measures
- GET /measures/{code}/tracking/documents
- GET /measures/{code}/follow-up/reports
- GET /measures/{code}/tracking/users
- GET /measures/{code}/tracking/solicite-de-responsible
General API questions v2.0
How do I get the single code from a legal instrument?
The unique code of a legal instrument is obtained in three ways:
-
Legal instrument discharge: The unique code assigned to the legal instrument is returned in the discharge operation response. For example:
POST /v2.0/contracts -
Consultation of legal instruments of an action: the list of legal instruments includes the single code of each legal instrument.
GET /v2.0/actions/{code}/legal instruments -
Consultation of a single code: there is a usefulness for obtaining the single code of a legal instrument from the code of action and the reference of the legal instrument.
GET /v2.0/instrument-juridical/profits/pro-unico
How are documents uploaded?
The document upload consists of two steps:
-
Document upload: A new document is added to the system and the locator required for other operations is obtained. The document is created with the PENDING type. Documents uploaded and not associated with an item shall be erased regularly. The service used is:
POST /v2.0/documents -
Association of the document with one element: The document raised in the previous paragraph is associated with one 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/
If the same document is to be associated with several elements, it is only necessary to do so once the upload of the document is possible to use the locator as often as necessary.
Other doubts
I have functional doubts about the management of the Transformation and Resilience Recovery Plan and its management system, where can I address myself?
The description of the operation of the Plan consists of 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 milestones and objectives and for the budgetary and accounting implementation of the measures of the components of the Recovery, Transformation and Resilience Plan.
I have further technical doubts about the API, where can I address myself?
For other technical questions about the CoFFEE REST API, a message can be written to the CoFFEE-Development@ Support Email Addressigae.hacienda.gob.es
Only technical consultations relating to the exchange of information with the platform will be dealt with from this mailbox.