Verificare la conformità UE

qr3.app include un validatore UE integrato per i Digital Product Passports. Verifica i tuoi DPP rispetto alle normative UE pertinenti (ESPR, Loi AGEC) e fornisce issue strutturati con severity, percorso del campo, suggerimenti e un badge opzionale ESPR-ready.

Ci sono tre punti di ingresso:

Lato server, DPP già salvati — GET /v1/dpp/:id/eu-compliance
Anteprima live nel modulo di creazione — POST /v1/dpp/validate
Simulatore live nel dettaglio — POST /v1/dpp/:id/validate-update

Tutti e tre restituiscono lo stesso shape EuComplianceResult — devi quindi implementare l’analisi una sola volta.

Shape del risultato

{
  "compliant": false,
  "espr_ready": true,
  "issues": [
    {
      "code": "TEXTILE_AGEC_REQUIRED",
      "severity": "error",
      "field": "textile_data.country_weaving_knitting",
      "message": "AGEC chain country is required for products sold on the French market",
      "hints": { "market": "FR" }
    },
    {
      "code": "TEXTILE_GREENWASHING",
      "severity": "warning",
      "field": "product_name",
      "message": "\"natural\" is a prohibited term under AGEC",
      "hints": { "term": "natural", "locale": "en", "category": "generic" }
    }
  ],
  "summary": { "errors": 1, "warnings": 1, "info": 0 }
}

compliant: true ⇔ summary.errors === 0
espr_ready: true ⇔ tutti i campi ESPR-Opt-in impostati (vedi DPP tessile)
issues[] è ordinato in modo stabile per severity (error → warning → info) e poi per codice

Livelli di severity

Severity	Significato	Esempio
`error`	Blocca la conformità UE; dovrebbe essere corretto prima del rilascio	`TEXTILE_AGEC_REQUIRED` se FR è nel mercato e la catena di origine è incompleta
`warning`	Raccomandazione; il cliente può salvare, ma dovrebbe agire	`TEXTILE_GREENWASHING` al di fuori di FR
`info`	Segnale di stato senza necessità di azione	`TEXTILE_ESPR_READY` — tutti i campi ESPR-Opt-in completi

Catalogo delle regole (Tessile + Batteria)

Tessile (Q3.3.4)

Codice	Severity	Causa
`TEXTILE_AGEC_REQUIRED`	`error` (FR) · `warning` (altrimenti)	Catena AGEC (tessitura/tintura/confezionamento) incompleta, FR nel mercato
`TEXTILE_MICROPLASTICS_CONSISTENCY`	`error`	Sintetico ≥ 50% ma `contains_microplastics !== true`
`TEXTILE_SVHC_THRESHOLD`	`warning`	Voce SVHC senza numero CAS o concentrazione
`TEXTILE_GREENWASHING`	`error` (FR) · `warning` (altrimenti)	Termine dall’elenco dei divieti in `product_name`/`material`
`TEXTILE_ESPR_READY`	`info`	Tutti i campi ESPR B7–B15 completi

Batteria (Fase 4a)

Il validatore verifica i valori limite del Regolamento UE sulle batterie 2023/1542 (soglie di contenuto riciclato, classi di impronta di carbonio, garanzia minima, ecc.). Dettagli nella documentazione del DPP per le batterie.

Anteprima live nel modulo di creazione

Non appena crei un DPP nella dashboard (/dashboard/dpp/new), lo stesso validatore viene eseguito in modalità stateless a ogni roundtrip di validazione — senza che il passaporto debba essere salvato. La sezione eu_compliance appare direttamente sotto il pannello di validazione esistente ed evidenzia errori e avvisi prima dell’invio (submit).

Accesso diretto all’API:

curl -X POST https://qr3.app/v1/dpp/validate \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Workspace-Id: $WS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "textile",
    "gtin": "04012345678901",
    "product_name": "Natural Cotton T-Shirt",
    "manufacturer": "EcoWear GmbH",
    "origin_country": "PT",
    "market_countries": ["FR"],
    "textile_data": { "fiber_composition": [{ "material": "cotton", "percentage": 100, "recycled_pct": 0 }] }
  }'

