Kūrėjai / REST API

API žinynas

Viskas „MyProductPassport“ pasiekiama per raktu autentifikuojamą REST API: kurkite produktus, generuokite ir skelbkite skaitmeninius produktų pasus, siųskite realaus laiko baterijų duomenis ir tikrinkite atitiktį tiesiai iš savo ERP, PIM ar kūrimo grandinės.

v1 https://myproductpassport.eu/api/v1 Pradėti nemokamai OpenAPI specifikacija ↓

01 / PradžiaAutentifikavimas

Kiekviena užklausa autentifikuojama API raktu, perduodamu kaip Bearer prieigos raktas. Raktai kuriami programoje skiltyje API raktai, rodomi vieną kartą ir saugomi užmaišyti; kiekvienas raktas turi savo leidimų rinkinį, pasirinktinį leidžiamų IP sąrašą ir pasirinktinę galiojimo pabaigos datą. Raktus galima keisti be prastovų.

Užklausos antraštė

Authorization: Bearer pk_your_api_key

Visuose planuose. API raktus galima kurti ir naudoti visuose planuose, taip pat nemokamame. Planas nustato, kiek užklausų per minutę raktas gali siųsti (žemiau) ir kiek gaminių bei pasų gali turėti darbo sritis.

Bandomasis režimas. Bandomasis raktas (pk_test_...) vykdo kiekvieną iškvietimą lygiai taip pat kaip tikrasis raktas, su tuo pačiu tikrinimu, ID ir atsakymais, o tada jį atšaukia: niekas neišsaugoma, nesiunčiamas joks el. laiškas ar webhook ir neišlaikomas joks failas. Atsakymuose yra "test_mode": true ir antraštė X-MPP-Mode: test. Sukurkite ir išbandykite integraciją su savo tikrais duomenimis, tada pakeiskite raktą tikruoju.

Leidimai suteikiami kiekvienam raktui, todėl integracija gauna tik tai, ko reikia:

Leidimas	Suteiktos prieigos
products:read	Produktų skaitymas
products:write	Produktų kūrimas, atnaujinimas ir trynimas
passports:read	Pasų skaitymas
passports:write	Generuoti pasus
passports:publish	Pasų skelbimas ir archyvavimas
webhooks:manage	Webhook galinių taškų kūrimas, testavimas ir šalinimas
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 / PradžiaUžklausų limitai

Limitai taikomi kiekvienam raktui, per minutę, ir priklauso nuo plano:

Planas	Užklausos / minutę
Nemokamai	30
Micro	60
E. etiketė	60
Starter	120
Professional	300
Business	600
Battery	600

Kiekviename atsakyme yra antraštės X-RateLimit-Limit ir X-RateLimit-Remaining. Viršijus limitą grąžinamas 429:

429 Too Many Requests

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

03 / PradžiaKlaidos

Klaidos pateikiamos JSON formatu su įprastu būsenos kodu. Dažniausios:

Būsena	Reikšmė	Turinio pavyzdys
401	Trūkstamas, negaliojantis, atšauktas arba pasibaigęs raktas	`{"error": "Invalid or revoked API key."}`
403	Raktui trūksta leidimo, IP adreso nėra leidžiamų sąraše arba pasiektas plano limitas	`{"message": "API key does not have 'products:write' permission."}`
404	Išteklius jūsų darbo srityje neegzistuoja	`{"message": "Not found."}`
422	Patvirtinti nepavyko	`{"message": "…", "errors": {"gtin": ["…"]}}`
429	Viršytas užklausų limitas	`{"error": "Rate limit exceeded."}`

04 / PradžiaPuslapiavimas

Sąrašų galiniai taškai grąžina 25 elementus puslapyje su standartiniais links ir meta objektais. Norėdami naršyti kolekciją, perduokite ?page=2.

05 / PradžiaDI asistento jungtis (MCP)

Prijunkite Claude, Cursor ar bet kurį asistentą, kuris palaiko Model Context Protocol, ir paprastais žodžiais paprašykite kurti gaminius, pildyti pasus pagal tai, ką jam pasakote, ir tikrinti, ko dar trūksta. Jis naudoja API raktą su to rakto leidimais ir užklausų limitu. Jis gali kurti juodraščius ir pildyti laukus; jis niekada nieko neskelbia, nearchyvuoja ir netrina: tai lieka jums programėlėje.

