PO Integration & Publishing

Choosing Your Integration Model

The ECO Portal supports two complementary integration models. In both models, the Program Operator hosts the authoritative EPD documents on their own infrastructure. The difference lies in whether the ECO Portal receives new records immediately via push notifications or crawls them via scheduled pull polling.

Summary of Integration Models

• Model A: Immediate Push (Webhooks): Best for real-time publishing workflows and eliminating crawler latency. Your publishing pipeline immediately sends an HTTP POST request to POST /api/webhooks/epds with dataset metadata, while full EPD documents are hosted at your own URLs.
• Model B: Scheduled Pull (PO Node Crawler): Best for existing soda4LCA nodes or automated directory polling. You maintain a PO Node web service exposing endpoints for search, retrieval, and health checks, and the portal crawler synchronizes data on a recurring schedule.

You Don’t Have to Use soda4LCA

Historically, many Program Operators deployed soda4LCA instances to participate in the network. Running soda4LCA is entirely optional.

You have complete flexibility to choose the architecture that minimizes operational overhead and best fits your technical capabilities:

Option 1: Existing soda4LCA Instance (Zero Coding)

If you already operate a soda4LCA instance, no new development is needed. The ECO Portal natively supports soda4LCA’s default endpoints:

• GET /resource/processes — Search and discovery endpoint queried by the crawler
• GET /resource/processes/{epd_uuid} — Retrieves the ILCD+EPD dataset
• GET /healthz (or /nodeinfo) — Health-check monitoring

Option 2: Custom Stack PO Node (Any Language or Framework)

You can build your PO Node using any programming language or framework (Node.js, Python, Go, Java, C#/.NET, PHP, or serverless functions). You only need to implement three HTTP endpoints:

1. Search Endpoint (default /v1/epds or /resource/processes):
   • Accepts query parameters sent by the crawler: pageSize, startIndex, validUntil, and format=json.
   • Returns a JSON envelope with pagination and an array of search items:

     {
       "pageSize": 50,
       "startIndex": 0,
       "totalCount": 120,
       "data": [ /* Array of SearchItem objects */ ]
     }

2. Get EPD Endpoint (default /v1/epds/{epd_uuid} or /resource/processes/{epd_uuid}):
   • Returns the complete ILCD+EPD document for the requested UUID in JSON format (format=json).
3. Health Endpoint (default /v1/healthz or /healthz):
   • Returns HTTP 200 to confirm that your node is operational and able to serve data.

You can configure your custom endpoint paths directly in the ECO Portal under Organization Settings → PO Data.

Option 3: Webhook-Only Publishing (No Public Search API Needed)

If your organization prefers not to develop or maintain a public search API and crawler endpoint, you can host your EPD files on any reliable web server or storage bucket, and push discovery records to the ECO Portal webhook whenever new declarations are published.

Publishing EPDs via Webhook

The Webhook endpoint allows Program Operators to push EPD discovery records directly into the ECO Portal Search Index in real time.

Endpoint & Authentication

• URL: POST /api/webhooks/epds
• Headers:
  • Content-Type: application/json
  • x-api-key: <PO_API_KEY> (or Authorization: Bearer <PO_API_KEY>)

Note on Permissions: Webhook publishing requires an API key associated with a verified Program Operator organization. Individual user keys without PO organization membership will return 403 Forbidden. See API Keys documentation to learn how to create and manage keys.

Request Payload Format

The webhook request body must be a JSON object containing a records array. Each entry in the array is a search item representing an EPD:

{
  "records": [
    {
      "uuid": "0e28fd9d-53ec-434f-a278-3ba03f8323d2",
      "name": "Structural Timber C24",
      "version": "01.00.000",
      "subType": "specific dataset",
      "format": "ILCD+EPD",
      "type": "EPD",
      "languages": ["en"],
      "validUntil": 2029,
      "refYear": 2024,
      "geo": "DE",
      "owner": "Holzwerke Example GmbH",
      "compliance": [
        {
          "uuid": "11111111-1111-4111-8111-111111111111",
          "name": "DIN EN 15804+A2"
        }
      ],
      "regAuthority": {
        "uuid": "d111dbec-b024-4be5-86c5-752d6eb2cf95",
        "name": "Institut Bauen und Umwelt e. V."
      },
      "nodeid": "d111dbec-b024-4be5-86c5-752d6eb2cf95",
      "uri": "https://epd-online.com/epds/0e28fd9d-53ec-434f-a278-3ba03f8323d2",
      "classific": "Wood and wood-based materials",
      "dataSources": [
        {
          "uuid": "22222222-2222-4222-8222-222222222222",
          "name": "IBU Data Pool"
        }
      ]
    }
  ]
}

Field Definitions

Responses and Status Codes

• 200 OK: Records accepted and successfully ingested into the Search Index.

  {
    "accepted": 1,
    "rejected": 0,
    "errors": []
  }

• 400 Bad Request: Request payload failed schema validation or missing required fields. Check the errors array in the response for detailed field errors.
• 401 Unauthorized: Missing or invalid API key.
• 403 Forbidden: Valid API key, but the account or organization is not designated as a registered Program Operator.

Code Examples

The code examples below show how to push EPD records via the webhook API:

PO Node API Reference

The interactive reference below specifies the endpoint schemas for self-hosted PO Nodes: