FAQs about the API

• How do I request access to the API and what procedure does it trigger?
• How is secure access achieved?
• What does a typical interaction with the service (a call to an API method) look like?
• Can multiple organisations use the same seal certificate to interact with the API?
• Are there limits on the use of the service?

General questions about API v2.0

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

Other concerns

• I have functional doubts about the management of the Recovery, Transformation and Resilience Plan and its management system, where can I go?
• I have further technical queries related to the API. Where can I address them?

How to apply to access CoFFEE/CoFFEE-MRR?

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

Access and use of the service

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

Instrucciones para la cumplimentación de la autorización para actualizar información en CoFFEE mediante API.

Instrucciones para la cumplimentación de la autorización para actualizar información en CoFFEE mediante API. (doc)

The procedure can be summarised as follows:

1. The individual responsible for integrating the management application with CoFFEE must submit a request for access via the form available in the Web Services Catalogue of the Budget Administration Portal.

2. The OIP will contact the requesting technical department via the mailbox CoFFEEDesarrollo@igae.hacienda.gob.es, indicating the user who has identified the management application.

3. Those responsible for the information of the nodes (projects, sub-projects and instrumental sub-projects of the RTRP) must grant authorisation to the user who has identified the management application that provides them with access and the ability to edit the data of the nodes.

4. The requesting technical department is responsible for configuring the electronic certificate to be used for secure communication.

 

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.

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 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.5.0 to v1.5.1

• 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).

• Legal instruments.
  • The PATCH update methods have been modified to utilize the PUT method for all nine types of legal instruments.
  • The fields of the schemas ContractorChanges, BeneficiaryChanges and RecipientChanges have undergone a transformation. The description is now returned as a description rather than an object.
  • The designation of the field amountWithoutVAT has been revised to amountWithoutVAT.
  • The uid has been incorporated into the operation manager requests.
  • A bug in the processing of instrument profile requests has been identified and rectified. The issue was that the requests did not behave as an overhead and did not show the correct path.
  • A new endpoint has been incorporated into the legal instruments, allowing an operation manager to cancel a request.
  • A new endpoint has been incorporated into the legal instruments to facilitate the retrieval of transaction officer details upon request.

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

• 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.
• Economic resources
  • Modification of PUT /sub-projects/{code}/sub-measures/{sub-measure} by POST /sub-projects/{code}/sub-measures/{sub-measure}

General questions about API v2.0

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

How do I upload documents?