Entwickler / REST API

API-Referenz

Alles in MyProductPassport ist über eine per Schlüssel authentifizierte REST-API verfügbar: Produkte anlegen, digitale Produktpässe erstellen und veröffentlichen, aktuelle Batteriedaten übermitteln und die Konformität prüfen, direkt aus Ihrem ERP, PIM oder Ihrer Build-Pipeline.

v1 https://myproductpassport.eu/api/v1 Kostenlos starten OpenAPI-Spezifikation ↓

01 / Erste SchritteAuthentifizierung

Jede Anfrage wird mit einem API-Schlüssel authentifiziert, der als Bearer-Token übergeben wird. Schlüssel werden in der App unter API-Schlüssel erstellt, nur einmal angezeigt und gehasht gespeichert; jeder Schlüssel hat eigene Berechtigungen, eine optionale IP-Freigabeliste und ein optionales Ablaufdatum. Schlüssel lassen sich ohne Ausfallzeit rotieren.

Anfrage-Header

Authorization: Bearer pk_your_api_key

In jedem Tarif. API-Schlüssel lassen sich in jedem Tarif erstellen und nutzen, auch im kostenlosen. Der Tarif bestimmt, wie viele Anfragen ein Schlüssel pro Minute stellen darf (siehe unten) und wie viele Produkte und Pässe der Arbeitsbereich führen darf.

Testmodus. Ein Testschlüssel (pk_test_...) führt jeden Aufruf genau wie ein Live-Schlüssel aus, mit derselben Validierung, denselben IDs und denselben Antworten, und macht ihn anschließend rückgängig: Es wird nichts gespeichert, keine E-Mail und kein Webhook versendet und keine Datei behalten. Antworten enthalten "test_mode": true und einen X-MPP-Mode: test-Header. Entwickeln und testen Sie eine Integration mit Ihren echten Daten und setzen Sie dann einen Live-Schlüssel ein.

Berechtigungen werden pro Schlüssel vergeben, sodass eine Integration nur erhält, was sie braucht:

Berechtigung	Freigaben
products:read	Produkte lesen
products:write	Produkte erstellen, aktualisieren und löschen
passports:read	Pässe lesen
passports:write	Pässe generieren
passports:publish	Pässe veröffentlichen und archivieren
webhooks:manage	Webhook-Endpunkte erstellen, testen und entfernen
items:read	Read individual items and their history
items:write	Add, update and flag individual items
aftersales:read	Read owner registrations and service requests
aftersales:write	Update service requests and reply to customers

02 / Erste SchritteRatenlimits

Die Limits gelten pro Schlüssel und Minute und richten sich nach dem Tarif:

Plan	Anfragen / Minute
Kostenlos	30
Micro	60
E-Label	60
Starter	120
Professional	300
Business	600
Battery	600

Jede Antwort enthält die Header X-RateLimit-Limit und X-RateLimit-Remaining. Bei Überschreitung des Limits wird 429 zurückgegeben:

429 Too Many Requests

{ "error": "Rate limit exceeded.", "limit": 300, "retry_after": 60 }

03 / Erste SchritteFehler

Fehler werden als JSON mit einem üblichen Statuscode zurückgegeben. Die häufigsten:

Status	Bedeutung	Beispielinhalt
401	Fehlender, ungültiger, widerrufener oder abgelaufener Schlüssel	`{"error": "Invalid or revoked API key."}`
403	Dem Schlüssel fehlt eine Berechtigung, die IP steht nicht auf der Freigabeliste oder das Kontingent des Tarifs ist erreicht	`{"message": "API key does not have 'products:write' permission."}`
404	Die Ressource existiert in Ihrem Arbeitsbereich nicht	`{"message": "Not found."}`
422	Validierung fehlgeschlagen	`{"message": "…", "errors": {"gtin": ["…"]}}`
429	Ratenlimit überschritten	`{"error": "Rate limit exceeded."}`

04 / Erste SchrittePaginierung

Listen-Endpunkte liefern 25 Einträge pro Seite mit den üblichen links- und meta-Objekten. Übergeben Sie ?page=2, um durch die Sammlung zu blättern.

05 / Erste SchritteKI-Assistent-Connector (MCP)

Verbinden Sie Claude, Cursor oder jeden Assistenten, der das Model Context Protocol spricht, und bitten Sie ihn in einfachen Worten, Produkte anzulegen, Pässe mit Ihren Angaben auszufüllen und zu prüfen, was noch fehlt. Er nutzt einen API-Schlüssel mit dessen Berechtigungen und Anfragelimit. Er kann Entwürfe anlegen und Felder ausfüllen; er veröffentlicht, archiviert oder löscht nie etwas: Das bleibt bei Ihnen in der App.

Serveradresse (Streamable HTTP)

https://myproductpassport.eu/api/mcp

Claude Code

claude mcp add --transport http myproductpassport https://myproductpassport.eu/api/mcp \
  --header "Authorization: Bearer pk_live_your_key"

Cursor (mcp.json)

{
  "mcpServers": {
    "myproductpassport": {
      "url": "https://myproductpassport.eu/api/mcp",
      "headers": { "Authorization": "Bearer pk_live_your_key" }
    }
  }
}

Claude Desktop und andere Clients, die einen lokalen Server starten

{
  "mcpServers": {
    "myproductpassport": {
      "command": "npx",
      "args": ["mcp-remote", "https://myproductpassport.eu/api/mcp", "--header", "Authorization: Bearer pk_live_your_key"]
    }
  }
}

Die verfügbaren Werkzeuge:

Tool	Was es tut
list_products	Die Produkte des Arbeitsbereichs, neueste zuerst, 25 pro Seite, mit Sektor und neuestem Pass.
get_product	Ein Produkt mit Details, Sektor, regulatorischen Abschnitten und neuestem Pass.
list_sectors	Die Sektorvorlagen, die ein Produkt nutzen kann (Textilien, Elektronik, Batterien, Wein und mehr), mit ihren IDs. Der Sektor eines Produkts bestimmt, welche Passfelder Pflicht sind.
create_product	Legt ein Produkt im Arbeitsbereich an. Verwenden Sie eine sector_id aus list_sectors. compliance_sections fügt seinem Pass regulatorische Abschnitte hinzu: gpsr, epr, france, chemicals, eudr.
list_passports	Die Pässe des Arbeitsbereichs, neueste zuerst, 25 pro Seite, mit Status (draft, published, archived), Vollständigkeit und öffentlicher Adresse.
get_passport	Ein Pass: Status, Version, Vollständigkeit, öffentliche Adresse und QR-Code-Links.
create_passport	Legt einen Passentwurf für ein Produkt an. Er wird nicht veröffentlicht: Das tut eine Person in der App.
get_passport_fields	Was ein Pass verlangt: Pflicht- und optionale Feldschlüssel, was jeder bedeutet (Bezeichnung, Beschreibung, Beispiel), die vorhandenen Werte und welche Pflichtfelder fehlen.
update_passport_fields	Schreibt Feldwerte in einen Entwurf oder veröffentlichten Pass (ein veröffentlichter wird an Ort und Stelle aktualisiert: gleiche Adresse, gleicher QR-Code). Schlüssel aus get_passport_fields; ein leerer Text entfernt einen Wert. Nur Fakten schreiben, die der Nutzer oder seine Dokumente angeben.
get_compliance	Die Vollständigkeit eines Passes: Prozentsatz, Status und die noch fehlenden Pflichtfelder.

