Programmatischer Zugriff auf die Produktpässe — für Webshop-/ERP-Sync und Massenautomatisierung.

ab dem Pro-Tarif

Während der offenen Beta steht die API allen Beta-Konten zur Verfügung — die Pro-Voraussetzung gilt erst nach der Beta.

Authentifizierung

Jede Anfrage authentifiziert sich mit einem API-Schlüssel im Authorization-Header:

Authorization: Bearer vk_<Ihr Schlüssel>

Einen Schlüssel erstellen Sie unter Einstellungen → Entwickler-API. Den Klartext-Schlüssel zeigen wir nur einmal, bei der Erstellung — bewahren Sie ihn sicher auf. Der Schlüssel gewährt Lese- und Schreibzugriff auf alle Produkte Ihres Kontos, behandeln Sie ihn daher vertraulich.

Schnelltest im Browser

Der Schlüssel gehört ausschließlich in den Authorization-Header — aus Sicherheitsgründen nicht als URL-Parameter (er würde im Browserverlauf und in den Server-Logs landen). Probieren Sie es zum Beispiel mit curl:

curl -H "Authorization: Bearer vk_<Ihr Schlüssel>" https://veridyn.eu/api/v1/categories

Schlüssel-Geltungsbereich (Scope)

Beim Erstellen eines Schlüssels wählen Sie einen Geltungsbereich: Voll (Lesen + Schreiben) oder Nur Lesen (read-only). Ein read-only-Schlüssel darf ausschließlich GET aufrufen — bei POST/PATCH/DELETE lautet die Antwort 403 read_only. Für ERP- oder Anzeige-Integrationen verwenden Sie einen read-only-Schlüssel.

Anfragelimit (Rate Limit)

Pro Schlüssel je nach Tarif 120–600 Anfragen / Minute (Pro 120 · Business 300 · Enterprise 600; während der offenen Beta 300). Jede Antwort enthält die Header X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset (Unix-Zeit). Wird das Limit überschritten, lautet die Antwort 429 rate_limited mit dem Header Retry-After — warten Sie die angegebene Zeit ab und versuchen Sie es dann erneut.

Idempotenz

Sie können POST-Anfragen einen eindeutigen Idempotency-Key-Header mitgeben. Senden Sie die Anfrage mit demselben Schlüssel erneut (z. B. nach einem Netzwerkfehler), erhalten Sie die ursprüngliche Antwort zurück — es entsteht kein Duplikat. Eine wiederholte Antwort erkennen Sie am Header Idempotency-Replayed: true.

OpenAPI

Maschinenlesbare API-Beschreibung (OpenAPI 3.1) — für den Postman-Import und die SDK-/Codegenerierung:

https://veridyn.eu/api/v1/openapi.json

⚡ Interaktive API-Referenz

Durchsuchbare Endpunkt-Referenz zum Blättern — direkt aus der obigen Spezifikation gerendert.

DPP-Vokabular (JSON-LD-Namensraum)

Die maschinenlesbare Fassung des öffentlichen Passes ist JSON-LD: Die Standardfelder stammen von schema.org, die DPP-spezifischen Felder aus dem Namensraum dpp:. Dieser Namensraum ist auflösbar — öffnen Sie ihn, um die Bedeutung jedes Feldes zu sehen; mit dem Header Accept: application/ld+json liefert er das maschinenlesbare @context-Dokument.

https://veridyn.eu/ns/dpp/v1/

Ein einzelner Pass als Daten: die öffentliche URL mit ?format=jsonld (oder dem Header Accept: application/ld+json).

Postman-Collection

Fertige, importierbare Collection (mit voreingestellten Variablen und Beispielanfragen). Nach dem Import füllen Sie nur die Collection-Variablen base_url und api_key aus.

⬇ Postman-Collection herunterladen

Eigenes SDK generieren

Aus der OpenAPI-Spezifikation erzeugen Sie mit openapi-generator einen offiziellen Client für jede Sprache — kein handgepflegtes SDK, immer aktuell. Z. B. PHP:

npx @openapitools/openapi-generator-cli generate \
  -i https://veridyn.eu/api/v1/openapi.json \
  -g php -o ./veridyn-sdk

Der Wert von -g kann typescript-fetch, python, java und vieles mehr sein.

Schnellstart (Code)

PHP

$ch = curl_init('https://veridyn.eu/api/v1/products?limit=5');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => ['Authorization: Bearer vk_...'],
]);
$products = json_decode(curl_exec($ch), true)['data'];

JavaScript (fetch)

const res = await fetch('https://veridyn.eu/api/v1/products?limit=5', {
  headers: { 'Authorization': 'Bearer vk_...' }
});
const { data } = await res.json();

Basis-URL

https://veridyn.eu/api/v1

Die Antworten haben das Format application/json und sind UTF-8-kodiert.

Endpunkte

