API für den Digitalen Produktpass: Dokumentation für Entwickler

Überblick

Die Kunden-API ist eine REST-Schnittstelle mit JSON. Sie arbeitet auf Ihren Mandantendaten, also auf denselben Produkten und Passports, die Sie in der Weboberfläche sehen. Typische Einsatzfälle sind die Anbindung an ein ERP- oder PLM-System, ein nächtlicher Abgleich von Stammdaten oder ein Skript, das QR-Codes für den Druck holt.

Die Basis-URL lautet https://dpp.com2u.selfhost.eu/api/v1/integration. Alle Antworten sind JSON, ausgenommen die Downloads von QR-Code und PDF.

Spezifikation herunterladen

Die maschinenlesbare Referenz aller Endpunkte, Felder, Beispiele und Fehlerantworten ist eine OpenAPI-3.1-Spezifikation mit dem Sicherheitsschema ApiKeyAuth:

• openapi.json herunterladen
• openapi.yaml herunterladen

Dieselbe Datei liefert die API selbst unter GET /api/v1/integration/openapi.json, ohne Key. Importieren Sie sie in Swagger UI, Postman oder einen Code-Generator Ihrer Wahl.

Schnellstart

1. Registrieren Sie sich oder melden Sie sich an. Die API gehört zu den bezahlten Tarifen, siehe Preise.
2. Öffnen Sie in der Plattform den Bereich Mandant und erzeugen Sie den API-Key. Kopieren Sie ihn sofort, denn er wird nur einmal angezeigt.
3. Testen Sie die Verbindung:

curl -H "X-API-Key: $DPP_API_KEY" \
  https://dpp.com2u.selfhost.eu/api/v1/integration/me

Die Antwort nennt Ihren Mandanten, die Scopes des Keys, Ihren Tarif und den Verbrauch an API-Aufrufen.

Authentifizierung

Senden Sie den Key bei jedem Aufruf im Header X-API-Key. Gleichwertig ist Authorization: Bearer dpp_key_…. Der Mandant ergibt sich immer aus dem Key, eine Mandanten-ID als Parameter wird nicht ausgewertet. Sitzungs-Tokens der Weboberfläche akzeptiert die API nicht.

Der Key gehört zu der Person, die ihn erzeugt hat. Aktionen laufen mit deren Rechten als Owner oder Admin. Verliert die Person diese Rolle, antwortet die API mit 403, bis ein neuer Key erzeugt wurde. Eine Neuerzeugung widerruft den bisherigen Key sofort. Die Plattform speichert nur einen SHA-256-Hash des Keys.

Endpunkte

Alle Pfade stehen unter /api/v1/integration. Jeder Endpunkt verlangt einen Scope, ein neuer Key trägt alle vier.

Produkt anlegen

name ist Pflicht. Ohne schema_key gilt das Standard-Schema Ihres Mandanten; verfügbare Schlüssel liefert GET /schemas. Datenfelder lassen sich direkt mitgeben. Mit field_status bestimmen Sie den Status der Werte, nur approved fließt in einen Passport.

curl -X POST https://dpp.com2u.selfhost.eu/api/v1/integration/products \
  -H "X-API-Key: $DPP_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Batteriemodul X1","category":"Industriebatterien",
       "manufacturer_ref":"ART-4711","schema_key":"battery-v1",
       "fields":{"battery_chemistry":"LFP"},"field_status":"approved"}'

Die Antwort mit Status 201 enthält die id des Produkts. Sie ist zugleich der eindeutige Produktidentifikator, der im QR-Code steckt. Das Produktkontingent Ihres Tarifs gilt wie in der Weboberfläche.

Passport veröffentlichen, QR-Code und PDF laden

Ein Passport friert die freigegebenen Datenfelder als neue Version ein. Fehlen Pflichtfelder, antwortet die API mit 422 und nennt sie in missing_fields.

curl -X POST -H "X-API-Key: $DPP_API_KEY" \
  https://dpp.com2u.selfhost.eu/api/v1/integration/products/{id}/passports

curl -o qr.png -H "X-API-Key: $DPP_API_KEY" \
  "https://dpp.com2u.selfhost.eu/api/v1/integration/products/{id}/passport/qr?format=png&size=600"

curl -o passport.pdf -H "X-API-Key: $DPP_API_KEY" \
  https://dpp.com2u.selfhost.eu/api/v1/integration/products/{id}/passport/pdf

Für den QR-Code in Vektorform nutzen Sie format=svg. Das PDF gibt es erst nach der Veröffentlichung, vorher antwortet die API mit 404. Der QR-Code verweist auf die öffentliche Passportseite, mehr dazu unter Digitalen Produktpass aus Excel erstellen.

Fehlercodes

Bei 401 und 403 enthält detail ein Objekt mit code und message, zum Beispiel insufficient_scope oder api_not_in_plan. Bei 402 nennt detail Ressource, Limit und bisherigen Verbrauch.

Grenzen

Über die API setzen Sie Datenfelder der Produktebene. Felder für Chargen oder Einzelartikel pflegen Sie in der Weboberfläche. Es gibt kein Ratenlimit, aber ein Aufruf-Kontingent je Tarif; jeder authentifizierte Aufruf zählt. Das Abrufen der Spezifikation zählt nicht. Aktuelle Tarife und Kontingente finden Sie auf der Seite Preise. Eine Vorlage für den Massenimport ohne API bietet die Datenvorlage.