Mit einem Testschlüssel ausprobieren. Mit einem Testschlüssel (pk_test_...) werden die Änderungen des Assistenten geprüft und dann rückgängig gemacht, sodass Sie sehen, was er tun würde, bevor Sie ihm einen Live-Schlüssel geben.

06 / EndpunkteKonto

GET /me

Gibt das authentifizierte Konto, seinen Abonnementtarif und den genutzten Anteil des Produktkontingents zurück. Nützlich als Verbindungstest.

Anfrage

curl https://myproductpassport.eu/api/v1/me \
  -H "Authorization: Bearer pk_your_key"

Antwort

{
  "data": {
    "id": 42,
    "name": "Jane Doe",
    "email": "[email protected]",
    "company_name": "Acme Ltd",
    "subscription_tier": "professional",
    "product_count": 128,
    "product_limit": 500,
    "passport_count": 96,
    "organization": {"id": 7, "name": "Acme Ltd"},
    "api_key": {"name": "ERP sync", "permissions": ["*"], "rate_limit_per_minute": 1000, "expires_at": null},
    "webhooks_available": true
  }
}

07 / EndpunkteProdukte

GET /products erfordert products:read

Listet die Produkte in Ihrem Arbeitsbereich auf, neueste zuerst, 25 pro Seite. Jedes Produkt enthält seinen Sektor und eine Übersicht des neuesten Passes.

Parameter	Art		Beschreibung
page	integer		Seitennummer.

Anfrage

curl "https://myproductpassport.eu/api/v1/products?page=1" \
  -H "Authorization: Bearer pk_your_key"

Antwort

{
  "data": [
    {
      "id": 512,
      "name": "Alpine Merino Crew Sweater",
      "sku": "AM-CREW-01",
      "gtin": "05012345678900",
      "brand": "Northloom",
      "category": "textiles",
      "status": "active",
      "country_of_origin": "PT",
      "weight": 0.4,
      "weight_unit": "kg",
      "materials": [
        { "name": "Merino wool (RWS)", "percentage": 78 },
        { "name": "Recycled nylon (GRS)", "percentage": 20 },
        { "name": "Elastane", "percentage": 2 }
      ],
      "sector": { "id": 3, "name": "Textiles" },
      "latest_passport": {
        "id": 96, "version": 1,
        "status": "published", "compliance_percentage": 100
      },
      "created_at": "2026-08-14T09:21:00+00:00",
      "updated_at": "2026-09-01T16:02:11+00:00"
    }
  ],
  "links": { "next": null },
  "meta": { "current_page": 1, "per_page": 25, "total": 1 }
}

POST /products erfordert products:write

Legt ein Produkt an. Schlägt mit 403 fehl, wenn das Produktkontingent des Tarifs ausgeschöpft ist.

Parameter	Art		Beschreibung
name	string	erforderlich	Produktname, bis zu 255 Zeichen.
sku	string		Ihre interne SKU, bis zu 100 Zeichen.
gtin	string		GTIN-8, 12, 13 oder 14 (nur Ziffern).
brand	string		Marke, die im öffentlichen Pass angezeigt wird.
description	string		Bis zu 2.000 Zeichen.
category	string		Freitext-Kategorie. Standardwert „general“.
sector_id	integer		Eine Sektor-ID, die die Feldvorlage des Passes bestimmt.
country_of_origin	string		Ländercode, z. B. „PT“.
weight	number		Nettogewicht.
weight_unit	string		Einer der Werte kg, g, lb, oz. Standard ist kg.
materials	array		Objekte aus {name, percentage 0-100}.
has_packaging	boolean		Fügt dem Pass die Felder der Verpackungsvorlage hinzu (Schlüssel beginnen mit pkg_), unter demselben QR-Code.

Anfrage

curl -X POST https://myproductpassport.eu/api/v1/products \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alpine Merino Crew Sweater",
    "sku": "AM-CREW-01",
    "gtin": "05012345678900",
    "sector_id": 3,
    "materials": [
      {"name": "Merino wool (RWS)", "percentage": 78},
      {"name": "Recycled nylon (GRS)", "percentage": 22}
    ]
  }'

Antwort

{
  "data": {
    "id": 513,
    "name": "Alpine Merino Crew Sweater",
    "sku": "AM-CREW-01",
    "status": "active",
    "sector": { "id": 3, "name": "Textiles" },
    "created_at": "2026-09-07T18:40:00+00:00"
  }
}

POST /products/bulk erfordert products:write

Legt bis zu 100 Produkte in einem Aufruf an. Der gesamte Stapel wird mit 403 abgelehnt, wenn er Ihr verbleibendes Produktkontingent überschreiten würde. Für Kataloge mit Tausenden von Artikeln rufen Sie diesen Endpunkt in einer Schleife auf oder nutzen den CSV-Import in der App.

Parameter	Art		Beschreibung
products	array	erforderlich	1 bis 100 Produktobjekte mit denselben Feldern wie „Produkt anlegen“ (ohne Materialien).

Anfrage

curl -X POST https://myproductpassport.eu/api/v1/products/bulk \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {"name": "PSL-BT-122000", "sku": "PSL-BT-122000", "sector_id": 5},
      {"name": "PSL-BT-123000", "sku": "PSL-BT-123000", "sector_id": 5}
    ]
  }'

Antwort

{
  "message": "2 product(s) created.",
  "products": [
    { "id": 514, "name": "PSL-BT-122000", "status": "active" },
    { "id": 515, "name": "PSL-BT-123000", "status": "active" }
  ]
}

GET /products/{id} erfordert products:read

Gibt ein Produkt mit seinem Sektor und einer Übersicht des neuesten Passes zurück. 404, wenn die ID nicht in Ihrem Arbeitsbereich ist.

Anfrage

curl https://myproductpassport.eu/api/v1/products/512 \
  -H "Authorization: Bearer pk_your_key"

PUT /products/{id} erfordert products:write

Aktualisiert ein Produkt teilweise. Senden Sie nur die Felder, die Sie ändern möchten; die Feldliste entspricht „Produkt erstellen“.

Anfrage

curl -X PUT https://myproductpassport.eu/api/v1/products/512 \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"brand": "Northloom"}'

DELETE /products/{id} erfordert products:write

Löscht ein Produkt vorläufig (Soft Delete). Veröffentlichte Pässe des Produkts funktionieren weiter, sodass gedruckte QR-Codes nie ins Leere führen.

Anfrage

curl -X DELETE https://myproductpassport.eu/api/v1/products/512 \
  -H "Authorization: Bearer pk_your_key"

Antwort

{ "message": "Product deleted." }

08 / EndpunktePässe

GET /passports erfordert passports:read

Listet Pässe auf, neueste zuerst, 25 pro Seite, mit Produktübersicht und allen Passfeldern.

Parameter	Art		Beschreibung
page	integer		Seitennummer.

Anfrage

