Fejlesztők / REST API

API-referencia

A MyProductPassport minden funkciója elérhető kulccsal hitelesített REST API-n keresztül: hozzon létre termékeket, generáljon és tegyen közzé digitális termékútleveleket, küldjön élő akkumulátoradatokat és ellenőrizze a megfelelőséget közvetlenül ERP-, PIM- vagy build-folyamatából.

v1 https://myproductpassport.eu/api/v1 Kezdje ingyen OpenAPI-specifikáció ↓

01 / Első lépésekHitelesítés

Minden kérést Bearer tokenként átadott API-kulccsal hitelesítünk. A kulcsokat az alkalmazás API-kulcsok menüpontjában lehet létrehozni, egyszer jelennek meg, és hash-elve tároljuk őket; minden kulcsnak saját jogosultságkészlete, opcionális IP-engedélyezési listája és opcionális lejárati dátuma van. A kulcsok leállás nélkül cserélhetők.

Kérés fejléce

Authorization: Bearer pk_your_api_key

Minden csomagban. API-kulcsokat minden csomagban lehet létrehozni és használni, az ingyenesben is. A csomag azt szabja meg, hány kérést küldhet egy kulcs percenként (lent), és hány terméket és útlevelet tarthat a munkaterület.

Tesztmód. A tesztkulcs (pk_test_...) minden hívást pontosan úgy futtat, ahogyan egy éles kulcs, ugyanazzal az ellenőrzéssel, azonosítókkal és válaszokkal, majd visszavonja azt: semmi sem kerül mentésre, nem megy ki e-mail vagy webhook, és nem marad meg fájl. A válaszok tartalmazzák a "test_mode": true értéket és egy X-MPP-Mode: test fejlécet. Építse fel és tesztelje integrációját valós adatain, majd cserélje le a kulcsot éles kulcsra.

A jogosultságokat kulcsonként adjuk meg, így egy integráció csak azt kapja meg, amire szüksége van:

Jogosultság	Engedélyek
products:read	Termékek olvasása
products:write	Termékek létrehozása, frissítése és törlése
passports:read	Útlevelek olvasása
passports:write	Útlevelek generálása
passports:publish	Útlevelek közzététele és archiválása
webhooks:manage	Webhook-végpontok létrehozása, tesztelése és eltávolítása
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 / Első lépésekKérésszám-korlátok

A korlátok kulcsonként, percenként érvényesek, és a csomag határozza meg őket:

Csomag	Kérés / perc
Ingyenes	30
Micro	60
E-címke	60
Starter	120
Professional	300
Business	600
Battery	600

Minden válasz tartalmazza az X-RateLimit-Limit és X-RateLimit-Remaining fejlécet. A korlát túllépésekor 429 a válasz:

429 Too Many Requests

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

03 / Első lépésekHibák

A hibák JSON formátumúak, szokásos állapotkóddal. A leggyakoribbak:

Állapot	Jelentés	Példa törzs
401	Hiányzó, érvénytelen, visszavont vagy lejárt kulcs	`{"error": "Invalid or revoked API key."}`
403	A kulcsnak hiányzik egy jogosultsága, az IP-cím nincs az engedélyezettek között, vagy elfogyott a csomag kerete	`{"message": "API key does not have 'products:write' permission."}`
404	Az erőforrás nem létezik a munkaterületén	`{"message": "Not found."}`
422	Az érvényesítés sikertelen	`{"message": "…", "errors": {"gtin": ["…"]}}`
429	Kérésszám-korlát túllépve	`{"error": "Rate limit exceeded."}`

04 / Első lépésekLapozás

A listavégpontok oldalanként 25 elemet adnak vissza a szabványos links és meta objektumokkal. Adja meg a ?page=2 paramétert a gyűjteményben való lapozáshoz.

05 / Első lépésekMI-asszisztens csatoló (MCP)

Csatlakoztassa a Claude-ot, a Cursort vagy bármely asszisztenst, amely ismeri a Model Context Protocolt, és kérje meg egyszerű szavakkal, hogy hozzon létre termékeket, töltse ki az útleveleket azzal, amit elmond neki, és ellenőrizze, mi hiányzik még. Egy API-kulcsot használ annak jogosultságaival és kéréskorlátjával. Létrehozhat piszkozatokat és kitölthet mezőket; soha nem tesz közzé, nem archivál és nem töröl semmit: ez Önnél marad az alkalmazásban.