Methode	Pfad	Beschreibung
GET	/categories	Verfügbare Produktkategorien.
GET	/schema/{category}	Die vollständige Feldliste der Kategorie — Pflicht + optional, Typ, Enum, sprachabhängige Felder.
GET	/products	Liste der Produkte (Zusammenfassung). Parameter: q, status, page, limit.
POST	/products	Neuer Produktpass. Body: { category, data }.
GET	/products/{id}	Die vollständigen Daten eines Produkts + Pass-URL.
PATCH	/products/{id}	Aktualisierung (partiell) — erzeugt eine neue Version. Body: { data, change_type? }. change_type ist optional: correction (im Modell standen falsche Daten → bereits ausgegebene Chargen-/Stückpässe veralten und können aufgefrischt werden) oder change (das Produkt hat sich ab einem bestimmten Datum geändert → die Daten früherer Stücke bleiben korrekt und werden nicht überschrieben).
GET	/products/{id}/qr	QR-Code (SVG) für den öffentlichen Produktpass.
GET	/products/{id}/children	Liste der untergeordneten Chargen-/Stückpässe.
POST	/products/{id}/children	Chargen-/Stückpass. Einzeln: { level, lot|serial, data } · als Masse: { level, items:[…] } (max. 500). Erbt die Daten des Elternpasses.
GET	/products/{id}/scans	Scan-Zusammenfassung je Produkt: total, unique, byCountry, byDevice. Parameter: days=7|30|90|365.
GET	/scans	Kontoweite Scan-Zusammenfassung: das Obige + byCategory, byLevel.

Was müssen Sie angeben? (Pflicht vs. optional)

Jede Kategorie hat einen Pflichtkern — ohne ihn weist die Schemavalidierung die Anfrage ab (422). Alle übrigen Felder sind optional, Sie können sie aber jederzeit im selben data-Objekt mitschicken (mehr Daten = besserer Produktpass und zukunftssicherere Compliance). Die genaue, maschinenlesbare Feldliste liefert /schema/{category} — mit required: true/false, Typ, Enum und localized-Kennzeichnung.

curl https://veridyn.eu/api/v1/schema/textile \
  -H "Authorization: Bearer vk_<kulcs>"

Alle Felder nach Kategorie

✓ = Pflicht · — = optional · ↳ verschachteltes Unterfeld · 🌐 je Sprache (localized) · 🔒 nur auf Behördenebene sichtbar. Diese Liste wird aus dem Schema generiert — immer aktuell.

Sprachen

Das Feld languages (z. B. ["hu","en"]) deklariert, in welchen Sprachen Freitextinhalte vorliegen. Die lokalisierten Felder (Pflege, Lebensende … — im /schema mit "localized": true) müssen nur in der ersten (primären) Sprache ausgefüllt werden; die übrigen sind optional und fallen bei Fehlen auf eine verfügbare Sprache zurück. Die UI-Beschriftungen des Produktpasses werden davon unabhängig automatisch in 24 Sprachen übersetzt.

Beispiele

Produkt anlegen

curl -X POST https://veridyn.eu/api/v1/products \
  -H "Authorization: Bearer vk_<kulcs>" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "textile",
    "data": {
      "productName": "Bio-Baumwoll-T-Shirt",
      "sku": "TEE-001",
      "brandName": "Lumora",
      "languages": ["hu","en"],
      "fiberComposition": [{"fiber":"pamut","percentage":100}],
      "countryOfManufacture": "PT",
      "careInstructions": {"hu":"Mosás 30 °C","en":"Wash at 30 °C"},
      "repair": {"repairable": true, "sparePartsAvailable": false},
      "endOfLife": {
        "recyclingInstructions": {"hu":"Textilgyűjtő","en":"Textile bin"},
        "disposalInstructions": {"hu":"Ne a kukába","en":"Not household waste"}
      },
      "economicOperator": {
        "role":"manufacturer","legalName":"Lumora Kft.","address":"Budapest",
        "country":"HU","contactEmail":"[email protected]"
      }
    }
  }'

Antwort (201):

{
  "data": {
    "id": "a1993ef7-7562-43bb-92ff-eb63f02dcde9",
    "category": "textile",
    "status": "active",
    "version_no": 1,
    "passport_url": "https://veridyn.eu/<fiók>/p/a1993ef7-…",
    "qr_url": "https://veridyn.eu/api/v1/products/a1993ef7-…/qr",
    "data": { "productName": "Bio-Baumwoll-T-Shirt", … }
  }
}

Auflisten

curl https://veridyn.eu/api/v1/products?limit=25 \
  -H "Authorization: Bearer vk_<kulcs>"

Ein Produkt abrufen

curl https://veridyn.eu/api/v1/products/{id} \
  -H "Authorization: Bearer vk_<kulcs>"

Aktualisierung (neue Version)

curl -X PATCH https://veridyn.eu/api/v1/products/{id} \
  -H "Authorization: Bearer vk_<kulcs>" \
  -H "Content-Type: application/json" \
  -d '{"data": {"recycledContentPercentage": 30}}'