curl https://myproductpassport.eu/api/v1/passports \
  -H "Authorization: Bearer pk_your_key"

Antwort

{
  "data": [
    {
      "id": 96,
      "uuid": "36ff3776-d517-4228-8cde-9208136ea84a",
      "version": 1,
      "status": "published",
      "compliance_status": "compliant",
      "compliance_percentage": 100,
      "public_url": "https://myproductpassport.co.uk/p/36ff3776-…",
      "gs1_url": "https://myproductpassport.co.uk/01/05012345678900",
      "product": { "id": 512, "name": "Alpine Merino Crew Sweater", "sku": "AM-CREW-01" },
      "fields": [
        { "key": "material_composition", "value": "…", "verification_status": "verified" }
      ],
      "published_at": "2026-08-16T10:00:00+00:00"
    }
  ],
  "meta": { "current_page": 1, "per_page": 25, "total": 1 }
}

POST /products/{productId}/passports erfordert passports:write

Erstellt einen Passentwurf für ein Produkt und füllt die Felder aus den Produktdaten und der Sektorvorlage vor. Gibt den Entwurf mit seinem Konformitätswert zurück. Hat das Produkt bereits einen aktiven Pass, wird 409 mit diesem Pass zurückgegeben: Korrigieren Sie ihn mit PUT /passports/{id}/fields, wobei Adresse und QR-Code erhalten bleiben.

Anfrage

curl -X POST https://myproductpassport.eu/api/v1/products/512/passports \
  -H "Authorization: Bearer pk_your_key"

GET /passports/{id} erfordert passports:read

Gibt einen Pass mit Produkt, Feldern, öffentlicher URL und GS1 Digital Link zurück.

Anfrage

curl https://myproductpassport.eu/api/v1/passports/96 \
  -H "Authorization: Bearer pk_your_key"

POST /passports/{id}/publish erfordert passports:publish

Veröffentlicht einen Passentwurf und schaltet seine öffentliche Seite und seinen QR-Code live. Nur Entwürfe können veröffentlicht werden; alles andere liefert 404.

Anfrage

curl -X POST https://myproductpassport.eu/api/v1/passports/96/publish \
  -H "Authorization: Bearer pk_your_key"

POST /passports/{id}/archive erfordert passports:publish

Archiviert einen Pass und nimmt seine öffentliche Seite aus dem Umlauf.

Anfrage

curl -X POST https://myproductpassport.eu/api/v1/passports/96/archive \
  -H "Authorization: Bearer pk_your_key"

POST /passports/bulk-publish erfordert passports:publish

Veröffentlicht bis zu 50 Passentwürfe in einem Aufruf und meldet das Ergebnis je Pass, sodass ein Fehler nie den ganzen Stapel abbricht.

Parameter	Art		Beschreibung
passport_ids	array	erforderlich	1 bis 50 Pass-IDs.

Anfrage

curl -X POST https://myproductpassport.eu/api/v1/passports/bulk-publish \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"passport_ids": [96, 97, 98]}'

Antwort

{
  "published": 2,
  "failed": 1,
  "published_ids": [96, 97],
  "errors": [
    { "id": 98, "error": "Compliance below the publishing threshold." }
  ]
}

POST /passports/{id}/successor erfordert passports:write

Für ein Produkt, das zur Wiederverwendung vorbereitet, umgenutzt oder wiederaufbereitet wurde, verlangt die Batterieverordnung (Artikel 77 Absatz 7) einen neuen, mit dem Original verknüpften Pass. Dies legt einen neuen Produktdatensatz und einen aus dem veröffentlichten Pass vorausgefüllten Entwurf an, der auf ihn verweist. Das Original bleibt live, und beide Pässe zeigen die Verknüpfung. Veröffentlichen Sie den neuen mit POST /passports/{id}/publish.

Parameter	Art		Beschreibung
stage	string	erforderlich	prepared_for_reuse, repurposed oder remanufactured.

Anfrage

curl -X POST https://myproductpassport.eu/api/v1/passports/96/successor \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "stage": "repurposed" }'

Antwort

{
  "data": {
    "id": 131, "status": "draft", "version": 1,
    "lineage": {
      "stage": "repurposed",
      "original": { "id": 96, "url": "https://myproductpassport.co.uk/p/..." },
      "originals": [{ "passport_id": 96, "product_id": 40, "stage": "repurposed", "status": "published", "url": "https://myproductpassport.co.uk/p/..." }],
      "successors": []
    }
  }
}

GET /passports/{id}/fields erfordert passports:read

Gibt die Feldschlüssel zurück, die die Sektorvorlage des Passes verlangt (Pflicht und optional), die aktuell gespeicherten Werte und welche Pflichtschlüssel noch fehlen. Verwenden Sie dies, um die Nutzlast für PUT /passports/{id}/fields zu erstellen.

Anfrage

curl https://myproductpassport.eu/api/v1/passports/96/fields \
  -H "Authorization: Bearer pk_your_key"

Antwort

{
  "passport_id": 96,
  "sector": "batteries",
  "compliance_percentage": 84,
  "required": ["battery_category", "carbon_footprint", "..."],
  "optional": ["energy_round_trip_efficiency", "..."],
  "missing_required": ["carbon_footprint_class", "recycled_content"],
  "values": { "battery_category": "Industrial", "...": "..." }
}

PUT /passports/{id}/fields erfordert passports:write

Schreibt beliebige Feldwerte in einen Entwurf oder einen veröffentlichten Pass: den vollständigen Satz nach Anhang XIII für eine Batterie, die Felder einer Sektorvorlage oder eigene Schlüssel. Senden Sie nur die Schlüssel, die Sie ändern möchten; ein null- oder leerer Wert entfernt das Feld. Ein veröffentlichter Pass wird direkt aktualisiert, seine Adresse und sein QR-Code bleiben gleich, und seine maschinellen Übersetzungen werden neu erzeugt. Die Compliance wird neu bewertet. Ein Entwurf wird durch diesen Aufruf nicht veröffentlicht; verwenden Sie POST /passports/{id}/publish.

Parameter	Art		Beschreibung
fields	object	erforderlich	Zuordnung von Feldschlüssel zu Wert. Schlüssel bestehen aus Kleinbuchstaben, Ziffern und Unterstrichen; Werte bis zu 5.000 Zeichen. Bis zu 200 Schlüssel pro Aufruf.

Anfrage

curl -X PUT https://myproductpassport.eu/api/v1/passports/96/fields \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "carbon_footprint": "61.2 kg CO2e/kWh",
      "carbon_footprint_class": "C",
      "recycled_content": "Cobalt 16%, lithium 6%, nickel 6%, lead 0%"
    }
  }'

Antwort

{
  "message": "3 field(s) changed, 0 removed.",
  "changed": ["carbon_footprint", "carbon_footprint_class", "recycled_content"],
  "removed": [],
  "passport": { "id": 96, "status": "published", "compliance_percentage": 92 }
}

POST /passports/{id}/state-of-health erfordert passports:write