Szervercím (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 és más kliensek, amelyek helyi szervert indítanak

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

Az elérhető eszközök:

Eszköz	Mit csinál
list_products	A munkaterület termékei, a legújabbakkal kezdve, oldalanként 25, ágazattal és a legújabb útlevéllel.
get_product	Egy termék adataival, ágazatával, szabályozási szakaszaival és legújabb útlevelével.
list_sectors	Az ágazati sablonok, amelyeket egy termék használhat (textil, elektronika, akkumulátorok, bor és más), az azonosítóikkal. A termék ágazata dönti el, mely útlevélmezők kötelezők.
create_product	Terméket ad a munkaterülethez. Használjon sector_id-t a list_sectors eredményéből. A compliance_sections szabályozási szakaszokat ad az útlevélhez: gpsr, epr, france, chemicals, eudr.
list_passports	A munkaterület útlevelei, a legújabbakkal kezdve, oldalanként 25, állapottal (draft, published, archived), teljességi százalékkal és nyilvános címmel.
get_passport	Egy útlevél: állapot, verzió, teljességi százalék, nyilvános cím és QR-kód-hivatkozások.
create_passport	Útlevélpiszkozatot hoz létre egy termékhez. Nem teszi közzé: azt egy személy teszi meg az alkalmazásban.
get_passport_fields	Mit kér egy útlevél: a kötelező és választható mezők kulcsai, mindegyik jelentése (címke, leírás, példa), a meglévő értékek és a hiányzó kötelező mezők.
update_passport_fields	Mezőértékeket ír egy piszkozat vagy közzétett útlevélbe (a közzétett helyben frissül: ugyanaz a cím, ugyanaz a QR-kód). Kulcsok a get_passport_fields eredményéből; az üres szöveg törli az értéket. Csak olyan tényt írjon, amelyet a felhasználó vagy a dokumentumai közölnek.
get_compliance	Egy útlevél teljessége: százalék, állapot és a még hiányzó kötelező mezők.

Próbálja ki tesztkulccsal. Tesztkulccsal (pk_test_...) az asszisztens módosításait ellenőrizzük, majd visszavonjuk, így láthatja, mit tenne, mielőtt éles kulcsot adna neki.

06 / VégpontokFiók

GET /me

Visszaadja a hitelesített fiókot, annak előfizetési szintjét és a termékkeret felhasznált részét. Kapcsolatellenőrzésre hasznos.

Kérés

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

Válasz

{
  "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 / VégpontokTermékek

GET /products szükséges hozzá: products:read

Listázza munkaterülete termékeit, a legújabbal kezdve, oldalanként 25-öt. Minden termék tartalmazza szektorát és legutóbbi útlevelének összefoglalóját.

Paraméter	Típus		Leírás
page	integer		Oldalszám.

Kérés

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

Válasz

{
  "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 szükséges hozzá: products:write

Egy terméket hoz létre. 403-at ad vissza, ha a csomag termékkerete elfogyott.

Paraméter	Típus		Leírás
name	string	kötelező	Termék neve, legfeljebb 255 karakter.
sku	string		Belső SKU-ja, legfeljebb 100 karakter.
gtin	string		GTIN-8, 12, 13 vagy 14 (csak számjegyek).
brand	string		A nyilvános útlevélen megjelenő márka.
description	string		Legfeljebb 2000 karakter.
category	string		Szabad szöveges kategória. Alapértelmezés: "general".
sector_id	integer		Szektorazonosító, amely kiválasztja az útlevél mezősablonját.
country_of_origin	string		Országkód, pl. "PT".
weight	number		Nettó tömeg.
weight_unit	string		A kg, g, lb, oz egyike. Alapértelmezés: kg.
materials	array		{name, percentage 0-100} objektumok.
has_packaging	boolean		Hozzáadja az útlevélhez a csomagolási sablon mezőit (pkg_ kezdetű kulcsok), ugyanazon QR-kód alatt.

Kérés

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}
    ]
  }'

Válasz

{
  "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 szükséges hozzá: products:write

Egy hívással legfeljebb 100 terméket hoz létre. A teljes köteget 403-mal elutasítja, ha az túllépné a fennmaradó termékkeretét. Több ezer termékes katalógusoknál hívja ezt a végpontot ciklusban, vagy használja az alkalmazás CSV-importját.

Paraméter	Típus		Leírás
products	array	kötelező	1–100 termékobjektum ugyanazokkal a mezőkkel, mint a „Termék létrehozása” (anyagok nélkül).

Kérés

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}
    ]
  }'

Válasz

{
  "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} szükséges hozzá: products:read

Egy terméket ad vissza a szektorával és a legutóbbi útlevél összefoglalójával. 404, ha az azonosító nincs a munkaterületén.

Kérés

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

PUT /products/{id} szükséges hozzá: products:write

Részben frissít egy terméket. Csak a módosítandó mezőket küldje el; a mezők listája megegyezik a Termék létrehozása esetén használtakkal.

Kérés

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} szükséges hozzá: products:write

