API-Explanation: EPEA Product Compliance Assessment Service (ProCA)

API-Explanation: EPEA Product Compliance Assessment Service (ProCA)



Access the API and its interactive documentation here:  Swagger UI 

Authentication and limits

All ProCA endpoints require an API key in the following HTTP header:
X-Api-Key: <your-api-key>
The ProCA API uses rate limiting. The current limit is 10 requests per 10 seconds. Up to 5 additional requests can wait in the queue. Requests exceeding the available limit receive HTTP status 429 Too Many Requests.

Background information

Product categories

Products are assigned to product categories so that they can be compared consistently. The category structure is based on the BWGS (Bau-Warengruppenschlüssel), a cross-sector classification system used by distributors, producers and suppliers.
Use the lowest-level category ID returned by the product-type endpoint. Current leaf category IDs are eight digits, for example 11010502. The API expects the category ID as a string; the endpoint does not explicitly validate the number of digits.
Product types can be retrieved with:
GET /api/Proca/StaticFiles/ProductTypes

Product attributes

Product attributes describe a product in addition to its category. They are used to determine whether rules and assessment requirements apply.
The complete current attribute list is available from:
GET /api/Proca/Attributes
An individual attribute can be retrieved with:
GET /api/Proca/Attributes/{codeName}
Do not hard-code the complete attribute list in an integration. Attributes and their metadata can change.

Rules and preconditions

Rules represent individual compliance requirements within an assessment system. Preconditions determine which rules apply to a product based on a reduced set of product attributes.
Preconditions determine which rules are applicable. The assessment execution evaluates the applicable rules and returns the assessment result.

Assessment workflow

1. Select the product category

Retrieve the available product types and select the appropriate lowest-level category ID.

2. Get the attributes required for preconditions

Use the GetPreconditions endpoint. The endpoint returns an array of ProductAttribute objects directly.
GET /api/Proca/GetPreconditions?categoryId=11010502&gbsIds=QNG23&gbsIds=DGNB18&gbsIds=EUTAX24
The query parameter gbsIds can be supplied multiple times. The response contains the attributes required to determine which rules apply.
Example response:
[
  {
    "name": {
      "de-de": "Anwendungsbereich ist innen",
      "en-us": "Application Area is indoors"
    },
    "type": "boolean",
    "codeName": "UsedIndoors",
    "createdAt": "2023-08-04T09:19:12",
    "modifiedAt": "2024-05-31T06:07:04",
    "values": [],
    "UTC-ID": "ET08-USE3",
    "unit": "",
    "description": {
      "de-de": "",
      "en-us": ""
    }
  }
]

3. Execute the preconditions

Call ExecutePreconditions once for each assessment system. The request contains assessmentId, categoryId and a product with an attributes object.
The product object for this endpoint contains only attributes. Fields such as name or productName are not part of the request contract.
Example:
{
  "assessmentId": "QNG23",
  "categoryId": "11010502",
  "product": {
    "attributes": {
      "RelevantContributionToCost": true,
      "UsedIndoors": false,
      "CrackBridging": false,
      "SealantForGlass": false,
      "AdhesiveTape": false,
      "MineralWool": false,
      "FoamGlass": false,
      "RigidFoam": false
    }
  }
}
All attributes returned by GetPreconditions must be supplied in product.attributes. Missing attributes can cause validation or assessment errors.
The response contains:
  • status: the precondition result status;
  • rules: applicable rules and the attributes required to evaluate them;
  • requiredAttributes: the complete set of attributes required for the next step.
Example response:
{
  "status": "HasRequirements",
  "rules": [
    {
      "ruleId": "WB117",
      "name": {
        "de-de": "Produkt aus Sekundärrohstoffen",
        "en-us": "Product from secondary material sources"
      },
      "requiredAttributes": [
        "RecycledContentPreConsumer",
        "RecycledContentPostConsumer"
      ]
    }
  ],
  "requiredAttributes": [
    {
      "name": {
        "de-de": "Pre-Consumer Recycled Content",
        "en-us": "Pre-Consumer Recycled Content"
      },
      "type": "number",
      "codeName": "RecycledContentPreConsumer",
      "values": [],
      "UTC-ID": "",
      "unit": "%",
      "description": {
        "de-de": "",
        "en-us": ""
      }
    }
  ]
}

4. Execute the assessment

Add the attributes returned by ExecutePreconditions to product.attributes and call ExecuteAssessment.
The request format is:
{
  "assessmentId": "QNG23",
  "categoryId": "11010502",
  "ruleIds": null,
  "product": {
    "attributes": {
      "RelevantContributionToCost": true,
      "UsedIndoors": false,
      "CrackBridging": false,
      "RecycledContentPreConsumer": 20
    }
  }
}
ruleIds is optional. If it is null, the assessment engine evaluates the applicable rules according to the product category and assessment system.
The response contains one or more assessment results:
{
  "assessmentResults": [
    {
      "resultType": {
        "resultTypeId": "ENV12QL",
        "name": "ENV1.2 Quality Level",
        "bestPossibleResult": 4
      },
      "result": 3,
      "ruleResults": [
        {
          "ruleId": "DGNBRU14",
          "ruleResultStatus": "RequirementsPassed",
          "value": 3
        }
      ]
    }
  ]
}
The aggregated assessment result is in assessmentResults[].result. Individual rule results are available in assessmentResults[].ruleResults[].value.
Possible ruleResultStatus values are:
RequirementsPassed
RequirementsNotMet
NotApplicable
NoRequirements
HasRequirements

ProCA endpoints

All endpoints below use the /api/Proca prefix and require the X-Api-Key header.

Assessment and metadata endpoints

POST /api/Proca/ExecuteAssessment
POST /api/Proca/ExecutePreconditions
GET  /api/Proca/GetPreconditions
GET  /api/Proca/RequiredAttributes/{categoryId}
GET  /api/Proca/GreenBuildingSystems
GET  /api/Proca/Attributes
GET  /api/Proca/Attributes/{codeName}
GET  /api/Proca/StaticFiles/ProductTypes
RequiredAttributes/{categoryId} expects the applicable preconditionIds query parameter, which can also be supplied multiple times:
GET /api/Proca/RequiredAttributes/11010502?preconditionIds=MC001&preconditionIds=MC002

Product endpoints

GET  /api/Proca/Product/{id}
GET  /api/Proca/Product/GetAllProcaProducts
GET  /api/Proca/Product/GetAllProducts
POST /api/Proca/Product
PUT  /api/Proca/Product
GetAllProcaProducts returns only ProCA-assessed products. GetAllProducts returns all products available to the API key.
The product create and update endpoints accept a ProductDto. They return a list of product view models. Read-only API keys cannot use these write operations.

Product attribute response fields

Product attributes can contain the following fields:
name
type
codeName
createdAt
modifiedAt
values
UTC-ID
unit
description
Localized names and descriptions use the de-de and en-us properties.