Überträgt die Daten dieser einzelnen Batterie (Anhang XIII Nummer 4 der Verordnung (EU) 2023/1542) auf einen veröffentlichten Pass, für BMS- und Flottensysteme. Senden Sie eine beliebige Teilmenge der folgenden Felder; die Compliance wird nach dem Update neu geprüft. Diese Werte werden nur Betrachtern angezeigt, die der Passinhaber freigegeben hat (Artikel 77 Absatz 2), nie auf der öffentlichen Seite. capacity_fade, power_capability und internal_resistance werden als aktuelle Messwerte dieser Batterie (current_*) gespeichert, getrennt von den Originalwerten des Modells.

Parameter	Art	Beschreibung
state_of_health	string	z. B. „97 % nach 412 Zyklen“.
state_of_certified_energy	string	Verbleibende zertifizierte Energie (Batterien für Elektrofahrzeuge).
battery_status	string	original, repurposed, re-used, remanufactured oder waste.
capacity_fade	string	Bisheriger Kapazitätsverlust. Gespeichert als current_capacity_fade.
power_capability	string	Aktuelle Leistungsfähigkeit. Gespeichert als current_power_capability.
internal_resistance	string	Gemessener Innenwiderstand. Gespeichert als current_internal_resistance.
use_data	string	Zyklen, negative Ereignisse, Temperatur und Ladezustand, bis zu 5.000 Zeichen.

Anfrage

curl -X POST https://myproductpassport.eu/api/v1/passports/96/state-of-health \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "state_of_health": "97% at 412 cycles",
    "capacity_fade": "3% from initial rated capacity"
  }'

Antwort

{
  "message": "2 field(s) updated.",
  "updated_fields": ["state_of_health", "current_capacity_fade"],
  "passport": { "id": 96, "status": "published", "compliance_percentage": 100 }
}

POST /passports/{id}/units erfordert passports:write

Jede Batterie benötigt einen eigenen Pass (Verordnung (EU) 2023/1542, Artikel 77 Absatz 1). Registrieren Sie bis zu 10.000 Batterien eines Batteriemodells in einem Aufruf, jede mit eigener Seriennummer (bis zu 20 Buchstaben, Ziffern, Punkte, Bindestriche oder Unterstriche) und optional manufacturing_date, battery_status und ihren Daten nach Anhang XIII Nummer 4. Vorhandene Seriennummern werden aktualisiert; weggelassene Werte bleiben erhalten. Hat das Produkt eine GTIN, ist die Adresse jeder Batterie ihr GS1 Digital Link, /01/{gtin}/21/{serial}. Daten nach Nummer 4 sehen nur vom Inhaber freigegebene Personen.

Parameter	Art		Beschreibung
units[].serial	string	erforderlich	Die Seriennummer der Batterie.
units[].manufacturing_date	string		Monat und Jahr, z. B. "2026-09".
units[].battery_status	string		original oder waste. Ein Statuswechsel erfordert die dabei gemessenen Werte (Anhang XIII Nummer 4 Buchstabe a); waste erfordert außerdem responsible_party_type (producer, pro oder waste_operator), responsible_party_name und responsible_party_contact (Artikel 77 Absatz 7). recycled mit recycled_at und recycler_name beendet den Pass (Artikel 77 Absatz 8). Eine umgenutzte, wiederverwendete oder wiederaufgearbeitete Batterie erhält einen neuen Pass: POST /passports/{id}/units/{serial}/successor.
units[].state_of_health	string		Außerdem state_of_certified_energy, current_capacity_fade, current_power_capability, current_internal_resistance, remaining_capacity_ah, power_fade, internal_resistance_increase, round_trip_efficiency, round_trip_efficiency_fade, expected_lifetime_cycles_remaining, self_discharge_rate, ohmic_resistance und use_data.

Anfrage

curl -X POST https://myproductpassport.eu/api/v1/passports/96/units \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"units": [{"serial": "KES-00001", "manufacturing_date": "2026-09", "state_of_health": "100%"}]}'

Antwort

{ "created": 1, "updated": 0, "skipped": 0, "errors": [] }

PATCH /passports/{id}/units/{serial} erfordert passports:write

Für ein Batteriemanagementsystem, das die Daten einer Batterie übermittelt: beliebige von battery_status, state_of_health, state_of_certified_energy, current_capacity_fade, current_power_capability, current_internal_resistance und use_data. Mit GET auf denselben Pfad lesen Sie sie, mit GET /passports/{id}/units erhalten Sie die Liste (per_page bis 500).

Anfrage

curl -X PATCH https://myproductpassport.eu/api/v1/passports/96/units/KES-00001 \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"state_of_health": "96% at 412 cycles"}'

Antwort

{
  "data": { "serial": "KES-00001", "public_url": "https://myproductpassport.co.uk/01/05012345678900/21/KES-00001", "battery_status": "original", "data": { "state_of_health": "96% at 412 cycles" } }
}

GET /passports/{id}/units/{serial}/snapshots erfordert passports:read

Anhang XIII Nummer 4 Buchstabe a verlangt die Leistungs- und Haltbarkeitswerte beim Inverkehrbringen der Batterie und bei einem Statuswechsel. Diese Messwerte bleiben unverändert erhalten, gleich was später übermittelt wird; senden Sie record_snapshot: true mit einem PATCH, um zusätzlich einen regelmäßigen Messwert zu speichern.

Anfrage

curl https://myproductpassport.eu/api/v1/passports/96/units/KES-00001/snapshots \
  -H "Authorization: Bearer pk_your_key"

Antwort

{
  "data": [
    { "event": "placed_on_market", "status": "original", "values": { "state_of_health": "100%" }, "measured_at": "2026-09-26T09:00:00+00:00", "source": "api" },
    { "event": "status_change", "status": "waste", "values": { "remaining_capacity_ah": "71 Ah", "power_fade": "14%", "internal_resistance_increase": "22%", "expected_lifetime_cycles_remaining": "0" }, "measured_at": "2029-03-02T10:00:00+00:00", "source": "bms" }
  ]
}

POST /passports/{id}/units/{serial}/successor erfordert passports:write

Artikel 77 Absatz 7: Eine Batterie, die zur Wiederverwendung vorbereitet, umgenutzt oder wiederaufgearbeitet wurde, hat einen neuen Pass, der mit ihrem Original verknüpft ist. Damit wird die Batterie mit einer neuen Seriennummer und Kennung unter einem Second-Life-Batteriemodell Ihres Arbeitsbereichs erneut registriert (aus diesem Modell erstellt, falls es noch keines gibt), beide werden verknüpft und die beim Statuswechsel gemessenen Werte gespeichert. Die ursprüngliche Batterie behält ihren Pass. Vervollständigen und veröffentlichen Sie das Second-Life-Modell mit POST /passports/{id}/publish.

Parameter	Art		Beschreibung
stage	string	erforderlich	prepared_for_reuse, repurposed oder remanufactured.
values	object	erforderlich	Die bei der Änderung gemessenen Werte: mindestens je einer der Werte remaining_capacity_ah oder current_capacity_fade, current_power_capability oder power_fade sowie current_internal_resistance oder internal_resistance_increase, außerdem expected_lifetime_cycles_remaining (Anhang IV Teil A).
serial	string		Die neue Seriennummer. Standard: die ursprüngliche Seriennummer mit dem Zusatz -RU, -RP oder -RM.
measured_at	string		Zeitpunkt der Messung.
member_state	string		Zweibuchstabiger Code des Mitgliedstaats, in dem der Gesundheitszustand geprüft wurde (Artikel 73 Absatz 1 Buchstabe a).
target_passport_id	integer		Ein bestehendes Second-Life-Modell dieses Batteriemodells, unter dem sie registriert werden soll.