Visszaállíthatóan törli a terméket. A termék közzétett útlevelei továbbra is működnek, így a nyomtatott QR-kódok soha nem maradnak oldal nélkül.

Kérés

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

Válasz

{ "message": "Product deleted." }

08 / VégpontokÚtlevelek

GET /passports szükséges hozzá: passports:read

Listázza az útleveleket, a legújabbal kezdve, oldalanként 25-öt, termékösszefoglalóval és az összes útlevélmezővel.

Paraméter	Típus		Leírás
page	integer		Oldalszám.

Kérés

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

Válasz

{
  "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 szükséges hozzá: passports:write

Útlevélpiszkozatot generál egy termékhez, a mezőket a termékadatokból és a szektorsablonból előre kitöltve. A piszkozatot a megfelelőségi pontszámával adja vissza. Ha a terméknek már van élő útlevele, 409-et ad vissza azzal az útlevéllel: javítsa a PUT /passports/{id}/fields kéréssel, amely megőrzi a címét és a QR-kódját.

Kérés

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

GET /passports/{id} szükséges hozzá: passports:read

Egy útlevelet ad vissza termékkel, mezőkkel, nyilvános URL-lel és GS1 Digital Linkkel.

Kérés

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

POST /passports/{id}/publish szükséges hozzá: passports:publish

Közzétesz egy útlevélpiszkozatot, élesítve annak nyilvános oldalát és QR-kódját. Csak piszkozatok tehetők közzé; minden más 404-et ad vissza.

Kérés

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

POST /passports/{id}/archive szükséges hozzá: passports:publish

Archivál egy útlevelet, és kivonja a nyilvános oldalát a forgalomból.

Kérés

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

POST /passports/bulk-publish szükséges hozzá: passports:publish

Egy hívással legfeljebb 50 útlevélpiszkozatot tesz közzé, és útlevelenként jelenti az eredményt, így egyetlen hiba sem szakítja meg a köteget.

Paraméter	Típus		Leírás
passport_ids	array	kötelező	1–50 útlevél-azonosító.

Kérés

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]}'

Válasz

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

POST /passports/{id}/successor szükséges hozzá: passports:write

Újrahasználatra előkészített, új célra alkalmazott vagy újragyártott termék esetén az akkumulátorrendelet (77. cikk (7) bekezdés) az eredetihez kapcsolt új útlevelet ír elő. Ez új termékrekordot és a közzétett útlevélből előre kitöltött, arra visszamutató útlevélpiszkozatot hoz létre. Az eredeti élő marad, és mindkét útlevél megjeleníti a kapcsolatot. Az újat a POST /passports/{id}/publish kéréssel tegye közzé.

Paraméter	Típus		Leírás
stage	string	kötelező	prepared_for_reuse, repurposed vagy remanufactured.

Kérés

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" }'

Válasz

{
  "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 szükséges hozzá: passports:read

Visszaadja az útlevél szektorsablonja által kért mezőkulcsokat (kötelező és opcionális), a jelenleg tárolt értékeket és a még hiányzó kötelező kulcsokat. Ezzel állíthatja össze a PUT /passports/{id}/fields kérés tartalmát.

Kérés

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

Válasz

{
  "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 szükséges hozzá: passports:write

Tetszőleges mezőérték-készletet ír egy piszkozat vagy élő útlevélre: akkumulátor esetén a teljes XIII. melléklet szerinti készletet, egy ágazati sablon mezőit vagy saját kulcsait. Csak a módosítani kívánt kulcsokat küldje; a null vagy üres érték eltávolítja a mezőt. Az élő útlevél helyben frissül, címe és QR-kódja nem változik, gépi fordításai újragenerálódnak. A megfelelést újrapontozzuk. Ez a hívás nem teszi közzé a piszkozatot; használja a POST /passports/{id}/publish végpontot.

Paraméter	Típus		Leírás
fields	object	kötelező	Mezőkulcs-érték leképezés. A kulcsok kisbetűkből, számjegyekből és aláhúzásokból állnak; az értékek legfeljebb 5000 karakteresek. Hívásonként legfeljebb 200 kulcs.

Kérés

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%"
    }
  }'

Válasz

