Provenia API

Jeder Request braucht einen API-Schlüssel im Authorization-Header. Schlüssel erstellst du in der App unter Einstellungen → API (nur Inhaber:innen). Der Schlüssel wird genau einmal angezeigt — wir speichern nur seinen SHA-256-Hash.

curl https://pass.provenia.at/api/v1/me \
  -H "Authorization: Bearer pv_DEIN_SCHLUESSEL"

Widerrufene Schlüssel werden sofort ungültig. Behandle Schlüssel wie Passwörter: nie im Frontend einbetten, nie committen.

Fehler kommen immer in derselben Struktur:

{
  "error": {
    "code": "invalid_api_key",
    "message": "API-Schlüssel fehlt, ist ungültig oder wurde widerrufen."
  }
}

Liefert den Betrieb, der zum Schlüssel gehört — ideal als Verbindungs-Test.

{
  "tenant": { "id": "…", "name": "Leinenweberei Hofer", "slug": "leinenweberei-hofer",
              "country": "AT", "plan": "trial" },
  "products_total": 12
}

curl "…/api/v1/products?status=active&limit=2" -H "Authorization: Bearer pv_…"

{
  "items": [
    { "id": "…", "name": "Leinenhemd Mühlviertel", "slug": "leinenhemd-muehlviertel",
      "status": "active", "gtin": "9012345678901", "completeness": 92,
      "registry_status": "none",
      "unique_product_identifier": "urn:provenia:leinenweberei-hofer:leinenhemd-muehlviertel",
      "created_at": "…", "updated_at": "…" }
  ],
  "total": 5, "limit": 2, "offset": 0
}

curl -X POST …/api/v1/products \
  -H "Authorization: Bearer pv_…" -H "Content-Type: application/json" \
  -d '{ "name": "Tischläufer Leinpfad", "product_group": "textile", "gtin": "9012345678918" }'

→ 200: das angelegte Produkt (gleiche Struktur wie GET /products/{slug})

Das Produkt startet als draft mit stabilem unique_product_identifier — der spätere QR-Link bleibt dauerhaft gültig.

Vollständige Stammdaten inkl. registry_status/registry_id (EU-Register-Vorbereitung) und Produktgruppe.

curl …/api/v1/products/leinenhemd-muehlviertel -H "Authorization: Bearer pv_…"

Alle Pass-Werte (auch restricted/authority — die API ist dein interner Zugriff), inkl. Quelle, Prüf-Status und der letzten Version mit content_hash (Integritätsnachweis).

{
  "product": { "id": "…", "name": "Leinenhemd Mühlviertel", "slug": "…",
               "status": "active", "completeness": 92 },
  "template_version": 1,
  "values": [
    { "field_key": "co2_footprint", "value": "2,4", "unit": "kg CO₂e",
      "source": "supplier", "is_unknown": false, "needs_review": true,
      "access_level": "public", "locale": "de", "updated_at": "…" }
  ],
  "latest_version": { "content_hash": "…", "created_at": "…" }
}

Body ist ein Array von Werten. Bestehende Felder werden aktualisiert, neue angelegt. Die Vollständigkeit wird serverseitig nachgeführt und jede Änderung versioniert (mit content_hash).

curl -X PUT …/api/v1/products/leinenhemd-muehlviertel/passport \
  -H "Authorization: Bearer pv_…" -H "Content-Type: application/json" \
  -d '[
    { "field_key": "co2_footprint", "value": "2,4", "unit": "kg CO₂e" },
    { "field_key": "main_material", "value": "100 % Bio-Leinen" }
  ]'

→ { "updated": 2, "completeness": 92 }

{
  "items": [
    { "id": "…", "type": "qr",
      "gs1_digital_link": "https://…/01/09012345678901",
      "nfc_tag_uid": null, "status": "active", "created_at": "…" }
  ]
}

{
  "days": 30, "total": 1248,
  "per_day": [ { "date": "2026-05-07", "count": 22 }, … ],
  "by_view_role": { "consumer": 1190, "inspector": 41, "recycler": 17 },
  "top_products": [ { "slug": "tischlaeufer-leinpfad", "name": "Tischläufer Leinpfad", "count": 412 }, … ]
}

Es werden keine personenbezogenen Daten erfasst — IPs sind nur als gesalzener Hash gespeichert.

Für aktivierte Pässe — das, was Datenträger und Dritt-Systeme nutzen:

Öffentlich erscheinen nur Felder mit access_level=public aktivierter Produkte. restricted-Felder (Lieferkette, Demontage, Stoffe) gibt es ausschließlich über Prüf-/Recycling-Links mit gültigem Token — die Rolle steckt im Token, ein bloßer ?view=-Parameter genügt nicht. Token erstellst und widerrufst du im Produktdetail unter „Vorschau“.