Anfrage

curl -X POST https://myproductpassport.eu/api/v1/passports/96/units/KES-00001/successor \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"stage": "repurposed", "values": {"remaining_capacity_ah": "82 Ah", "power_fade": "9%", "internal_resistance_increase": "15%", "expected_lifetime_cycles_remaining": "2000"}}'

Antwort

{
  "data": {
    "serial": "KES-00001-RP", "battery_status": "repurposed", "passport_id": 131,
    "lineage": { "originals": [{ "serial": "KES-00001", "passport_id": 96, "stage": "repurposed" }], "successors": [] }
  }
}

POST /passports/{id}/registry erfordert passports:write

Speichert die Einreichung beim EU-DPP-Register und das Ergebnis an einem Pass: Status, Korrelations-ID, die vom Register zurückgegebene Registrierungskennung und optional einen Link zu einer Sicherungskopie bei einem DPP-Dienstleister. Die Registrierung selbst erfolgt im Register der Kommission (Webformular oder Datei-Upload); hier wird das Ergebnis beim Pass festgehalten. GET /passports/{id} gibt denselben Block unter registry zurück.

Parameter	Art	Beschreibung
status	string	not_submitted, submitted, registered oder failed.
product_group	string	Produktgruppe im Register, zum Beispiel batteries.
granularity	string	Modell, Charge oder Artikel.
upi	string	Eindeutige Produktkennung als https-URL. Standard ist die URL des öffentlichen Passes.
correlation_id	string	Korrelations-ID, die das Register bei der Einreichung vergibt.
uri	string	Vom Register zurückgegebene Registrierungskennung.
backup_url	string	https-Link zur Sicherungskopie, die von einem DPP-Dienstleister gehostet wird.
submitted_at	date	Einreichungsdatum.
registered_at	date	Registrierungsdatum.
error	string	Fehlerbeschreibung für eine fehlgeschlagene Einreichung.

Anfrage

curl -X POST https://myproductpassport.eu/api/v1/passports/96/registry \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "registered",
    "correlation_id": "7f3a2c1e-0b4d-4f8e-9a6b-2d1c3e4f5a6b",
    "uri": "urn:eu:dpp:reg:00000001",
    "registered_at": "2027-02-18"
  }'

Antwort

{
  "message": "Registry details updated.",
  "passport": {
    "id": 96,
    "registry": {
      "status": "registered",
      "upi": "https://myproductpassport.co.uk/p/552fbb4e-5d9a-41da-9050-cc9005d8b66b",
      "correlation_id": "7f3a2c1e-0b4d-4f8e-9a6b-2d1c3e4f5a6b",
      "uri": "urn:eu:dpp:reg:00000001",
      "registered_at": "2027-02-18T00:00:00+00:00"
    }
  }
}

GET /passports/{id}/qr erfordert passports:read

Der QR-Code des Passes als Datei: svg (Standard), png (gebrandet, druckfertig) oder pdf (Etikettenbogen).

Parameter	Art		Beschreibung
format	string		svg \| png \| pdf

Anfrage

curl "https://myproductpassport.eu/api/v1/passports/96/qr?format=png" \
  -H "Authorization: Bearer pk_your_key" -o passport-96.png

09 / EndpunkteKonformität

GET /passports/{passportId}/compliance erfordert passports:read

Führt eine Live-Compliance-Prüfung eines Passes anhand der Pflichtfelder seines Sektors durch und meldet genau, was fehlt.

Anfrage

curl https://myproductpassport.eu/api/v1/passports/96/compliance \
  -H "Authorization: Bearer pk_your_key"

Antwort

{
  "data": {
    "passport_id": 96,
    "product_name": "Alpine Merino Crew Sweater",
    "status": "compliant",
    "percentage": 100,
    "completed_fields": 12,
    "total_fields": 12,
    "missing_fields": []
  }
}

10 / EndpunkteSektoren

GET /sectors

Die Sektoren, denen ein Produkt zugeordnet werden kann: die Systemsektoren der Plattform sowie alle von Ihrem Arbeitsbereich definierten. Verwenden Sie die ID beim Anlegen von Produkten und die Feldschlüssel beim Schreiben von Passfeldern.

Anfrage

curl https://myproductpassport.eu/api/v1/sectors \
  -H "Authorization: Bearer pk_your_key"

Antwort

{
  "data": [
    {
      "id": 4,
      "slug": "batteries",
      "name": "Batteries",
      "system": true,
      "regulations_finalised": true,
      "deadline": "2027-02-18",
      "deadline_label": "18 Feb 2027",
      "required_fields": ["battery_category", "battery_weight", "..."],
      "optional_fields": ["energy_round_trip_efficiency", "..."]
    }
  ]
}

11 / EndpunkteDokumente

GET /products/{productId}/documents erfordert products:read

Dem Produkt beigefügte Konformitätserklärungen, Prüfberichte und Zertifikate. Ein öffentliches Dokument wird in jedem veröffentlichten Pass des Produkts verlinkt.

Anfrage

curl https://myproductpassport.eu/api/v1/products/512/documents \
  -H "Authorization: Bearer pk_your_key"

Antwort

{
  "data": [
    {
      "id": 31,
      "product_id": 512,
      "filename": "declaration-of-conformity.pdf",
      "mime_type": "application/pdf",
      "file_size": 184322,
      "is_public": true,
      "processing_status": "completed",
      "public_url": "https://myproductpassport.co.uk/p/3f0c.../document/31",
      "created_at": "2026-09-22T10:12:00+00:00"
    }
  ]
}

POST /products/{productId}/documents erfordert products:write

Multipart-Upload. PDF, Word, Excel, CSV, Text, PNG und JPEG bis 10 MB, höchstens 20 pro Produkt. Der Text wird im Hintergrund extrahiert.

Parameter	Art		Beschreibung
file	file	erforderlich	Das Dokument.
is_public	boolean		Im öffentlichen Pass anzeigen (Standard false).

Anfrage

curl -X POST https://myproductpassport.eu/api/v1/products/512/documents \
  -H "Authorization: Bearer pk_your_key" \
  -F "[email protected]" \
  -F "is_public=1"

PATCH /products/{productId}/documents/{id} erfordert products:write

Legt fest, ob das Dokument im öffentlichen Pass verlinkt ist.

Parameter	Art		Beschreibung
is_public	boolean	erforderlich

Anfrage

curl -X PATCH https://myproductpassport.eu/api/v1/products/512/documents/31 \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"is_public": false}'

DELETE /products/{productId}/documents/{id} erfordert products:write

Entfernt die Datei und ihre Verknüpfung mit dem Pass.

Anfrage

curl -X DELETE https://myproductpassport.eu/api/v1/products/512/documents/31 \
  -H "Authorization: Bearer pk_your_key"

Antwort