{
  "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 szükséges hozzá: passports:write

Az akkumulátor saját adatait (az (EU) 2023/1542 rendelet XIII. mellékletének 4. pontja) küldi el egy közzétett útlevélhez BMS- és flottarendszerek számára. Küldje el az alábbi mezők tetszőleges részhalmazát; a frissítés után a megfelelés újraellenőrzésre kerül. Ezeket az értékeket csak az útlevél tulajdonosa által jóváhagyott megtekintők látják (77. cikk (2) bekezdés), a nyilvános oldalon soha. A capacity_fade, power_capability és internal_resistance értékeket az akkumulátor aktuális méréseiként (current_*) tároljuk, a modell eredeti értékeitől elkülönítve.

Paraméter	Típus	Leírás
state_of_health	string	pl. "97% 412 ciklusnál".
state_of_certified_energy	string	Hátralévő tanúsított energia (elektromos jármű akkumulátorai).
battery_status	string	original, repurposed, re-used, remanufactured vagy waste.
capacity_fade	string	Eddigi kapacitáscsökkenés. current_capacity_fade néven tárolva.
power_capability	string	Jelenlegi teljesítőképesség. current_power_capability néven tárolva.
internal_resistance	string	Mért belső ellenállás. current_internal_resistance néven tárolva.
use_data	string	Ciklusok, kedvezőtlen események, hőmérséklet és töltöttségi szint, legfeljebb 5000 karakter.

Kérés

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"
  }'

Válasz

{
  "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 szükséges hozzá: passports:write

Minden akkumulátornak saját útlevél kell (az (EU) 2023/1542 rendelet 77. cikkének (1) bekezdése). Egy hívással egy akkumulátormodell legfeljebb 10 000 akkumulátorát regisztrálhatja, mindegyiket saját sorozatszámmal (legfeljebb 20 betű, számjegy, pont, kötőjel vagy aláhúzás), és opcionálisan manufacturing_date, battery_status és a XIII. melléklet 4. pontja szerinti adataival. A meglévő sorozatszámok frissülnek; a kihagyott értékek megmaradnak. Ha a terméknek van GTIN-je, minden akkumulátor címe a GS1 Digital Linkje: /01/{gtin}/21/{serial}. A 4. pont szerinti adatokat csak a tulajdonos által jóváhagyott megtekintők látják.

Paraméter	Típus		Leírás
units[].serial	string	kötelező	Az akkumulátor sorozatszáma.
units[].manufacturing_date	string		Hónap és év, pl. "2026-09".
units[].battery_status	string		original vagy waste. A státuszváltozáshoz szükségesek az akkor mért értékek (XIII. melléklet, 4. pont a) alpont); a waste státuszhoz ezenkívül szükséges a responsible_party_type (producer, pro vagy waste_operator), a responsible_party_name és a responsible_party_contact (77. cikk (7) bekezdés). A recycled státusz a recycled_at és a recycler_name mezővel megszünteti az útlevelet (77. cikk (8) bekezdés). Az új rendeltetésre átalakított, újrahasznált vagy újragyártott akkumulátor új útlevelet kap: POST /passports/{id}/units/{serial}/successor.
units[].state_of_health	string		Továbbá: 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 és use_data.

Kérés

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%"}]}'

Válasz

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

PATCH /passports/{id}/units/{serial} szükséges hozzá: passports:write

Egyetlen akkumulátor adatait küldő akkumulátor-kezelő rendszer számára: a battery_status, state_of_health, state_of_certified_energy, current_capacity_fade, current_power_capability, current_internal_resistance és use_data bármelyike. Olvasáshoz használjon GET kérést ugyanarra az útvonalra, a listához pedig GET /passports/{id}/units (per_page legfeljebb 500).

Kérés

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"}'

Válasz

{
  "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 szükséges hozzá: passports:read

A XIII. melléklet 4. pont a) alpontja előírja a teljesítmény- és tartóssági értékeket az akkumulátor forgalomba hozatalakor és állapotának változásakor. Ezeket a méréseket változatlanul megőrizzük, bármit küldenek is később; ha időszakos mérést is meg szeretne őrizni, küldje a record_snapshot: true értéket egy PATCH kéréssel.

Kérés

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

Válasz

{
  "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 szükséges hozzá: passports:write

77. cikk (7) bekezdés: az újrahasználatra előkészített, új célra alkalmazott vagy újragyártott akkumulátor új útlevelet kap, amely az eredetijére hivatkozik. Ez új sorozatszámmal és azonosítóval újra nyilvántartásba veszi az akkumulátort a munkaterület egy második életciklusú akkumulátormodellje alatt (ha még nincs ilyen, ebből a modellből készül), összekapcsolja a kettőt, és megőrzi a változáskor mért értékeket. Az eredeti akkumulátor megtartja útlevelét. A második életciklusú modellt egészítse ki, majd tegye közzé a POST /passports/{id}/publish hívással.

Paraméter	Típus		Leírás
stage	string	kötelező	prepared_for_reuse, repurposed vagy remanufactured.
values	object	kötelező	A változáskor mért értékek: legalább egy a remaining_capacity_ah és a current_capacity_fade közül, egy a current_power_capability és a power_fade közül, egy a current_internal_resistance és az internal_resistance_increase közül, valamint az expected_lifetime_cycles_remaining (IV. melléklet, A. rész).
serial	string		Az új sorozatszám. Alapértelmezés: az eredeti sorozatszám -RU, -RP vagy -RM utótaggal.
measured_at	string		Az értékek mérésének időpontja.
member_state	string		Annak a tagállamnak a kétbetűs kódja, ahol az egészségi állapotot vizsgálták (73. cikk (1) bekezdés a) pont).
target_passport_id	integer		Ennek az akkumulátormodellnek egy meglévő második életciklusú modellje, amely alatt nyilvántartásba veszi.