Die übergebenen Felder werden mit den vorhandenen Daten zusammengeführt (Teilaktualisierung), anschließend validiert, und es entsteht eine neue, aufbewahrte Version — die vollständige Änderungshistorie bleibt erhalten.

Chargen- und Stückpass (Serialisierung)

Sie erstellen unter einem Modell Chargen- oder Stückpässe; das Kind erbt die Daten des Elternpasses — Sie geben nur die exemplarspezifischen Felder (lot/serial) an. Auch mehrere auf einmal (items[], max. 500); die Antwort meldet Erfolg/Fehler je Zeile.

curl -X POST https://veridyn.eu/api/v1/products/{id}/children \
  -H "Authorization: Bearer vk_<kulcs>" \
  -H "Content-Type: application/json" \
  -d '{"level":"item","items":[{"serial":"SN-0001"},{"serial":"SN-0002"}]}'

Die {id} kann ein Modell oder eine Charge sein. Ein POST auf eine Chargen-ID mit level:"item" legt das Stück unter dieser Charge an und übernimmt deren Lot — der GS1-Link lautet dann …/10/lot/21/serial statt …/21/serial. So entsteht die vollständige Kette Modell → Charge → Stück.

Scan-Analytik

Aggregierte Statistik der QR-Scans — je Produkt oder für das gesamte Konto —, aufgeschlüsselt nach Land und Gerät. Datenschutz: keine rohen IP-Adressen; eindeutige Besucher sind eine anonyme Hash-Schätzung.

curl "https://veridyn.eu/api/v1/products/{id}/scans?days=30" \
  -H "Authorization: Bearer vk_<kulcs>"

{
  "data": {
    "product_id": "a1993ef7-…",
    "range_days": 30,
    "total": 189, "unique": 142,
    "byCountry": { "HU": 142, "DE": 38, "AT": 9 },
    "byDevice":  { "mobile": 168, "tablet": 9, "desktop": 12 }
  }
}

Antwort & Fehler

Erfolg: die Nutzdaten stehen unter dem Schlüssel data. Im Fehlerfall:

{ "error": "Ungültige Daten.", "code": "validation", "errors": [ … ] }

HTTP	code	Bedeutung
401	unauthorized	Fehlender/ungültiger API-Schlüssel.
403	plan_required	Die API ist ab dem Pro-Tarif verfügbar (während der offenen Beta kann sie jedes Beta-Konto nutzen).
404	not_found	Produkt oder Pfad nicht gefunden.
409	gtin_taken	Die GTIN ist bereits vergeben.
403	plan_limit	Sie haben das Kontingent dieser Ebene erreicht (Tarif + Extra). Bei Massenaufrufen landen die überzähligen Einträge in errors.
422	validation	Ungültige Daten (Details in errors).

Webhooks

Unter Einstellungen → Webhooks registrieren Sie eine HTTPS-URL. Sobald ein Produktpass erstellt / aktualisiert / archiviert wird, sendet Veridyn ein signiertes JSON per POST an diese URL — so wird Ihr System in Echtzeit benachrichtigt, ohne Polling.

Ereignisse

product.created · product.updated · product.archived · product.restored · scan.milestone · scan.clone_suspected

scan.milestone wird ausgelöst, wenn die Scan-Zahl eines Produktpasses einen Meilenstein überschreitet (10, 50, 100, 250, 500, 1000, …) — z. B. „Ihr Produktpass wurde 1000-mal geöffnet“. Daten: { product_id, count, milestone }.

scan.clone_suspected weist auf eine mögliche Fälschung hin: Ein eindeutiger (serialisierter) Pass wurde ungewöhnlich oft und aus vielen verschiedenen Ländern bzw. von vielen Geräten gescannt — das kann auf einen kopierten QR-Code hindeuten. Daten: { product_id, count, countries, unique_devices }.

Zustellung

POST https://your-system.example/veridyn-webhook
Content-Type: application/json
X-Veridyn-Event: product.updated
X-Veridyn-Signature: sha256=<hmac>

{
  "event": "product.updated",
  "data": { "id": "a1993ef7-…", "category": "textile", "version_no": 2 },
  "sent_at": "2026-07-02T13:19:11+00:00"
}

Signaturprüfung

X-Veridyn-Signature ist die HMAC-SHA256-Signatur des Roh-Bodys mit dem Secret des Webhooks (in den Einstellungen sichtbar). So prüfen Sie sie — z. B. in PHP:

$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_VERIDYN_SIGNATURE'] ?? '')) {
    http_response_code(401); exit; // ungültige Signatur}

Antworten Sie mit einem 2xx-Status. Schlägt die Zustellung fehl (kein 2xx / Zeitüberschreitung), wiederholen wir sie automatisch mit exponentiellem Backoff (ca. 1 Minute → 5 Minuten → 30 Minuten → 2 Stunden → 6 Stunden, max. 6 Versuche); bei dauerhaftem Fehler geben wir auf. Den Status der letzten Zustellung sehen Sie in den Einstellungen.

← Einstellungen / API-Schlüssel