{ "message": "Document deleted." }

12 / EndpunkteLieferkette

GET /products/{productId}/supply-chain erfordert products:read

Die im Produktpass angezeigten Schritte, in Reihenfolge.

Anfrage

curl https://myproductpassport.eu/api/v1/products/512/supply-chain \
  -H "Authorization: Bearer pk_your_key"

PUT /products/{productId}/supply-chain erfordert products:write

Ersetzt alle Schritte durch die gesendete Liste, in der gesendeten Reihenfolge. Senden Sie eine leere Liste, um sie zu leeren. Schritttypen: raw_material, processing, manufacturing, assembly, packaging, distribution.

Parameter	Art		Beschreibung
steps	array	erforderlich	Bis zu 50 Schritte.
steps[].step_type	string	erforderlich
steps[].supplier_name	string	erforderlich
steps[].supplier_location	string
steps[].supplier_country	string		ISO 3166-1 Alpha-2.
steps[].lat / lng	number
steps[].description	string
steps[].certifications	array
steps[].date	date

Anfrage

curl -X PUT https://myproductpassport.eu/api/v1/products/512/supply-chain \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"steps": [{"step_type": "raw_material", "supplier_name": "Merino Growers Co-op", "supplier_country": "NZ", "certifications": ["RWS"]}, {"step_type": "manufacturing", "supplier_name": "Northloom Mill", "supplier_location": "Biella", "supplier_country": "IT"}]}'

13 / EndpunkteÜbersetzungen

GET /passports/{id}/translations erfordert passports:read

Jeder übersetzte Feldwert nach Sprache, mit Herkunft: auto (maschinell, bei Veröffentlichung erstellt) oder manuell.

Anfrage

curl https://myproductpassport.eu/api/v1/passports/96/translations \
  -H "Authorization: Bearer pk_your_key"

Antwort

{
  "data": {
    "passport_id": 96,
    "available_locales": ["bg", "cs", "da", "de", "..."],
    "translations": {
      "de": {"care_instructions": {"value": "Kalt waschen", "source": "manual"}}
    }
  }
}

PUT /passports/{id}/translations/{locale} erfordert passports:write

Legt Übersetzungen für eine Sprache fest, nach Feldschlüssel. Eine manuelle Übersetzung wird nie maschinell überschrieben. Senden Sie eine leere Zeichenkette, um eine zu entfernen.

Parameter	Art		Beschreibung
fields	object	erforderlich	field_key: übersetzter Wert

Anfrage

curl -X PUT https://myproductpassport.eu/api/v1/passports/96/translations/de \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"fields": {"care_instructions": "Kalt waschen, nicht bleichen"}}'

Antwort

{ "message": "1 translation(s) written, 0 removed.", "locale": "de", "written": 1, "removed": 0 }

14 / EndpunkteIntegrität und Exporte

GET /passports/{id}/integrity erfordert passports:read

Jeder veröffentlichte Stand des Passes als hashverketteter, mit Ed25519 signierter Eintrag: Fingerabdruck (SHA-256), Kettenwert und Signatur. Die öffentlichen Schlüssel liegen unter /.well-known/mpp-integrity-keys.json, sodass jeder die Kette prüfen kann.

Anfrage

curl https://myproductpassport.eu/api/v1/passports/96/integrity \
  -H "Authorization: Bearer pk_your_key"

Antwort

{ "data": { "state": "intact", "hash_algorithm": "SHA-256", "signature_algorithm": "Ed25519", "records": [ { "sequence": 1, "event": "published", "content_hash": "8f3a...", "chain_hash": "c21e...", "signature": "MEUC...", "key_id": "3fa9c21e0b7d4a11" } ], "problems": [] } }

GET /passports/{id}/integrity/{sequence} erfordert passports:read

Der vollständige Eintrag, wie er signiert wurde, einschließlich Snapshot: was der Pass zu diesem Zeitpunkt enthielt, bis hin zu einem Hash jeder angehängten Datei.

Anfrage

curl https://myproductpassport.eu/api/v1/passports/96/integrity/1 \
  -H "Authorization: Bearer pk_your_key"

GET /passports/{id}/epcis erfordert passports:read

Der Pass als GS1 EPCIS 2.0 JSON-LD-Dokument: das in Betrieb genommene Produkt, jeder Schritt der Lieferkette als Beobachtung, einzelne Batterien und ein Second-Life-Pass als Transformation. Kennungen sind GS1 Digital Link URIs, wenn das Produkt eine GTIN hat.

Anfrage

curl https://myproductpassport.eu/api/v1/passports/96/epcis \
  -H "Authorization: Bearer pk_your_key"

15 / EndpunkteLieferantenanfragen

POST /passports/{id}/supplier-requests erfordert passports:write

Sendet einem Lieferanten per E-Mail einen privaten Link, über den er die von Ihnen gewählten Felder in seiner Sprache ausfüllt. Nichts gelangt in den Pass, bevor jemand in Ihrem Arbeitsbereich es freigibt.

Parameter	Art		Beschreibung
supplier_name	string	erforderlich
supplier_email	string	erforderlich
field_keys	array	erforderlich	Feldschlüssel aus der Vorlage des Passes.
locale	string		Sprache der E-Mail und des Formulars, z. B. de.
due_at	date		Antwortfrist; 14 Tage, wenn nicht angegeben.
message	string

Anfrage

curl -X POST https://myproductpassport.eu/api/v1/passports/96/supplier-requests \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"supplier_name": "Mei Chen", "supplier_email": "[email protected]", "field_keys": ["recycled_content_cobalt", "carbon_footprint"], "locale": "de"}'

GET /passports/{id}/supplier-requests erfordert passports:read

Jede Anfrage für den Pass mit ihrem Status.

Anfrage

curl https://myproductpassport.eu/api/v1/passports/96/supplier-requests \
  -H "Authorization: Bearer pk_your_key"

GET /supplier-requests/{id} erfordert passports:read

Eine Anfrage mit den Antworten des Lieferanten, seiner Notiz und den Namen der angehängten Dateien.

Anfrage

curl https://myproductpassport.eu/api/v1/supplier-requests/12 \
  -H "Authorization: Bearer pk_your_key"

16 / EndpunkteAfter-Sales

POST /passports/{id}/items erfordert items:write

Geben Sie Artikeln eines Produkts (jede Branche außer Batterien, die /units verwenden) eine eigene Seriennummer: Jeder erhält eine eigene Adresse und einen QR-Code, einen verborgenen Echtheitscode für sein Etikett und kann von seinem Eigentümer registriert werden. Senden Sie bis zu 10.000 Artikel oder einen Bereich. Mit einer GTIN ist die Adresse der GS1 Digital Link /01/{gtin}/21/{serial}.

Parameter	Art		Beschreibung
items[].serial	string	erforderlich	Bis zu 20 Buchstaben, Ziffern, Punkte, Bindestriche oder Unterstriche.
items[].batch	string		Charge oder Los, bis zu 20 Zeichen.
items[].manufactured_on	string		Herstellungsdatum, JJJJ-MM-TT.
range	object		Statt items: prefix, start, count, digits und batch, zum Beispiel SN-00001 bis SN-00500.

Anfrage