Kérés

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"}}'

Válasz

{
  "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 szükséges hozzá: passports:write

Az útlevélen tárolja az uniós DPP-nyilvántartásba történő benyújtást és annak eredményét: állapot, korrelációs azonosító, a nyilvántartás által visszaadott regisztrációs azonosító, valamint opcionális hivatkozás egy DPP-szolgáltató által tárolt biztonsági másolatra. Maga a regisztráció a Bizottság nyilvántartásában történik (webes űrlap vagy fájlfeltöltés); ez az eredményt az útlevél mellett tartja. A GET /passports/{id} ugyanezt a blokkot adja vissza a registry alatt.

Paraméter	Típus	Leírás
status	string	not_submitted, submitted, registered vagy failed.
product_group	string	A nyilvántartás termékcsoportja, például batteries.
granularity	string	modell, tétel vagy darab.
upi	string	Egyedi termékazonosító https URL-ként. Alapértelmezés szerint a nyilvános útlevél URL-je.
correlation_id	string	A nyilvántartás által a benyújtáskor kiosztott korrelációs azonosító.
uri	string	A nyilvántartás által visszaadott regisztrációs azonosító.
backup_url	string	https hivatkozás a DPP-szolgáltató által tárolt biztonsági másolatra.
submitted_at	date	Benyújtás dátuma.
registered_at	date	Regisztráció dátuma.
error	string	Hibaleírás sikertelen benyújtás esetén.

Kérés

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"
  }'

Válasz

