EPU Commercial Intelligence API Contracts

1. Purpose

This page defines implementation-facing service contracts for Supplier Product Data Onboarding, Anticipatory Sustainability Acquisition and Procurement Sustainability Intelligence. It does not define marketplace transactions.

All commands and queries are tenant-scoped, authorization-checked, idempotent where they create business effects, and provenance-bearing.

2. Supplier product source connection

POST /epu/v1/supplier-product-sources

Creates a governed connection descriptor for a supplier ECO product-data source.

Required semantic inputs:

supplier_eco_id
source_type
source_system_ref
connection_policy_ref
authority_profile
synchronization_policy
access_policy_ref

Returns a supplier_product_source_id. Secrets/credentials are managed by the platform secrets/integration layer and must never be embedded in EPU graph objects or documentation payloads.

POST /epu/v1/supplier-product-sources/{id}/sync

Requests idempotent synchronization. Source records become SourceProductCandidate objects and must pass Product Identity Resolution before product facts become attached to an EPU context.

3. Information profile resolution

POST /epu/v1/information-profiles:resolve

Input:

{
  "epu_id": "EPU-...",
  "profile_ids": ["PCF_PROFILE", "CHEMICAL_DECLARATION_PROFILE"],
  "effective_at": "2026-08-30T00:00:00Z",
  "requesting_party_ref": "ECO-...",
  "purpose": "PROCUREMENT_QUALIFICATION"
}

Response must distinguish:

RESOLVED
PARTIALLY_RESOLVED
MISSING
ACCESS_DENIED
EXPIRED
CONFLICTED

Every resolved datum must preserve source authority, provenance, validity and TrustGate/evidence state where applicable.

4. Requirement anticipation

POST /epu/v1/requirements:anticipate

Input context may include:

epu_id
trigger_type
trigger_ref
buyer_eco_id
supplier_eco_id
jurisdictions[]
market_context[]
commercial_context
product_definition_version
composition_version
requested_disclosure_profiles[]
customer_policy_refs[]
effective_at

The service resolves requirements from Pergamum Pulse and other governed policies and returns a RequirementSet.

It must not ask a supplier for data.

5. Gap analysis

POST /epu/v1/requirement-sets/{id}:analyze-gaps

For each requirement, evaluate reusable governed information before acquisition.

Response states use the canonical Requirement Type Registry, including:

NOT_APPLICABLE
SATISFIED
SATISFIED_ESTIMATED
SATISFIED_SECONDARY_DATA
MISSING
REQUESTED
SUBMITTED
VALIDATING
INSUFFICIENT
EXPIRED
VERIFIED
WAIVED

6. Data authority resolution

POST /epu/v1/requirement-gaps/{id}:resolve-authority

Determines the best-positioned source for an unresolved datum.

Candidate authorities may include manufacturer ECO, component supplier ECO, material producer ECO, connected ERP/PLM/PIM, existing evidence issuer or another governed source.

Response includes rationale and provenance; it must not infer authority solely from graph proximity.

7. Acquisition planning

POST /epu/v1/requirement-gaps/{id}:plan-acquisition

Produces an acquisition action only after reuse and authority resolution.

AcquisitionAction
├── acquisition_action_id
├── requirement_ref
├── epu_id
├── scope_ref
├── acquisition_mode
├── authority_ref
├── target_party_ref?
├── target_source_ref?
├── requested_profile_ids[]
├── requested_fields[]
├── evidence_expectations[]
├── priority
├── desired_by
├── trigger_ref
└── provenance_ref

The planner may choose automated resolution/synchronization instead of a human supplier request.

8. PCF comparability

POST /epu/v1/procurement/pcf:compare

Input references two or more governed PCF artifacts plus the procurement functional-unit/context requirement.

The resolver evaluates the registered dimensions:

functional_unit
system_boundary
methodology
allocation
reference_period
geography
production_context
data_quality
verification_state
uncertainty
trustgate_state

Response state:

COMPARABLE
CONDITIONALLY_COMPARABLE
NORMALIZABLE
NOT_COMPARABLE

NOT_COMPARABLE prohibits a PCF-based ranking. NORMALIZABLE requires a governed normalization result before ranking.

9. Carbon-adjusted acquisition cost

POST /epu/v1/procurement/carbon-adjusted-cost:calculate

Calculation execution belongs to Computation Hub/MICE. The EPU-facing contract supplies governed context and receives a result reference.

Required inputs:

offer_ref
epu_id
commercial_price
commercial_currency
commercial_functional_unit
pcf_result_ref
comparability_decision_ref
internal_carbon_price_policy_ref
scenario_effective_at

Canonical formula for the simple case:

CAAC = P + ((PCF_kgCO2e / 1000) × ICP_per_tCO2e)

Response must expose separately:

commercial_price
internal_carbon_cost
carbon_adjusted_acquisition_cost
currency
functional_unit
uncertainty
calculation_result_ref
method/version lineage

Internal carbon cost must never overwrite or masquerade as invoice price.

10. Carbon-price break-even

POST /epu/v1/procurement/carbon-price-break-even:calculate

Given comparable candidate offers, MICE calculates the internal carbon price at which preference changes under the selected cost model.

The result is decision intelligence, not a supplier-facing contractual price unless explicitly authorized by buyer policy.

11. Event contract

Services publish material state changes using schemas/epu/commercial-intelligence-event.schema.v1.json and event names registered in config/system/epu.commercial-events.json.

Every event carries:

event_id
event_type
occurred_at
tenant_id
correlation_id
causation_id?
producer
actor_ref?
epu_id?
eco_id?
source_ref?
provenance_ref?
payload

Consumers must be replay-safe and achieve exactly-once business effect through idempotency even when delivery is at-least-once.

12. Authorization

Authorization must cover both object values and graph discovery. Relevant actions include:

RESOLVE_INFORMATION_PROFILE
ANTICIPATE_REQUIREMENTS
VIEW_REQUIREMENT_REASON
PLAN_ACQUISITION
REQUEST_SUPPLIER_DATA
VIEW_PCF
COMPARE_PCF
VIEW_INTERNAL_CARBON_PRICE
CALCULATE_PROCUREMENT_SCENARIO
VIEW_PROCUREMENT_SCENARIO

Internal carbon-price policies and procurement scenarios are buyer-confidential by default.

13. Non-goals

These contracts do not implement marketplace listing, auction, payment, commission, settlement, escrow or legally binding transaction execution.