curl -X POST https://myproductpassport.eu/api/v1/passports/96/items \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"range": {"prefix": "SN-", "start": 1, "count": 500, "digits": 5, "batch": "B2026-10"}}'

Antwort

{ "created": 500, "updated": 0, "skipped": 0, "over_limit": 0, "errors": [] }

GET /passports/{id}/items/{serial} erfordert items:read

Ein Artikel mit Adresse, Status, ob er registriert ist und bis wann seine Garantie läuft, seinen Echtheitsprüfungen und seinem Verlauf. Ein Schlüssel mit items:write erhält auch den verborgenen Code zum Drucken. GET /passports/{id}/items listet sie auf (Filter status und batch, per_page bis 500).

Anfrage

curl https://myproductpassport.eu/api/v1/passports/96/items/SN-00001 \
  -H "Authorization: Bearer pk_your_key"

Antwort

{
  "data": { "serial": "SN-00001", "status": "active", "url": "https://myproductpassport.co.uk/01/05012345678900/21/SN-00001", "registered": true, "warranty_ends_on": "2028-10-02", "events": [ { "type": "registered", "country": "IE", "at": "2026-10-03T09:12:00+00:00" } ] }
}

PATCH /passports/{id}/items/{serial} erfordert items:write

Setzen Sie status auf stolen oder recalled, dann warnt seine Seite alle, die ihn scannen, mit Ihrer status_note; ein gestohlener Artikel kann nicht registriert werden. retired nimmt seine Seite offline. Auch batch und manufactured_on können geändert werden.

Parameter	Art		Beschreibung
status	string		active, stolen, recalled oder retired.
status_note	string		Wird auf der Seite des Artikels angezeigt, bis zu 500 Zeichen.

Anfrage

curl -X PATCH https://myproductpassport.eu/api/v1/passports/96/items/SN-00001 \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "stolen", "status_note": "Reported stolen on 2 October 2026."}'

GET /owner-registrations erfordert aftersales:read

Personen, die Ihre Produkte registriert haben: Name, E-Mail, Land, Kaufdatum, Händler, Garantiedaten und ob sie Neuigkeiten und Angeboten zugestimmt haben (marketing_consent=1 listet nur diese). Standardmäßig aktive Registrierungen; status=pending, transferred oder ended für andere; since= für Änderungen nach einem Datum.

Anfrage

curl "https://myproductpassport.eu/api/v1/owner-registrations?marketing_consent=1&since=2026-10-01" \
  -H "Authorization: Bearer pk_your_key"

GET /service-requests erfordert aftersales:read

Reparaturen, Garantieansprüche, Rücknahmen, Ersatzteile und Fragen aus Ihren Pässen, die neuesten zuerst, mit Filtern für status und type. GET /service-requests/{reference} fügt die Unterhaltung hinzu.

Anfrage

curl "https://myproductpassport.eu/api/v1/service-requests?status=new" \
  -H "Authorization: Bearer pk_your_key"

POST /service-requests/{reference}/replies erfordert aftersales:write

Ihre Antwort wird dem Kunden mit einem Link zu seiner Anfrageseite in seiner Sprache per E-Mail gesendet. internal: true fügt eine Notiz hinzu, die nur Ihr Team sieht. PATCH /service-requests/{reference} mit einem status bringt sie voran (der Kunde wird informiert, wenn sie in Bearbeitung, gelöst oder geschlossen ist).

Parameter	Art		Beschreibung
body	string	erforderlich	Die Antwort, bis zu 5.000 Zeichen.
internal	boolean		Eine Notiz für Ihr Team statt einer Antwort.
status	string		new, in_progress, waiting, resolved oder closed.

Anfrage

curl -X POST https://myproductpassport.eu/api/v1/service-requests/SR-7K3F9Q/replies \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"body": "A new lid is on its way today.", "status": "waiting"}'

17 / EndpunkteMassenbearbeitung und Bilder

PATCH /products/bulk-fields erfordert products:write

Setzt ein Produktdetail oder ein Passfeld für bis zu 5.000 Produkte. mode ist set, fill (nur wo leer) oder clear. Bis zu 100 Produkte werden direkt in der Anfrage aktualisiert; größere Mengen werden in die Warteschlange gestellt (202).

Parameter	Art		Beschreibung
product_ids	array	erforderlich
target	string	erforderlich	product \| field
key	string	erforderlich
value	string
mode	string		set \| fill \| clear

Anfrage

curl -X PATCH https://myproductpassport.eu/api/v1/products/bulk-fields \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"product_ids": [12, 13, 14], "target": "field", "key": "warranty_period", "value": "10 years", "mode": "fill"}'

Antwort

{ "data": { "changed": 2, "skipped": 1, "errors": [] } }

POST /products/{id}/images erfordert products:write

Multipart-Upload einer JPG-, PNG- oder WebP-Datei (bis zu 15MB, 8 pro Produkt). Das erste Bild ist das Titelbild im öffentlichen Pass.

Parameter	Art		Beschreibung
image	file	erforderlich
alt	string		Beschreibung des Bildes.

Anfrage

curl -X POST https://myproductpassport.eu/api/v1/products/12/images \
  -H "Authorization: Bearer pk_your_key" \
  -F [email protected] -F alt="Front of the battery"

PUT /products/{id}/images/order erfordert products:write

Übergeben Sie image_ids in der gewünschten Reihenfolge; das erste Bild wird zum Titelbild.

Parameter	Art		Beschreibung
image_ids	array	erforderlich

Anfrage

curl -X PUT https://myproductpassport.eu/api/v1/products/12/images/order \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"image_ids": [31, 30]}'

DELETE /products/{id}/images/{imageId} erfordert products:write

Entfernt das Bild und seine Datei.

Anfrage

curl -X DELETE https://myproductpassport.eu/api/v1/products/12/images/31 \
  -H "Authorization: Bearer pk_your_key"

18 / EndpunkteWebhooks

GET /webhooks erfordert webhooks:manage

Die für Ihren Arbeitsbereich registrierten Endpunkte. Geheimnisse sind hier nicht enthalten; rufen Sie einen einzelnen Endpunkt ab, um sein Geheimnis zu sehen.

Anfrage

curl https://myproductpassport.eu/api/v1/webhooks \
  -H "Authorization: Bearer pk_your_key"

POST /webhooks erfordert webhooks:manage

Registriert eine öffentliche HTTPS-URL für ein oder mehrere Ereignisse. Die Antwort enthält das Signaturgeheimnis. Private oder interne Hosts werden abgelehnt.

Parameter	Art		Beschreibung
url	string	erforderlich
events	array	erforderlich	Eines der unten aufgeführten Ereignisse.

Anfrage

curl -X POST https://myproductpassport.eu/api/v1/webhooks \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://erp.acme.example/mpp", "events": ["passport.published", "product.updated"]}'

Antwort

{
  "data": {
    "id": 3,
    "url": "https://erp.acme.example/mpp",
    "events": ["passport.published", "product.updated"],
    "is_active": true,
    "failure_count": 0,
    "secret": "9f1c...64 hex characters...",
    "created_at": "2026-09-22T10:12:00+00:00"
  }
}