{
  "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 szükséges hozzá: passports:read

Az útlevél QR-kódja fájlként: svg (alapértelmezett), png (márkázott, nyomdakész) vagy pdf (címkelap).

Paraméter	Típus		Leírás
format	string		svg \| png \| pdf

Kérés

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

09 / VégpontokMegfelelőség

GET /passports/{passportId}/compliance szükséges hozzá: passports:read

Élő megfelelőségi ellenőrzést végez egy útlevélen a szektora kötelező mezői alapján, és pontosan jelzi, mi hiányzik.

Kérés

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

Válasz

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

10 / VégpontokÁgazatok

GET /sectors

Az ágazatok, amelyekbe egy termék besorolható: a platform rendszerágazatai, valamint a munkaterülete által meghatározottak. Termékek létrehozásakor az id-t, útlevélmezők írásakor a mezőkulcsokat használja.

Kérés

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

Válasz

{
  "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 / VégpontokDokumentumok

GET /products/{productId}/documents szükséges hozzá: products:read

A termékhez csatolt megfelelőségi nyilatkozatok, vizsgálati jegyzőkönyvek és tanúsítványok. A nyilvános dokumentum a termék minden közzétett útleveléből elérhető.

Kérés

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

Válasz

{
  "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 szükséges hozzá: products:write

Többrészes feltöltés. PDF, Word, Excel, CSV, szöveg, PNG és JPEG legfeljebb 10 MB-ig, termékenként legfeljebb 20. A szöveget a háttérben nyerjük ki.

Paraméter	Típus		Leírás
file	file	kötelező	A dokumentum.
is_public	boolean		Megjelenítés a nyilvános útlevélen (alapértelmezés: false).

Kérés

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} szükséges hozzá: products:write

Beállítja, hogy a dokumentum hivatkozva legyen-e a nyilvános útlevélről.

Paraméter	Típus		Leírás
is_public	boolean	kötelező

Kérés

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} szükséges hozzá: products:write

Eltávolítja a fájlt és annak útlevél-hivatkozását.

Kérés

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

Válasz

{ "message": "Document deleted." }

12 / VégpontokEllátási lánc

GET /products/{productId}/supply-chain szükséges hozzá: products:read

A termék útlevelén megjelenített lépések sorrendben.

Kérés

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

PUT /products/{productId}/supply-chain szükséges hozzá: products:write

Minden lépést lecserél az elküldött listára, a küldés sorrendjében. A törléshez küldjön üres listát. Lépéstípusok: raw_material, processing, manufacturing, assembly, packaging, distribution.

Paraméter	Típus		Leírás
steps	array	kötelező	Legfeljebb 50 lépés.
steps[].step_type	string	kötelező
steps[].supplier_name	string	kötelező
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

Kérés

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 / VégpontokFordítások

GET /passports/{id}/translations szükséges hozzá: passports:read

Minden lefordított mezőérték nyelvenként, a forrással együtt: auto (gépi, közzétételkor készült) vagy manual.

Kérés

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

Válasz

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

PUT /passports/{id}/translations/{locale} szükséges hozzá: passports:write

Egy nyelv fordításait állítja be mezőkulcsonként. A kézi fordítást gépi fordítás soha nem írja felül. Üres karakterlánc küldésével törölhető egy fordítás.

Paraméter	Típus		Leírás
fields	object	kötelező	field_key: lefordított érték

Kérés

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"}}'

Válasz

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

14 / VégpontokIntegritás és exportálás

GET /passports/{id}/integrity szükséges hozzá: passports:read

Az útlevél minden közzétett állapota hash-láncba fűzött, Ed25519-cel aláírt rekordként: ujjlenyomat (SHA-256), láncérték és aláírás. A nyilvános kulcsok a /.well-known/mpp-integrity-keys.json címen érhetők el, így bárki ellenőrizheti a láncot.

Kérés

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

Válasz

{ "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} szükséges hozzá: passports:read

A teljes rekord úgy, ahogyan aláírták, a pillanatképpel együtt: mit tartalmazott az útlevél abban a pillanatban, egészen az összes csatolt fájl hash-éig.

Kérés

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

GET /passports/{id}/epcis szükséges hozzá: passports:read

Az útlevél GS1 EPCIS 2.0 JSON-LD dokumentumként: a tétel üzembe vétele (commissioning), az ellátási lánc minden lépése megfigyelésként (observation), az egyes akkumulátorok egyedileg, a második élet útlevele pedig átalakításként (transformation). Az azonosítók GS1 Digital Link URI-k, ha a terméknek van GTIN-je.

Kérés

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

15 / VégpontokBeszállítói kérések

POST /passports/{id}/supplier-requests szükséges hozzá: passports:write

E-mailben privát hivatkozást küld a beszállítónak, amelyen a saját nyelvén kitöltheti az Ön által kiválasztott mezőket. Semmi sem kerül az útlevélbe, amíg a munkaterületén valaki jóvá nem hagyja.

Paraméter	Típus		Leírás
supplier_name	string	kötelező
supplier_email	string	kötelező
field_keys	array	kötelező	Mezőkulcsok az útlevél sablonjából.
locale	string		Az e-mail és az űrlap nyelve, pl. de.
due_at	date		Válaszadási határidő; ha nincs megadva, 14 nap.
message	string

Kérés

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 szükséges hozzá: passports:read

Az útlevélhez tartozó összes kérés az állapotukkal együtt.

Kérés

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

GET /supplier-requests/{id} szükséges hozzá: passports:read

Egy kérés a beszállító válaszaival, megjegyzésével és a csatolt fájlok nevével.

Kérés

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

16 / VégpontokÉrtékesítés utáni szolgáltatás

POST /passports/{id}/items szükséges hozzá: items:write

Adjon egy termék darabjainak (bármely ágazat, kivéve az akkumulátorokat, amelyek a /units végpontot használják) saját sorozatszámot: mindegyik saját címet és QR-kódot, a címkéjére rejtett eredetiségkódot kap, és tulajdonosa regisztrálhatja. Küldjön legfeljebb 10 000 darabot vagy egy tartományt. GTIN-nel a cím a GS1 Digital Link /01/{gtin}/21/{serial}.

Paraméter	Típus		Leírás
items[].serial	string	kötelező	Legfeljebb 20 betű, számjegy, pont, kötőjel vagy aláhúzás.
items[].batch	string		Gyártási tétel, legfeljebb 20 karakter.
items[].manufactured_on	string		Gyártási dátum, ÉÉÉÉ-HH-NN.
range	object		Az items helyett: prefix, start, count, digits és batch, például SN-00001-től SN-00500-ig.

Kérés

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"}}'

Válasz

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

GET /passports/{id}/items/{serial} szükséges hozzá: items:read

Egy darab a címével, állapotával, regisztrációs adataival és a jótállás lejáratával, az eredetiség-ellenőrzésekkel és előzményekkel. Az items:write jogú kulcs a rejtett kódot is megkapja nyomtatáshoz. A GET /passports/{id}/items listázza őket (status és batch szűrők, per_page legfeljebb 500).

Kérés

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

Válasz

{
  "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} szükséges hozzá: items:write

Állítsa a status mezőt stolen vagy recalled értékre, és oldala figyelmezteti azt, aki beszkenneli, az Ön status_note szövegével; lopott darab nem regisztrálható. A retired offline állapotba teszi az oldalt. A batch és a manufactured_on is módosítható.

Paraméter	Típus		Leírás
status	string		active, stolen, recalled vagy retired.
status_note	string		A darab oldalán jelenik meg, legfeljebb 500 karakter.

Kérés

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 szükséges hozzá: aftersales:read

Akik regisztrálták termékeit: név, e-mail, ország, vásárlás dátuma, kereskedő, jótállási dátumok, és hogy hozzájárultak-e a hírekhez és ajánlatokhoz (marketing_consent=1 csak őket listázza). Alapértelmezés szerint az aktív regisztrációk; status=pending, transferred vagy ended a többihez; since= egy dátum utáni változásokhoz.

Kérés

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

GET /service-requests szükséges hozzá: aftersales:read

Útleveleiből küldött javítások, jótállási igények, visszavételek, pótalkatrészek és kérdések, a legújabbak elöl, status és type szűrőkkel. A GET /service-requests/{reference} a beszélgetést is hozzáadja.

Kérés

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

POST /service-requests/{reference}/replies szükséges hozzá: aftersales:write

Válaszát e-mailben küldjük el az ügyfélnek, a kérés oldalának linkjével, az ügyfél nyelvén. Az internal: true csak a csapata számára látható jegyzetet ad hozzá. A PATCH /service-requests/{reference} egy status értékkel viszi tovább (az ügyfél értesítést kap, amikor folyamatban, megoldva vagy lezárva van).

Paraméter	Típus		Leírás
body	string	kötelező	A válasz, legfeljebb 5000 karakter.
internal	boolean		Jegyzet a csapatnak válasz helyett.
status	string		new, in_progress, waiting, resolved vagy closed.

Kérés

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 / VégpontokTömeges szerkesztés és képek

PATCH /products/bulk-fields szükséges hozzá: products:write

Termékadatot vagy útlevélmezőt állít be legfeljebb 5000 terméken. A mode értéke set, fill (csak ahol üres) vagy clear. A kérésen belül legfeljebb 100 termék frissül; a nagyobb halmazok sorba kerülnek (202).

Paraméter	Típus		Leírás
product_ids	array	kötelező
target	string	kötelező	product \| field
key	string	kötelező
value	string
mode	string		set \| fill \| clear

Kérés

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"}'

Válasz

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

POST /products/{id}/images szükséges hozzá: products:write

JPG, PNG vagy WebP fájl feltöltése multipart kérésben (legfeljebb 15MB, termékenként 8). Az első kép a nyilvános útlevél borítóképe.

Paraméter	Típus		Leírás
image	file	kötelező
alt	string		A kép leírása.

Kérés

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 szükséges hozzá: products:write

Adja meg az image_ids értékeit a kívánt sorrendben; az első lesz a borítókép.

Paraméter	Típus		Leírás
image_ids	array	kötelező

Kérés

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} szükséges hozzá: products:write

Eltávolítja a képet és annak fájlját.

Kérés

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

18 / VégpontokWebhookok

GET /webhooks szükséges hozzá: webhooks:manage

A munkaterülethez regisztrált végpontok. A titkos kulcsok itt nem szerepelnek; egy végpont lekérésével láthatja annak titkos kulcsát.

Kérés

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

POST /webhooks szükséges hozzá: webhooks:manage

Nyilvános HTTPS URL-t regisztrál egy vagy több eseményhez. A válasz tartalmazza az aláírási titkot. A privát vagy belső hosztokat elutasítjuk.

Paraméter	Típus		Leírás
url	string	kötelező
events	array	kötelező	Az alább felsorolt események bármelyike.

Kérés

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"]}'

Válasz

{
  "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} szükséges hozzá: webhooks:manage

Kérés

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

PUT /webhooks/{id} szükséges hozzá: webhooks:manage

Módosítsa az URL-t vagy az eseményeket, vagy szüneteltesse és folytassa a végpontot. A folytatás nullázza a hibaszámlálót; a végpont 10 egymást követő sikertelen kézbesítés után automatikusan szünetel.

Paraméter	Típus		Leírás
url	string
events	array
is_active	boolean

Kérés

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 szükséges hozzá: webhooks:manage

Sorba állít egy webhook.test kézbesítést, hogy ellenőrizhesse fogadóját és aláírási kódját.

Kérés

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

Válasz

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

GET /webhooks/{id}/deliveries szükséges hozzá: webhooks:manage

Legutóbbi kézbesítések, a legújabbal kezdve, a végpontja által visszaadott HTTP-állapottal és a válasz első 500 karakterével.

Paraméter	Típus		Leírás
per_page	integer		Legfeljebb 100.

Kérés

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

DELETE /webhooks/{id} szükséges hozzá: webhooks:manage

Kérés

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

Válasz

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

19 / EseményekWebhookok

Lekérdezés helyett regisztráljon webhook-végpontot az alkalmazásban (Webhooks oldal, a Starter csomagtól elérhető), és a MyProductPassport POST-kéréssel JSON-t küld az URL-jére az események bekövetkeztekor:

Esemény	Akkor aktiválódik, amikor
product.created	Egy termék létrejön (alkalmazás, API vagy CSV-importálás)
product.updated	Egy termék frissül
product.deleted	Egy termék törlődik
passport.created	Egy útlevél létrejön
passport.published	Egy útlevél élővé válik
passport.archived	Egy útlevél archiválásra kerül
supplier_request.submitted	Egy beszállító elküldi a kért adatokat
owner.registered	Egy tulajdonos megerősíti regisztrációját
owner.transferred	Egy darab új regisztrált tulajdonoshoz kerül
service_request.created	Egy ügyfél szervizkérést küld egy útlevélből
service_request.updated	Egy szervizkérés választ vagy új állapotot kap
item.status_changed	Egy darabot lopottnak, visszahívottnak vagy használaton kívülinek jelölnek, vagy a jelölést megszüntetik
item.verification_failed	Egy biztonságos címke leolvasása sikertelen, halmozódnak a hibás kódok, vagy egy sorozatszám túl sok helyen tűnik fel
webhook.test	Tesztkézbesítést küld az alkalmazásból

Minden kézbesítés egy JSON-boríték: kézbesítési azonosító (újrapróbálkozáskor ugyanaz az azonosító érkezik, így kiszűrheti a duplikátumokat), az esemény, a próbálkozás sorszáma, időbélyeg és az esemény adatai. Az útlevél-események tartalmazzák az útlevél uuid-ját és nyilvános URL-jét, így ritkán kell második kérés:

Kézbesítés törzse

{
  "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"}
  }
}

A fejlécek tartalmazzák az esemény nevét, a kézbesítési azonosítót, egy Unix-időbélyeget és a nyers törzs HMAC-aláírását, így ellenőrizheti, hogy tőlünk érkezett, és elutasíthatja az ismétléseket:

Kézbesítés fejlécei

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>

Válaszoljon bármilyen 2xx kóddal 10 másodpercen belül. Minden más esetben ötször próbálkozunk újra körülbelül 90 perc alatt (30 s, 1 perc, 5 perc, 15 perc, 1 óra); 10 egymást követő hiba után a végpont szünetel, amíg újra nem engedélyezi.

Ellenőrzés (PHP)

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

Süti	Cél	Lejárat
myproductpassport-session	Bejelentkezve tartja Önt, és biztonságban a webhelyet	2 óra
XSRF-TOKEN	Védi az űrlapokat a webhelyek közötti kéréshamisítás ellen	2 óra
cookie_consent	Megjegyzi a sütikkel kapcsolatos választását	12 hónap
locale_suggested countdown_dismissed exit_intent_dismissed	Megjegyzi, hogy bezárt egy üzenetet, hogy ne jelenjen meg újra	Legfeljebb 30 nap

Süti	Cél	Lejárat
_ga, _ga_*	Google Analytics: számolja a látogatásokat, és megmutatja, hogyan használják a webhelyet	2 év
_gcl_au	Google Ads: méri, mely hirdetések vezetnek regisztrációhoz	90 nap
mpp_ref	Megjegyzi a partnert, akinek a hivatkozását követte, hogy jóváírjuk neki, ha később regisztrál	90 nap

API-referencia

01 / Első lépésekHitelesítés

02 / Első lépésekKérésszám-korlátok

03 / Első lépésekHibák

04 / Első lépésekLapozás

05 / Első lépésekMI-asszisztens csatoló (MCP)

06 / VégpontokFiók

07 / VégpontokTermékek

08 / VégpontokÚtlevelek

09 / VégpontokMegfelelőség

10 / VégpontokÁgazatok

11 / VégpontokDokumentumok

12 / VégpontokEllátási lánc

13 / VégpontokFordítások

14 / VégpontokIntegritás és exportálás

15 / VégpontokBeszállítói kérések

16 / VégpontokÉrtékesítés utáni szolgáltatás

17 / VégpontokTömeges szerkesztés és képek

18 / VégpontokWebhookok

19 / EseményekWebhookok

Mielőtt elmenne…

Felkerült a listára!