Serverio adresas (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 ir kiti klientai, paleidžiantys vietinį serverį

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

Siūlomi įrankiai:

Įrankis	Ką daro
list_products	Darbo srities gaminiai, nuo naujausių, po 25 puslapyje, su sektoriumi ir naujausiu pasu.
get_product	Vienas gaminys su duomenimis, sektoriumi, reguliavimo skiltimis ir naujausiu pasu.
list_sectors	Sektorių šablonai, kuriuos gali naudoti gaminys (tekstilė, elektronika, baterijos, vynas ir kt.), su jų ID. Gaminio sektorius lemia, kurie paso laukai privalomi.
create_product	Prideda gaminį į darbo sritį. Naudokite sector_id iš list_sectors. compliance_sections prideda pasui reguliavimo skiltis: gpsr, epr, france, chemicals, eudr.
list_passports	Darbo srities pasai, nuo naujausių, po 25 puslapyje, su būsena (draft, published, archived), išsamumo procentu ir viešu adresu.
get_passport	Vienas pasas: būsena, versija, išsamumo procentas, viešas adresas ir QR kodo nuorodos.
create_passport	Sukuria gaminio paso juodraštį. Jis neskelbiamas: jį paskelbia žmogus programėlėje.
get_passport_fields	Ko prašo pasas: privalomų ir neprivalomų laukų raktai, ką kiekvienas reiškia (pavadinimas, aprašymas, pavyzdys), esamos reikšmės ir trūkstami privalomi laukai.
update_passport_fields	Įrašo laukų reikšmes į juodraštį ar paskelbtą pasą (paskelbtas atnaujinamas vietoje: tas pats adresas, tas pats QR kodas). Raktai iš get_passport_fields; tuščias tekstas pašalina reikšmę. Rašykite tik faktus, kuriuos nurodo naudotojas ar jo dokumentai.
get_compliance	Paso išsamumas: procentas, būsena ir dar trūkstami privalomi laukai.

Išbandykite su bandomuoju raktu. Su bandomuoju raktu (pk_test_...) asistento pakeitimai patikrinami ir atšaukiami, todėl matote, ką jis darytų, prieš suteikdami jam tikrą raktą.

06 / Galiniai taškaiPaskyra

GET /me

Grąžina autentifikuotą paskyrą, jos prenumeratos lygį ir kiek produktų limito išnaudota. Naudinga ryšiui patikrinti.

Užklausa

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

Atsakymas

{
  "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 / Galiniai taškaiProduktai

GET /products reikalauja products:read

Pateikia jūsų darbo srities produktus nuo naujausių, po 25 puslapyje. Kiekvienas produktas apima savo sektorių ir naujausio paso santrauką.

Parametras	Tipas		Aprašymas
page	integer		Puslapio numeris.

Užklausa

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

Atsakymas

{
  "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 reikalauja products:write

Sukuria vieną produktą. Grąžina 403, jei plano produktų limitas išnaudotas.

Parametras	Tipas		Aprašymas
name	string	privaloma	Produkto pavadinimas, iki 255 simbolių.
sku	string		Jūsų vidinis SKU, iki 100 simbolių.
gtin	string		GTIN-8, 12, 13 arba 14 (tik skaitmenys).
brand	string		Viešame pase rodomas prekės ženklas.
description	string		Iki 2 000 simbolių.
category	string		Laisvo teksto kategorija. Numatytoji reikšmė "general".
sector_id	integer		Sektoriaus ID, pagal kurį parenkamas paso laukų šablonas.
country_of_origin	string		Šalies kodas, pvz., "PT".
weight	number		Grynasis svoris.
weight_unit	string		Vienas iš kg, g, lb, oz. Numatytoji reikšmė kg.
materials	array		Objektai {name, percentage 0-100}.
has_packaging	boolean		Prideda prie paso pakuotės šablono laukus (raktai, prasidedantys pkg_), su tuo pačiu QR kodu.

Užklausa

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

Atsakymas

{
  "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 reikalauja products:write

Vienu kvietimu sukuria iki 100 produktų. Visa partija atmetama su 403, jei viršytų jūsų likusį produktų limitą. Tūkstančių produktų katalogams kvieskite šį galinį tašką cikle arba naudokite CSV importą programoje.

Parametras	Tipas		Aprašymas
products	array	privaloma	Nuo 1 iki 100 produktų objektų su tais pačiais laukais kaip „Sukurti produktą“ (be medžiagų).

Užklausa

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

Atsakymas

{
  "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} reikalauja products:read

Grąžina vieną produktą su jo sektoriumi ir naujausio paso santrauka. 404, jei ID nėra jūsų darbo srityje.

Užklausa

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

PUT /products/{id} reikalauja products:write

Iš dalies atnaujina produktą. Siųskite tik laukus, kuriuos norite pakeisti; laukų sąrašas toks pat kaip „Sukurti produktą“.

Užklausa

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} reikalauja products:write

Pašalina produktą su galimybe atkurti. Paskelbti produkto pasai toliau veikia, todėl atspausdinti QR kodai niekada nelieka be puslapio.

Užklausa

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

Atsakymas

{ "message": "Product deleted." }

08 / Galiniai taškaiPasai

GET /passports reikalauja passports:read

Pateikia pasus nuo naujausių, po 25 puslapyje, su produkto santrauka ir visais paso laukais.

Parametras	Tipas		Aprašymas
page	integer		Puslapio numeris.

Užklausa

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

Atsakymas

{
  "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 reikalauja passports:write

Sugeneruoja produkto paso juodraštį, iš anksto užpildydamas laukus iš produkto duomenų ir sektoriaus šablono. Grąžina juodraštį su atitikties balu. Produktui, kuris jau turi aktyvų pasą, grąžinamas 409 su tuo pasu: pataisykite jį su PUT /passports/{id}/fields, kuris išsaugo jo adresą ir QR kodą.

Užklausa

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

GET /passports/{id} reikalauja passports:read

Grąžina vieną pasą su produktu, laukais, viešu URL ir GS1 Digital Link.

Užklausa

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

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

Paskelbia paso juodraštį ir įjungia jo viešą puslapį bei QR kodą. Galima skelbti tik juodraščius; kitais atvejais grąžinamas 404.

Užklausa

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

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

Archyvuoja pasą ir išima jo viešą puslapį iš apyvartos.

Užklausa

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

POST /passports/bulk-publish reikalauja passports:publish

Vienu kvietimu paskelbia iki 50 pasų juodraščių ir pateikia kiekvieno paso rezultatą, todėl viena klaida niekada nenutraukia partijos.

Parametras	Tipas		Aprašymas
passport_ids	array	privaloma	Nuo 1 iki 50 pasų ID.

Užklausa

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

Atsakymas

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

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

Produktui, paruoštam pakartotiniam naudojimui, pritaikytam naujai paskirčiai ar perdirbtam, Baterijų reglamentas (77 straipsnio 7 dalis) reikalauja naujo paso, susieto su originaliu. Taip sukuriamas naujas produkto įrašas ir paso juodraštis, iš anksto užpildytas iš paskelbtojo ir susietas su juo. Originalas lieka aktyvus, o abiejuose pasuose rodoma nuoroda. Naująjį paskelbkite su POST /passports/{id}/publish.

Parametras	Tipas		Aprašymas
stage	string	privaloma	prepared_for_reuse, repurposed arba remanufactured.

Užklausa

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

Atsakymas

{
  "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 reikalauja passports:read

Grąžina laukų raktus, kurių reikalauja paso sektoriaus šablonas (privalomus ir neprivalomus), dabartines reikšmes ir kurių privalomų raktų dar trūksta. Naudokite tai PUT /passports/{id}/fields turiniui sudaryti.

Užklausa

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

Atsakymas

{
  "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 reikalauja passports:write

Įrašo bet kokį laukų reikšmių rinkinį į juodraštį arba aktyvų pasą: visą XIII priedo rinkinį baterijai, sektoriaus šablono laukus arba jūsų raktus. Siųskite tik raktus, kuriuos norite pakeisti; null arba tuščia reikšmė pašalina lauką. Aktyvus pasas atnaujinamas vietoje, jo adresas ir QR kodas nesikeičia, o mašininiai vertimai sugeneruojami iš naujo. Atitiktis įvertinama iš naujo. Šis kvietimas juodraščio nepaskelbia; naudokite POST /passports/{id}/publish.

Parametras	Tipas		Aprašymas
fields	object	privaloma	Lauko rakto ir reikšmės atitikmenys. Raktai – mažosios raidės, skaitmenys ir pabraukimai; reikšmės iki 5 000 simbolių. Iki 200 raktų vienu kvietimu.

Užklausa

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

Atsakymas

{
  "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 reikalauja passports:write

Siunčia šios baterijos duomenis (Reglamento (ES) 2023/1542 XIII priedo 4 punktas) į paskelbtą pasą BMS ir parkų sistemoms. Siųskite bet kurį toliau nurodytų laukų poaibį; po atnaujinimo atitiktis patikrinama iš naujo. Šios reikšmės rodomos tik paso savininko patvirtintiems žiūrovams (77 straipsnio 2 dalis), niekada viešame puslapyje. capacity_fade, power_capability ir internal_resistance saugomi kaip dabartiniai šios baterijos rodmenys (current_*), atskirai nuo pradinių modelio reikšmių.

Parametras	Tipas	Aprašymas
state_of_health	string	pvz., "97% po 412 ciklų".
state_of_certified_energy	string	Likusi sertifikuota energija (elektromobilių baterijos).
battery_status	string	original, repurposed, re-used, remanufactured arba waste.
capacity_fade	string	Iki šiol sumažėjusi talpa. Saugoma kaip current_capacity_fade.
power_capability	string	Dabartinė galios geba. Saugoma kaip current_power_capability.
internal_resistance	string	Išmatuota vidinė varža. Saugoma kaip current_internal_resistance.
use_data	string	Ciklai, neigiami įvykiai, temperatūra ir įkrovos būsena, iki 5 000 simbolių.

Užklausa

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

Atsakymas

{
  "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 reikalauja passports:write

Kiekvienai baterijai reikia savo paso (Reglamento (ES) 2023/1542 77 straipsnio 1 dalis). Vienu kvietimu užregistruokite iki 10 000 vieno modelio baterijų, kiekvieną su savo serijos numeriu (iki 20 raidžių, skaitmenų, taškų, brūkšnelių ar pabraukimų) ir pasirinktinai manufacturing_date, battery_status bei XIII priedo 4 punkto duomenimis. Esami serijos numeriai atnaujinami; praleistos reikšmės išsaugomos. Jei produktas turi GTIN, kiekvienos baterijos adresas yra jos GS1 Digital Link, /01/{gtin}/21/{serial}. 4 punkto duomenys rodomi tik savininko patvirtintiems žiūrovams.

Parametras	Tipas		Aprašymas
units[].serial	string	privaloma	Baterijos serijos numeris.
units[].manufacturing_date	string		Mėnuo ir metai, pvz., "2026-09".
units[].battery_status	string		original arba waste. Pasikeitus būsenai reikia tuo metu išmatuotų verčių (XIII priedo 4 punkto a papunktis); waste taip pat reikalauja responsible_party_type (producer, pro arba waste_operator), responsible_party_name ir responsible_party_contact (77 straipsnio 7 dalis). recycled kartu su recycled_at ir recycler_name užbaigia pasą (77 straipsnio 8 dalis). Kitai paskirčiai pritaikyta, pakartotinai panaudota ar atnaujinta baterija gauna naują pasą: POST /passports/{id}/units/{serial}/successor.
units[].state_of_health	string		Taip pat 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 ir use_data.

Užklausa

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

Atsakymas

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

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

Baterijos valdymo sistemai, siunčiančiai vienos baterijos duomenis: bet kuris iš battery_status, state_of_health, state_of_certified_energy, current_capacity_fade, current_power_capability, current_internal_resistance ir use_data. Norėdami skaityti, naudokite GET tuo pačiu keliu arba GET /passports/{id}/units sąrašui gauti (per_page iki 500).

Užklausa

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

Atsakymas

{
  "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 reikalauja passports:read

XIII priedo 4 punkto a papunktyje reikalaujama veikimo ir patvarumo verčių, kai baterija pateikiama rinkai ir kai pasikeičia jos būsena. Šie rodmenys išsaugomi tokie, kokie buvo, nesvarbu, kas atsiunčiama vėliau; kad išsaugotumėte ir periodinį rodmenį, su PATCH siųskite record_snapshot: true.

Užklausa

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

Atsakymas

{
  "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 reikalauja passports:write

77 straipsnio 7 dalis: baterija, kuri buvo paruošta pakartotiniam naudojimui, pritaikyta kitai paskirčiai arba pergaminta, turi naują pasą, susietą su jos originalu. Taip baterija užregistruojama iš naujo su nauju serijos numeriu ir identifikatoriumi pagal jūsų darbo srities antrojo gyvenimo baterijos modelį (jei jo dar nėra, jis sukuriamas iš šio modelio), abu pasai susiejami ir išsaugomos pasikeitimo metu išmatuotos vertės. Originali baterija išlaiko savo pasą. Užbaikite ir paskelbkite antrojo gyvenimo modelį naudodami POST /passports/{id}/publish.

Parametras	Tipas		Aprašymas
stage	string	privaloma	prepared_for_reuse, repurposed arba remanufactured.
values	object	privaloma	Pasikeitimo metu išmatuotos vertės: bent viena iš remaining_capacity_ah arba current_capacity_fade, iš current_power_capability arba power_fade, iš current_internal_resistance arba internal_resistance_increase, taip pat expected_lifetime_cycles_remaining (IV priedo A dalis).
serial	string		Naujas serijos numeris. Numatytasis: originalus serijos numeris su priesaga -RU, -RP arba -RM.
measured_at	string		Kada vertės buvo išmatuotos.
member_state	string		Dviejų raidžių valstybės narės, kurioje buvo tikrinta būklė, kodas (73 straipsnio 1 dalies a punktas).
target_passport_id	integer		Esamas šio baterijos modelio antrojo gyvenimo modelis, pagal kurį ją užregistruoti.

Užklausa

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

Atsakymas

{
  "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 reikalauja passports:write

Išsaugo pase pateikimą į ES DPP registrą ir jo rezultatą: būseną, koreliacijos ID, registro grąžintą registracijos identifikatorių ir pasirinktinę nuorodą į DPP paslaugų teikėjo talpinamą atsarginę kopiją. Pati registracija atliekama Komisijos registre (žiniatinklio forma arba failo įkėlimas); tai išlaiko rezultatą kartu su pasu. GET /passports/{id} grąžina tą patį bloką lauke registry.

Parametras	Tipas	Aprašymas
status	string	not_submitted, submitted, registered arba failed.
product_group	string	Registro produktų grupė, pavyzdžiui, batteries.
granularity	string	modelis, partija ar vienetas.
upi	string	Unikalus produkto identifikatorius kaip https URL. Numatytasis – viešojo paso URL.
correlation_id	string	Koreliacijos ID, kurį registras suteikia pateikiant.
uri	string	Registro grąžintas registracijos identifikatorius.
backup_url	string	https nuoroda į DPP paslaugų teikėjo talpinamą atsarginę kopiją.
submitted_at	date	Pateikimo data.
registered_at	date	Registracijos data.
error	string	Nesėkmingo pateikimo klaidos aprašymas.

Užklausa

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

Atsakymas

{
  "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 reikalauja passports:read

Paso QR kodas kaip failas: svg (numatytasis), png (su prekės ženklu, paruoštas spausdinti) arba pdf (etikečių lapas).

Parametras	Tipas		Aprašymas
format	string		svg \| png \| pdf

Užklausa

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

09 / Galiniai taškaiAtitiktis

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

Atlieka realaus laiko paso atitikties patikrą pagal jo sektoriaus privalomus laukus ir tiksliai nurodo, ko trūksta.

Užklausa

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

Atsakymas

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

10 / Galiniai taškaiSektoriai

GET /sectors

Sektoriai, kuriems galima priskirti produktą: platformos sisteminiai sektoriai ir visi jūsų darbo srityje apibrėžti. Kurdami produktus naudokite id, o rašydami paso laukus – laukų raktus.

Užklausa

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

Atsakymas

{
  "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 / Galiniai taškaiDokumentai

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

Prie produkto pridėtos atitikties deklaracijos, bandymų ataskaitos ir sertifikatai. Viešas dokumentas susietas iš kiekvieno paskelbto produkto paso.

Užklausa

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

Atsakymas

{
  "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 reikalauja products:write

Kelių dalių įkėlimas. PDF, Word, Excel, CSV, tekstas, PNG ir JPEG iki 10 MB, ne daugiau kaip 20 vienam produktui. Tekstas išgaunamas fone.

Parametras	Tipas		Aprašymas
file	file	privaloma	Dokumentas.
is_public	boolean		Rodyti viešajame pase (numatyta false).

Užklausa

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} reikalauja products:write

Įjungia arba išjungia dokumento nuorodą viešajame pase.

Parametras	Tipas		Aprašymas
is_public	boolean	privaloma

Užklausa

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} reikalauja products:write

Pašalina failą ir jo sąsają su pasu.

Užklausa

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

Atsakymas

{ "message": "Document deleted." }

12 / Galiniai taškaiTiekimo grandinė

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

Produkto pase rodomi žingsniai iš eilės.

Užklausa

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

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

Pakeičia visus žingsnius jūsų siunčiamu sąrašu, siuntimo tvarka. Norėdami išvalyti, siųskite tuščią sąrašą. Žingsnių tipai: raw_material, processing, manufacturing, assembly, packaging, distribution.

Parametras	Tipas		Aprašymas
steps	array	privaloma	Iki 50 žingsnių.
steps[].step_type	string	privaloma
steps[].supplier_name	string	privaloma
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

Užklausa

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 / Galiniai taškaiVertimai

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

Kiekviena išversta lauko reikšmė pagal kalbą su šaltiniu: auto (mašininis, sukurtas skelbiant) arba manual.

Užklausa

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

Atsakymas

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

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

Nustato vienos kalbos vertimus pagal lauko raktą. Rankinis vertimas niekada neperrašomas mašininiu. Norėdami pašalinti vertimą, siųskite tuščią eilutę.

Parametras	Tipas		Aprašymas
fields	object	privaloma	field_key: išversta reikšmė

Užklausa

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

Atsakymas

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

14 / Galiniai taškaiVientisumas ir eksportas

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

Kiekviena paskelbta paso būsena kaip maiša susietas, Ed25519 parašu pasirašytas įrašas: kontrolinis kodas (SHA-256), grandinės reikšmė ir parašas. Viešieji raktai pateikti adresu /.well-known/mpp-integrity-keys.json, todėl grandinę gali patikrinti bet kas.

Užklausa

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

Atsakymas

{ "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} reikalauja passports:read

Visas įrašas toks, koks buvo pasirašytas, įskaitant momentinę kopiją: ką pasas nurodė tuo metu, iki kiekvieno pridėto failo maišos.

Užklausa

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

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

Pasas kaip GS1 EPCIS 2.0 JSON-LD dokumentas: užsakytas (commissioned) elementas, kiekvienas tiekimo grandinės etapas kaip stebėjimas, atskiros baterijos ir antrojo gyvavimo ciklo pasas kaip transformacija. Kai produktas turi GTIN, identifikatoriai yra GS1 Digital Link URI.

Užklausa

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

15 / Galiniai taškaiTiekėjų prašymai

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

Tiekėjui el. paštu išsiunčiama privati nuoroda užpildyti jūsų pasirinktus laukus jo kalba. Į pasą niekas nepatenka, kol to nepatvirtina kas nors iš jūsų darbo srities.

Parametras	Tipas		Aprašymas
supplier_name	string	privaloma
supplier_email	string	privaloma
field_keys	array	privaloma	Laukų raktai iš paso šablono.
locale	string		El. laiško ir formos kalba, pvz., de.
due_at	date		Atsakymo terminas; jei nenurodytas, 14 dienų.
message	string

Užklausa

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 reikalauja passports:read

Visi paso prašymai su jų būsena.

Užklausa

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

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

Vienas prašymas su tiekėjo atsakymais, pastaba ir pridėtų failų pavadinimais.

Užklausa

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

16 / Galiniai taškaiPo pardavimo

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

Suteikite produkto vienetams (bet kurio sektoriaus, išskyrus baterijas, kurios naudoja /units) savo serijos numerį: kiekvienas gauna savo adresą ir QR kodą, paslėptą autentiškumo kodą etiketei, o savininkas gali jį užregistruoti. Siųskite iki 10 000 vienetų arba intervalą. Su GTIN adresas yra GS1 Digital Link /01/{gtin}/21/{serial}.

Parametras	Tipas		Aprašymas
items[].serial	string	privaloma	Iki 20 raidžių, skaitmenų, taškų, brūkšnelių arba apatinių brūkšnių.
items[].batch	string		Partija, iki 20 simbolių.
items[].manufactured_on	string		Pagaminimo data, MMMM-MM-DD.
range	object		Vietoj items: prefix, start, count, digits ir batch, pavyzdžiui, nuo SN-00001 iki SN-00500.

Užklausa

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

Atsakymas

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

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

Vienetas su adresu, būsena, informacija, ar jis užregistruotas ir iki kada galioja garantija, autentiškumo patikromis ir istorija. Raktas su items:write gauna ir paslėptą kodą spausdinimui. GET /passports/{id}/items juos išvardija (filtrai status ir batch, per_page iki 500).

Užklausa

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

Atsakymas

{
  "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} reikalauja items:write

Nustatykite būseną stolen arba recalled, ir jo puslapis įspės kiekvieną jį nuskaitantį asmenį, pateikdamas jūsų status_note; pavogto vieneto užregistruoti negalima. retired išjungia puslapį. Taip pat galima keisti batch ir manufactured_on.

Parametras	Tipas		Aprašymas
status	string		active, stolen, recalled arba retired.
status_note	string		Rodoma vieneto puslapyje, iki 500 simbolių.

Užklausa

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 reikalauja aftersales:read

Asmenys, užregistravę jūsų produktus: vardas, el. paštas, šalis, pirkimo data, mažmenininkas, garantijos datos ir ar jie sutiko gauti naujienas ir pasiūlymus (marketing_consent=1 išvardija tik juos). Pagal nutylėjimą aktyvios registracijos; status=pending, transferred arba ended kitoms; since= pakeitimams po datos.

Užklausa

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

GET /service-requests reikalauja aftersales:read

Remontai, garantiniai reikalavimai, grąžinimai, atsarginės dalys ir klausimai iš jūsų pasų, naujausi pirmiausia, su filtrais status ir type. GET /service-requests/{reference} prideda pokalbį.

Užklausa

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

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

Jūsų atsakymas siunčiamas klientui el. paštu su nuoroda į jo užklausos puslapį, jo kalba. internal: true prideda pastabą, kurią mato tik jūsų komanda. PATCH /service-requests/{reference} su būsena perkelia ją toliau (klientui pranešama, kai ji nagrinėjama, išspręsta arba uždaryta).

Parametras	Tipas		Aprašymas
body	string	privaloma	Atsakymas, iki 5000 simbolių.
internal	boolean		Pastaba jūsų komandai vietoj atsakymo.
status	string		new, in_progress, waiting, resolved arba closed.

Užklausa

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 / Galiniai taškaiMasinis redagavimas ir vaizdai

PATCH /products/bulk-fields reikalauja products:write

Nustato produkto duomenį arba paso lauką iki 5 000 produktų. mode yra set, fill (tik ten, kur tuščia) arba clear. Užklausoje atnaujinama iki 100 produktų; didesni rinkiniai įtraukiami į eilę (202).

Parametras	Tipas		Aprašymas
product_ids	array	privaloma
target	string	privaloma	product \| field
key	string	privaloma
value	string
mode	string		set \| fill \| clear

Užklausa

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

Atsakymas

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

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

Kelių dalių (multipart) JPG, PNG arba WebP įkėlimas (iki 15MB, iki 8 vienam produktui). Pirmasis vaizdas yra viešojo paso viršelio vaizdas.

Parametras	Tipas		Aprašymas
image	file	privaloma
alt	string		Vaizdo aprašymas.

Užklausa

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 reikalauja products:write

Pateikite image_ids norima tvarka; pirmasis tampa viršelio vaizdu.

Parametras	Tipas		Aprašymas
image_ids	array	privaloma

Užklausa

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} reikalauja products:write

Pašalinamas vaizdas ir jo failas.

Užklausa

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

18 / Galiniai taškaiWebhook

GET /webhooks reikalauja webhooks:manage

Jūsų darbo sričiai užregistruoti galiniai taškai. Paslapčių čia nėra; norėdami pamatyti paslaptį, gaukite vieną galinį tašką.

Užklausa

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

POST /webhooks reikalauja webhooks:manage

Užregistruoja viešą HTTPS URL vienam ar keliems įvykiams. Atsakyme pateikiama pasirašymo paslaptis. Privatūs ar vidiniai serveriai atmetami.

Parametras	Tipas		Aprašymas
url	string	privaloma
events	array	privaloma	Bet kuris iš toliau nurodytų įvykių.

Užklausa

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

Atsakymas

{
  "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} reikalauja webhooks:manage

Užklausa

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

PUT /webhooks/{id} reikalauja webhooks:manage

Pakeiskite URL arba įvykius, arba pristabdykite ir atnaujinkite galinį tašką. Atnaujinus nesėkmių skaičius nunulinamas; galinis taškas automatiškai pristabdomas po 10 nesėkmingų pristatymų iš eilės.

Parametras	Tipas		Aprašymas
url	string
events	array
is_active	boolean

Užklausa

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 reikalauja webhooks:manage

Įtraukia į eilę webhook.test pristatymą, kad galėtumėte patikrinti gavėją ir parašo kodą.

Užklausa

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

Atsakymas

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

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

Naujausi pristatymai, pradedant naujausiu, su jūsų galinio taško grąžinta HTTP būsena ir pirmaisiais 500 atsakymo simbolių.

Parametras	Tipas		Aprašymas
per_page	integer		Iki 100.

Užklausa

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

DELETE /webhooks/{id} reikalauja webhooks:manage

Užklausa

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

Atsakymas

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

19 / ĮvykiaiWebhook

Užuot kartotinai klausinėję, užregistruokite webhook galinį tašką programoje (puslapis Webhooks, prieinamas nuo „Starter“ plano) ir „MyProductPassport“ siųs JSON POST užklausa į jūsų URL, kai kas nors įvyksta:

Įvykis	Suveikia, kai
product.created	Sukuriamas produktas (programėlė, API arba CSV importas)
product.updated	Produktas atnaujinamas
product.deleted	Produktas ištrinamas
passport.created	Pasas sugeneruojamas
passport.published	Pasas paskelbiamas
passport.archived	Pasas archyvuojamas
supplier_request.submitted	Tiekėjas atsiunčia jūsų prašytą informaciją
owner.registered	Savininkas patvirtina savo registraciją
owner.transferred	Vienetas pereina naujam registruotam savininkui
service_request.created	Klientas iš paso išsiunčia aptarnavimo užklausą
service_request.updated	Aptarnavimo užklausa gauna atsakymą arba naują būseną
item.status_changed	Vienetas pažymimas kaip pavogtas, atšauktas arba išimtas iš apyvartos, arba žymė pašalinama
item.verification_failed	Saugios žymos nuskaitymas nepavyksta, kaupiasi neteisingi kodai arba serijos numeris pasirodo per daug vietų
webhook.test	Iš programėlės siunčiate bandomąjį pristatymą

Kiekvienas pristatymas yra JSON vokas: pristatymo ID (kartojant siunčiamas tas pats ID, todėl galite pašalinti dublikatus), įvykis, bandymo numeris, laiko žyma ir įvykio duomenys. Paso įvykiuose yra paso uuid ir viešas URL, todėl antros užklausos reikia retai:

Pristatymo turinys

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

Antraštėse yra įvykio pavadinimas, pristatymo ID, Unix laiko žyma ir neapdoroto turinio HMAC parašas, kad galėtumėte patikrinti, jog jis atėjo iš mūsų, ir atmesti pakartojimus:

Pristatymo antraštės

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>

Atsakykite bet kuriuo 2xx kodu per 10 sekundžių. Visa kita bandoma pakartoti penkis kartus per maždaug 90 minučių (30 s, 1 min., 5 min., 15 min., 1 val.); po 10 nesėkmių iš eilės galinis taškas pristabdomas, kol jį vėl įjungsite.

Patikrinti (PHP)

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

Slapukas	Tikslas	Galiojimo pabaiga
myproductpassport-session	Palaiko jūsų prisijungimą ir svetainės saugumą	2 valandos
XSRF-TOKEN	Apsaugo formas nuo tarpvietinių užklausų klastojimo	2 valandos
cookie_consent	Įsimena jūsų slapukų pasirinkimą	12 mėnesių
locale_suggested countdown_dismissed exit_intent_dismissed	Įsimena, kad uždarėte pranešimą, kad jis nebebūtų rodomas	Iki 30 dienų

Slapukas	Tikslas	Galiojimo pabaiga
_ga, _ga_*	Google Analytics: skaičiuoja apsilankymus ir rodo, kaip naudojama svetainė	2 metai
_gcl_au	Google Ads: matuoja, kurie skelbimai lemia registracijas	90 dienų
mpp_ref	Įsimena partnerį, kurio nuoroda pasinaudojote, kad jam būtų priskirta, jei užsiregistruosite vėliau	90 dienų

API žinynas

01 / PradžiaAutentifikavimas

02 / PradžiaUžklausų limitai

03 / PradžiaKlaidos

04 / PradžiaPuslapiavimas

05 / PradžiaDI asistento jungtis (MCP)

06 / Galiniai taškaiPaskyra

07 / Galiniai taškaiProduktai

08 / Galiniai taškaiPasai

09 / Galiniai taškaiAtitiktis

10 / Galiniai taškaiSektoriai

11 / Galiniai taškaiDokumentai

12 / Galiniai taškaiTiekimo grandinė

13 / Galiniai taškaiVertimai

14 / Galiniai taškaiVientisumas ir eksportas

15 / Galiniai taškaiTiekėjų prašymai

16 / Galiniai taškaiPo pardavimo

17 / Galiniai taškaiMasinis redagavimas ir vaizdai

18 / Galiniai taškaiWebhook

19 / ĮvykiaiWebhook

Prieš išeidami…

Esate sąraše!