GET /webhooks/{id} erfordert webhooks:manage

Anfrage

curl https://myproductpassport.eu/api/v1/webhooks/3 \
  -H "Authorization: Bearer pk_your_key"

PUT /webhooks/{id} erfordert webhooks:manage

Ändern Sie URL oder Ereignisse oder pausieren und reaktivieren Sie ihn. Die Reaktivierung setzt den Fehlerzähler zurück; ein Endpunkt wird nach 10 aufeinanderfolgenden fehlgeschlagenen Zustellungen automatisch pausiert.

Parameter	Art		Beschreibung
url	string
events	array
is_active	boolean

Anfrage

curl -X PUT https://myproductpassport.eu/api/v1/webhooks/3 \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"is_active": true}'

POST /webhooks/{id}/test erfordert webhooks:manage

Stellt eine webhook.test-Zustellung in die Warteschlange, damit Sie Ihren Empfänger und Ihren Signaturcode prüfen können.

Anfrage

curl -X POST https://myproductpassport.eu/api/v1/webhooks/3/test \
  -H "Authorization: Bearer pk_your_key"

Antwort

{ "message": "Test delivery queued." }

GET /webhooks/{id}/deliveries erfordert webhooks:manage

Letzte Zustellungen, neueste zuerst, mit dem HTTP-Status, den Ihr Endpunkt zurückgegeben hat, und den ersten 500 Zeichen der Antwort.

Parameter	Art		Beschreibung
per_page	integer		Bis zu 100.

Anfrage

curl https://myproductpassport.eu/api/v1/webhooks/3/deliveries \
  -H "Authorization: Bearer pk_your_key"

DELETE /webhooks/{id} erfordert webhooks:manage

Anfrage

curl -X DELETE https://myproductpassport.eu/api/v1/webhooks/3 \
  -H "Authorization: Bearer pk_your_key"

Antwort

{ "message": "Webhook endpoint deleted." }

19 / EreignisseWebhooks

Statt regelmäßig abzufragen, registrieren Sie in der App einen Webhook-Endpunkt (Seite Webhooks, ab dem Starter-Tarif verfügbar), und MyProductPassport sendet bei jedem Ereignis JSON per POST an Ihre URL:

Ereignis	Ausgelöst, wenn
product.created	Ein Produkt wird angelegt (App, API oder CSV-Import)
product.updated	Ein Produkt wird aktualisiert
product.deleted	Ein Produkt wird gelöscht
passport.created	Ein Pass wird erstellt
passport.published	Ein Pass geht live
passport.archived	Ein Pass wird archiviert
supplier_request.submitted	Ein Lieferant sendet die angeforderten Informationen
owner.registered	Ein Eigentümer bestätigt seine Registrierung
owner.transferred	Ein Artikel geht an einen neuen registrierten Eigentümer über
service_request.created	Ein Kunde sendet über einen Pass eine Serviceanfrage
service_request.updated	Eine Serviceanfrage erhält eine Antwort oder einen neuen Status
item.status_changed	Ein Artikel wird als gestohlen, zurückgerufen oder außer Betrieb markiert oder freigegeben
item.verification_failed	Ein sicherer NFC-Scan schlägt fehl, falsche Codes häufen sich oder eine Seriennummer taucht an zu vielen Orten auf
webhook.test	Sie senden eine Testzustellung aus der App

Jede Zustellung ist ein JSON-Umschlag: eine Zustellungs-ID (bei Wiederholungen wird dieselbe ID gesendet, damit Sie Duplikate erkennen können), das Ereignis, die Versuchsnummer, ein Zeitstempel und die Ereignisdaten. Pass-Ereignisse enthalten die UUID und die öffentliche URL des Passes, sodass Sie selten eine zweite Anfrage benötigen:

Inhalt der Zustellung

{
  "id": 8123,
  "event": "passport.published",
  "attempt": 1,
  "created_at": "2026-09-22T10:12:00+00:00",
  "data": {
    "passport_id": 96,
    "uuid": "3f0c8f1e-...",
    "version": 2,
    "status": "published",
    "public_url": "https://myproductpassport.co.uk/p/3f0c8f1e-...",
    "product_id": 512,
    "product": {"id": 512, "name": "Alpine Merino Crew Sweater", "sku": "NL-AMC-001", "gtin": "5012345678900"}
  }
}

Die Header enthalten den Ereignisnamen, die Zustellungs-ID, einen Unix-Zeitstempel und eine HMAC-Signatur des Rohinhalts, damit Sie prüfen können, dass die Nachricht von uns stammt, und Wiederholungen abweisen können:

Header der Zustellung

Content-Type: application/json
User-Agent: MyProductPassport-Webhooks/1.0
X-MPP-Event: passport.published
X-MPP-Delivery: 8123
X-MPP-Timestamp: 1790084320
X-MPP-Signature: sha256=<hex hmac of the raw body, keyed with your endpoint secret>

Antworten Sie innerhalb von 10 Sekunden mit einem beliebigen 2xx-Status. Alles andere wird fünfmal innerhalb von etwa 90 Minuten erneut versucht (30 s, 1 min, 5 min, 15 min, 1 h); nach 10 aufeinanderfolgenden Fehlschlägen wird der Endpunkt pausiert, bis Sie ihn wieder aktivieren.

Prüfen (PHP)

$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $endpointSecret);
abort_unless(hash_equals($expected, $request->header('X-MPP-Signature')), 401);

Cookie	Zweck	Ablauf
myproductpassport-session	Hält Sie angemeldet und die Website sicher	2 Stunden
XSRF-TOKEN	Schützt Formulare vor Cross-Site-Request-Forgery	2 Stunden
cookie_consent	Speichert Ihre Cookie-Auswahl	12 Monate
locale_suggested countdown_dismissed exit_intent_dismissed	Merkt sich, dass Sie eine Meldung geschlossen haben, damit sie nicht erneut erscheint	Bis zu 30 Tage

Cookie	Zweck	Ablauf
_ga, _ga_*	Google Analytics: zählt Besuche und zeigt, wie die Website genutzt wird	2 Jahre
_gcl_au	Google Ads: misst, welche Anzeigen zu Registrierungen führen	90 Tage
mpp_ref	Merkt sich den Partner, dessen Link Sie gefolgt sind, damit er bei einer späteren Registrierung angerechnet wird	90 Tage

API-Referenz

01 / Erste SchritteAuthentifizierung

02 / Erste SchritteRatenlimits

03 / Erste SchritteFehler

04 / Erste SchrittePaginierung

05 / Erste SchritteKI-Assistent-Connector (MCP)

06 / EndpunkteKonto

07 / EndpunkteProdukte

08 / EndpunktePässe

09 / EndpunkteKonformität

10 / EndpunkteSektoren

11 / EndpunkteDokumente

12 / EndpunkteLieferkette

13 / EndpunkteÜbersetzungen

14 / EndpunkteIntegrität und Exporte

15 / EndpunkteLieferantenanfragen

16 / EndpunkteAfter-Sales

17 / EndpunkteMassenbearbeitung und Bilder

18 / EndpunkteWebhooks

19 / EreignisseWebhooks

Bevor Sie gehen…

Sie stehen auf der Liste!