La risposta contiene:

data.valid — validità sintattica (Zod)
data.errors[] — classici errori Zod
data.jsonld_preview — anteprima JSON-LD
data.eu_compliance — risultato del validatore UE (null se la validazione Zod fallisce)

Se eu_compliance.summary.errors > 0, la dashboard esegue il rendering di un banner Save-Guard direttamente sopra il pulsante di invio — il salvataggio non viene bloccato, ma vedrai le conseguenze prima di fare clic.

Simulatore live nel dettaglio

Su /dashboard/dpp/:dppId, sotto la sezione di conformità, è presente una scheda simulatore. Consente di modificare i due campi più rilevanti per la conformità (status e market_countries) e di vederne immediatamente l’impatto — senza toccare i dati esistenti. Flusso tipico:

Preview: “Cosa succede se includo la FR nell’assortimento?” → selezionare il chip “FR” → “Preview EU impact” → TEXTILE_AGEC_REQUIRED diventa visibile
Fix: completare la catena di origine (al di fuori del simulatore nel flusso di creazione o bulk)
Save: “Save changes” salva lo stato/l’elenco dei mercati direttamente tramite PUT /v1/dpp/:id

Accesso diretto all’API:

curl -X POST https://qr3.app/v1/dpp/$DPP_ID/validate-update \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Workspace-Id: $WS_ID" \
  -H "Content-Type: application/json" \
  -d '{ "market_countries": ["DE", "FR"], "status": "live" }'

La risposta estende il risultato standard con un oggetto preview:

{
  "data": {
    "compliant": false,
    "espr_ready": false,
    "issues": [/* … */],
    "summary": { "errors": 1, "warnings": 0, "info": 0 },
    "preview": {
      "status": "live",
      "landing_locale": "de",
      "market_countries": ["DE", "FR"],
      "changed_fields": ["status", "market_countries"]
    }
  }
}

changed_fields[] elenca solo i campi che cambierebbero effettivamente — in questo modo puoi, ad esempio, evidenziare solo i chip modificati in un’interfaccia utente.

Un body vuoto è consentito e restituisce la valutazione di conformità corrente (nuova verifica dello stato attuale).

Automazione

Pipeline CI

Un tipico controllo CI:

STATUS=$(curl -s -o /tmp/out.json -w "%{http_code}" \
  https://qr3.app/v1/dpp/$DPP_ID/eu-compliance \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Workspace-Id: $WS_ID")

if [ "$STATUS" != "200" ]; then
  exit 1
fi

jq -e '.data.summary.errors == 0' /tmp/out.json > /dev/null

Server MCP

Il @qr3/mcp-server fornito in dotazione offre, tra le altre cose, uno strumento validate_dpp — gli agenti IA possono utilizzarlo prima della chiamata di creazione per verificare se i dati disponibili sono conformi alle regole AGEC.

Errori comuni

Issue	Causa	Soluzione
`TEXTILE_MICROPLASTICS_CONSISTENCY`	Percentuale di poliestere ≥ 50%, ma flag impostato su `false`	Impostare `contains_microplastics: true`
`TEXTILE_AGEC_REQUIRED` con `hints.market: "FR"`	FR nel mercato, catena incomple	Impostare `country_weaving_knitting`, `country_dyeing_printing`, `country_assembly`
`TEXTILE_GREENWASHING` come `error`	Termine vietato + FR nel mercato	Rimuovere il termine da `product_name` o adattare il mercato
`TEXTILE_SVHC_THRESHOLD`	Sostanza SVHC senza CAS	Inserire il numero CAS dall’elenco REACH

Passaggi successivi

DPP tessile — schema, catena di origine, box di avviso microplastiche
DPP per batterie — campi obbligatori del passaporto della batteria
Riferimento API — tutti gli endpoint di conformità UE nel dettaglio