Kehittäjät / REST API

API-viite

Kaikki MyProductPassportissa on käytettävissä avaimella todennetun REST API:n kautta: luo tuotteita, luo ja julkaise digitaalisia tuotepasseja, lähetä ajantasaisia akkutietoja ja tarkista vaatimustenmukaisuus suoraan ERP-, PIM- tai build-putkestasi.

v1 https://myproductpassport.eu/api/v1 Aloita ilmaiseksi OpenAPI-määrittely ↓

01 / AloittaminenTodennus

Jokainen pyyntö todennetaan Bearer-tunnuksena välitettävällä API-avaimella. Avaimet luodaan sovelluksen kohdassa API-avaimet, ne näytetään kerran ja tallennetaan tiivisteinä; jokaisella avaimella on omat käyttöoikeutensa, valinnainen sallittujen IP-osoitteiden luettelo ja valinnainen vanhenemispäivä. Avaimia voi vaihtaa ilman katkoja.

Pyynnön otsake

Authorization: Bearer pk_your_api_key

Kaikissa paketeissa. API-avaimia voi luoda ja käyttää kaikissa paketeissa, myös ilmaisessa. Paketti määrää, montako pyyntöä avain saa tehdä minuutissa (alla) ja montako tuotetta ja passia työtilassa voi olla.

Testitila. Testiavain (pk_test_...) suorittaa jokaisen kutsun täsmälleen kuten tuotantoavain, samalla validoinnilla, samoilla tunnisteilla ja samoilla vastauksilla, ja peruu sen sitten: mitään ei tallenneta, sähköposteja tai webhookeja ei lähetetä eikä tiedostoja säilytetä. Vastauksissa on "test_mode": true ja X-MPP-Mode: test -otsake. Rakenna ja testaa integraatio todellisilla tiedoillasi ja vaihda sitten tilalle tuotantoavain.

Käyttöoikeudet myönnetään avainkohtaisesti, joten integraatio saa vain sen, mitä tarvitsee:

Käyttöoikeus	Käyttöoikeudet
products:read	Tuotteiden luku
products:write	Tuotteiden luonti, päivitys ja poisto
passports:read	Passien luku
passports:write	Luo passit
passports:publish	Passien julkaisu ja arkistointi
webhooks:manage	Webhook-päätepisteiden luonti, testaus ja poisto
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 / AloittaminenPyyntörajat

Rajat ovat avainkohtaisia, minuuttikohtaisia ja paketin mukaisia:

Paketti	Pyyntöjä / minuutti
Ilmainen	30
Micro	60
Sähköinen etiketti	60
Starter	120
Professional	300
Business	600
Battery	600

Jokainen vastaus sisältää otsakkeet X-RateLimit-Limit ja X-RateLimit-Remaining. Rajan ylittäminen palauttaa 429:

429 Too Many Requests

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

03 / AloittaminenVirheet

Virheet ovat JSONia tavanomaisella tilakoodilla. Yleisimmät:

Tila	Merkitys	Esimerkkisisältö
401	Puuttuva, virheellinen, peruttu tai vanhentunut avain	`{"error": "Invalid or revoked API key."}`
403	Avaimelta puuttuu oikeus, IP-osoite ei ole sallittujen listalla tai paketin raja on täynnä	`{"message": "API key does not have 'products:write' permission."}`
404	Resurssia ei ole työtilassasi	`{"message": "Not found."}`
422	Vahvistus epäonnistui	`{"message": "…", "errors": {"gtin": ["…"]}}`
429	Pyyntöraja ylitetty	`{"error": "Rate limit exceeded."}`

04 / AloitusSivutus

Luettelopäätepisteet palauttavat 25 kohdetta sivua kohden vakio-objekteilla links ja meta. Käytä ?page=2 selataksesi kokoelmaa.

05 / AloittaminenTekoälyavustajan liitäntä (MCP)

Yhdistä Claude, Cursor tai mikä tahansa Model Context Protocolia tukeva avustaja ja pyydä sitä tavallisin sanoin luomaan tuotteita, täyttämään passeja kertomasi perusteella ja tarkistamaan, mitä vielä puuttuu. Se käyttää API-avainta tämän oikeuksin ja pyyntörajoin. Se voi luoda luonnoksia ja täyttää kenttiä; se ei koskaan julkaise, arkistoi tai poista mitään: ne jäävät sinulle sovelluksessa.

Palvelimen osoite (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 ja muut paikallisen palvelimen käynnistävät asiakasohjelmat

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

Sen tarjoamat työkalut:

Työkalu	Mitä se tekee
list_products	Työtilan tuotteet uusimmasta alkaen, 25 sivulla, toimialan ja uusimman passin kanssa.
get_product	Yksi tuote tietoineen, toimialoineen, säädösosioineen ja uusimpine passeineen.
list_sectors	Toimialamallit, joita tuote voi käyttää (tekstiilit, elektroniikka, akut, viini ja muut), tunnisteineen. Tuotteen toimiala ratkaisee, mitkä passin kentät ovat pakollisia.
create_product	Lisää tuotteen työtilaan. Käytä list_sectors-työkalun antamaa sector_id-arvoa. compliance_sections lisää passiin säädösosioita: gpsr, epr, france, chemicals, eudr.
list_passports	Työtilan passit uusimmasta alkaen, 25 sivulla, tilan (draft, published, archived), täydellisyysprosentin ja julkisen osoitteen kanssa.
get_passport	Yksi passi: tila, versio, täydellisyysprosentti, julkinen osoite ja QR-koodin linkit.
create_passport	Luo tuotteelle passiluonnoksen. Sitä ei julkaista: ihminen julkaisee sen sovelluksessa.
get_passport_fields	Mitä passi pyytää: pakollisten ja valinnaisten kenttien avaimet, kunkin merkitys (nimi, kuvaus, esimerkki), nykyiset arvot ja puuttuvat pakolliset kentät.
update_passport_fields	Kirjoittaa kenttien arvot luonnokseen tai julkaistuun passiin (julkaistu päivittyy paikallaan: sama osoite, sama QR-koodi). Avaimet get_passport_fields-työkalusta; tyhjä teksti poistaa arvon. Kirjoita vain tosiasioita, jotka käyttäjä tai hänen asiakirjansa kertovat.
get_compliance	Passin täydellisyys: prosentti, tila ja vielä puuttuvat pakolliset kentät.

Kokeile testiavaimella. Testiavaimella (pk_test_...) avustajan muutokset tarkistetaan ja perutaan, joten näet, mitä se tekisi, ennen kuin annat sille oikean avaimen.

06 / PäätepisteetTili

GET /me

Palauttaa todennetun tilin, sen tilaustason ja kuinka paljon tuotekiintiöstä on käytetty. Hyödyllinen yhteyden testaukseen.

Pyyntö

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

Vastaus

{
  "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 / PäätepisteetTuotteet

GET /products edellyttää products:read

Luettelee työtilasi tuotteet uusimmasta alkaen, 25 sivua kohden. Jokainen tuote sisältää toimialansa ja viimeisimmän passin yhteenvedon.

Parametri	Tyyppi		Kuvaus
page	integer		Sivunumero.

Pyyntö

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

Vastaus

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

Luo yhden tuotteen. Palauttaa 403, jos paketin tuotekiintiö on käytetty.

Parametri	Tyyppi		Kuvaus
name	string	pakollinen	Tuotteen nimi, enintään 255 merkkiä.
sku	string		Sisäinen SKU-koodisi, enintään 100 merkkiä.
gtin	string		GTIN-8, 12, 13 tai 14 (vain numeroita).
brand	string		Julkisessa passissa näkyvä brändi.
description	string		Enintään 2 000 merkkiä.
category	string		Vapaatekstinen luokka. Oletus "general".
sector_id	integer		Toimialan tunniste, joka valitsee passin kenttämallin.
country_of_origin	string		Maakoodi, esim. "PT".
weight	number		Nettopaino.
weight_unit	string		Yksi seuraavista: kg, g, lb, oz. Oletus kg.
materials	array		Objekteja {name, percentage 0-100}.
has_packaging	boolean		Lisää passiin pakkausmallin kentät (avaimet alkavat pkg_), saman QR-koodin taakse.

Pyyntö

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

Vastaus

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

Luo enintään 100 tuotetta yhdellä kutsulla. Koko erä hylätään koodilla 403, jos se ylittäisi jäljellä olevan tuotekiintiösi. Tuhansien tuotteiden luetteloissa kutsu tätä päätepistettä silmukassa tai käytä sovelluksen CSV-tuontia.

Parametri	Tyyppi		Kuvaus
products	array	pakollinen	1–100 tuoteobjektia samoilla kentillä kuin ”Luo tuote” (ilman materiaaleja).

Pyyntö

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

Vastaus

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

Palauttaa yhden tuotteen toimialoineen ja viimeisimmän passin yhteenvetoineen. 404, jos tunnus ei ole työtilassasi.

Pyyntö

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

PUT /products/{id} edellyttää products:write

Päivittää tuotteen osittain. Lähetä vain muutettavat kentät; kenttäluettelo on sama kuin kohdassa Luo tuote.

Pyyntö

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

Poistaa tuotteen palautettavasti. Tuotteen julkaistut passit toimivat edelleen, joten tulostetut QR-koodit eivät koskaan jää ilman sivua.

Pyyntö

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

Vastaus

{ "message": "Product deleted." }

08 / PäätepisteetPassit

GET /passports edellyttää passports:read

Luettelee passit uusimmasta alkaen, 25 sivua kohden, tuoteyhteenvedon ja kaikkien passikenttien kanssa.

Parametri	Tyyppi		Kuvaus
page	integer		Sivunumero.

Pyyntö

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

Vastaus

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

Luo tuotteelle passiluonnoksen ja esitäyttää kentät tuotetiedoista ja toimialamallista. Palauttaa luonnoksen vaatimustenmukaisuuspisteineen. Jos tuotteella on jo julkaistu passi, palautetaan 409 ja kyseinen passi: korjaa se pyynnöllä PUT /passports/{id}/fields, joka säilyttää sen osoitteen ja QR-koodin.

Pyyntö

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

GET /passports/{id} edellyttää passports:read

Palauttaa yhden passin tuotteen, kenttien, julkisen URL-osoitteen ja GS1 Digital Linkin kanssa.

Pyyntö

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

POST /passports/{id}/publish edellyttää passports:publish

Julkaisee passiluonnoksen, jolloin sen julkinen sivu ja QR-koodi otetaan käyttöön. Vain luonnoksia voi julkaista; muusta palautetaan 404.

Pyyntö

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

POST /passports/{id}/archive edellyttää passports:publish

Arkistoi passin ja poistaa sen julkisen sivun käytöstä.

Pyyntö

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

POST /passports/bulk-publish edellyttää passports:publish

Julkaisee enintään 50 passiluonnosta yhdellä kutsulla ja raportoi tulokset passeittain, joten yksi virhe ei koskaan keskeytä erää.

Parametri	Tyyppi		Kuvaus
passport_ids	array	pakollinen	1–50 passin tunnistetta.

Pyyntö

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

Vastaus

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

POST /passports/{id}/successor edellyttää passports:write

Uudelleenkäyttöön valmistellulle, uuteen käyttötarkoitukseen otetulle tai uudelleenvalmistetulle tuotteelle akkuasetus (77 artiklan 7 kohta) edellyttää uutta passia, joka on linkitetty alkuperäiseen. Tämä luo uuden tuotetietueen ja passiluonnoksen, joka on esitäytetty julkaistusta passista ja linkitetty siihen. Alkuperäinen pysyy käytössä ja molemmat passit näyttävät linkin. Julkaise uusi pyynnöllä POST /passports/{id}/publish.

Parametri	Tyyppi		Kuvaus
stage	string	pakollinen	prepared_for_reuse, repurposed tai remanufactured.

Pyyntö

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

Vastaus

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

Palauttaa kenttäavaimet, joita passin toimialamalli edellyttää (pakolliset ja valinnaiset), nykyiset arvot ja mitkä pakolliset avaimet vielä puuttuvat. Käytä sitä PUT /passports/{id}/fields -pyynnön sisällön kokoamiseen.

Pyyntö

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

Vastaus

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

Kirjoittaa minkä tahansa kenttäarvojen joukon luonnokseen tai julkaistuun passiin: akulle liitteen XIII koko joukon, toimialamallin kentät tai omat avaimesi. Lähetä vain avaimet, joita haluat muuttaa; null- tai tyhjä arvo poistaa kentän. Julkaistu passi päivitetään paikallaan, sen osoite ja QR-koodi eivät muutu, ja sen konekäännökset luodaan uudelleen. Vaatimustenmukaisuus pisteytetään uudelleen. Tämä kutsu ei julkaise luonnosta; käytä POST /passports/{id}/publish.

Parametri	Tyyppi		Kuvaus
fields	object	pakollinen	Kenttäavainten ja arvojen vastaavuus. Avaimet ovat pieniä kirjaimia, numeroita ja alaviivoja; arvot enintään 5 000 merkkiä. Enintään 200 avainta kutsua kohden.

Pyyntö

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

Vastaus

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

Lähettää tämän akun omat tiedot (asetuksen (EU) 2023/1542 liitteen XIII kohta 4) julkaistuun passiin BMS- ja kalustojärjestelmiä varten. Lähetä mikä tahansa osajoukko alla olevista kentistä; vaatimustenmukaisuus tarkistetaan päivityksen jälkeen uudelleen. Nämä arvot näytetään vain passin omistajan hyväksymille katsojille (77 artiklan 2 kohta), ei koskaan julkisella sivulla. capacity_fade, power_capability ja internal_resistance tallennetaan tämän akun nykyisinä lukemina (current_*), erillään mallin alkuperäisistä arvoista.

Parametri	Tyyppi	Kuvaus
state_of_health	string	esim. "97% 412 syklin kohdalla".
state_of_certified_energy	string	Jäljellä oleva sertifioitu energia (sähköajoneuvojen akut).
battery_status	string	original, repurposed, re-used, remanufactured tai waste.
capacity_fade	string	Tähänastinen kapasiteetin heikkeneminen. Tallennetaan nimellä current_capacity_fade.
power_capability	string	Nykyinen tehokapasiteetti. Tallennetaan nimellä current_power_capability.
internal_resistance	string	Mitattu sisäinen resistanssi. Tallennetaan nimellä current_internal_resistance.
use_data	string	Syklit, haitalliset tapahtumat, lämpötila ja varaustila, enintään 5 000 merkkiä.

Pyyntö

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

Vastaus

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

Jokainen akku tarvitsee oman passinsa (asetus (EU) 2023/1542, 77 artiklan 1 kohta). Rekisteröi enintään 10 000 saman mallin akkua yhdellä kutsulla, kukin omalla sarjanumerollaan (enintään 20 kirjainta, numeroa, pistettä, yhdysmerkkiä tai alaviivaa) ja valinnaisesti manufacturing_date, battery_status sekä liitteen XIII kohdan 4 tiedot. Olemassa olevat sarjanumerot päivitetään; pois jättämäsi arvot säilyvät. Jos tuotteella on GTIN, kunkin akun osoite on sen GS1 Digital Link, /01/{gtin}/21/{serial}. Kohdan 4 tiedot näytetään vain omistajan hyväksymille katsojille.

Parametri	Tyyppi		Kuvaus
units[].serial	string	pakollinen	Akun sarjanumero.
units[].manufacturing_date	string		Kuukausi ja vuosi, esim. "2026-09".
units[].battery_status	string		original tai waste. Tilan muutos edellyttää sen yhteydessä mitattuja arvoja (liite XIII, 4 kohdan a alakohta); waste edellyttää lisäksi kentät responsible_party_type (producer, pro tai waste_operator), responsible_party_name ja responsible_party_contact (77 artiklan 7 kohta). recycled yhdessä kenttien recycled_at ja recycler_name kanssa päättää passin (77 artiklan 8 kohta). Uuteen käyttötarkoitukseen otettu, uudelleenkäytetty tai uudelleenvalmistettu akku saa uuden passin: POST /passports/{id}/units/{serial}/successor.
units[].state_of_health	string		Lisäksi 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 ja use_data.

Pyyntö

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

Vastaus

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

PATCH /passports/{id}/units/{serial} edellyttää passports:write

Akunhallintajärjestelmälle, joka lähettää yhden akun tietoja: mikä tahansa seuraavista: battery_status, state_of_health, state_of_certified_energy, current_capacity_fade, current_power_capability, current_internal_resistance ja use_data. Lue tiedot GET-pyynnöllä samaan polkuun tai hae luettelo GET /passports/{id}/units (per_page enintään 500).

Pyyntö

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

Vastaus

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

Liitteen XIII 4 kohdan a alakohdassa edellytetään suorituskyky- ja kestävyysarvot silloin, kun akku saatetaan markkinoille ja kun sen tila muuttuu. Nämä lukemat säilytetään sellaisinaan, vaikka myöhemmin lähetettäisiin uusia arvoja; lähetä PATCH-pyynnössä record_snapshot: true, jos haluat säilyttää myös määräaikaisen lukeman.

Pyyntö

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

Vastaus

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

77 artiklan 7 kohta: akulla, joka on valmisteltu uudelleenkäyttöön, muutettu uuteen käyttötarkoitukseen tai uudelleenvalmistettu, on uusi passi, joka on linkitetty sen alkuperäisen akun passiin. Tämä rekisteröi akun uudelleen uudella sarjanumerolla ja tunnisteella työtilasi toisen elinkaaren akkumallin alle (joka luodaan tästä mallista, jos sellaista ei vielä ole), linkittää passit toisiinsa ja säilyttää muutoksen yhteydessä mitatut arvot. Alkuperäinen akku säilyttää passinsa. Täydennä ja julkaise toisen elinkaaren malli pyynnöllä POST /passports/{id}/publish.

Parametri	Tyyppi		Kuvaus
stage	string	pakollinen	prepared_for_reuse, repurposed tai remanufactured.
values	object	pakollinen	Tilan muutoksen yhteydessä mitatut arvot: vähintään yksi kustakin parista remaining_capacity_ah tai current_capacity_fade, current_power_capability tai power_fade ja current_internal_resistance tai internal_resistance_increase sekä expected_lifetime_cycles_remaining (liite IV, A osa).
serial	string		Uusi sarjanumero. Oletus: alkuperäinen sarjanumero ja pääte -RU, -RP tai -RM.
measured_at	string		Milloin arvot mitattiin.
member_state	string		Sen jäsenvaltion kaksikirjaiminen koodi, jossa kunto testattiin (73 artiklan 1 kohdan a alakohta).
target_passport_id	integer		Tämän akkumallin olemassa oleva toisen elinkaaren malli, jonka alle akku rekisteröidään.

Pyyntö

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

Vastaus

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

Tallentaa passiin EU:n DPP-rekisteriin tehdyn ilmoituksen ja sen tuloksen: tilan, korrelaatiotunnuksen, rekisterin palauttaman rekisteröintitunnisteen ja valinnaisen linkin DPP-palveluntarjoajan ylläpitämään varmuuskopioon. Itse rekisteröinti tehdään komission rekisterissä (verkkolomake tai tiedoston lataus); tämä pitää tuloksen passin yhteydessä. GET /passports/{id} palauttaa saman lohkon kentässä registry.

Parametri	Tyyppi	Kuvaus
status	string	not_submitted, submitted, registered tai failed.
product_group	string	Rekisterin tuoteryhmä, esimerkiksi batteries.
granularity	string	malli, erä tai yksittäinen tuote.
upi	string	Yksilöllinen tuotetunniste https-URL-osoitteena. Oletuksena julkisen passin URL.
correlation_id	string	Rekisterin lähetyksen yhteydessä antama korrelaatiotunnus.
uri	string	Rekisterin palauttama rekisteröintitunniste.
backup_url	string	https-linkki DPP-palveluntarjoajan isännöimään varmuuskopioon.
submitted_at	date	Ilmoituspäivä.
registered_at	date	Rekisteröintipäivä.
error	string	Epäonnistuneen lähetyksen virhekuvaus.

Pyyntö

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

Vastaus

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

Passin QR-koodi tiedostona: svg (oletus), png (brändätty, painovalmis) tai pdf (etikettiarkki).

Parametri	Tyyppi		Kuvaus
format	string		svg \| png \| pdf

Pyyntö

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

09 / PäätepisteetVaatimustenmukaisuus

GET /passports/{passportId}/compliance edellyttää passports:read

Suorittaa passille reaaliaikaisen vaatimustenmukaisuuden tarkistuksen sen toimialan pakollisia kenttiä vasten ja kertoo tarkasti, mitä puuttuu.

Pyyntö

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

Vastaus

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

10 / PäätepisteetToimialat

GET /sectors

Toimialat, joihin tuote voidaan luokitella: alustan järjestelmätoimialat sekä työtilasi määrittämät. Käytä id:tä tuotteita luodessasi ja kenttäavaimia passin kenttiä kirjoittaessasi.

Pyyntö

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

Vastaus

{
  "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 / PäätepisteetAsiakirjat

GET /products/{productId}/documents edellyttää products:read

Tuotteeseen liitetyt vaatimustenmukaisuusvakuutukset, testiraportit ja sertifikaatit. Julkinen asiakirja linkitetään tuotteen jokaisesta julkaistusta passista.

Pyyntö

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

Vastaus

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

Multipart-lataus. PDF, Word, Excel, CSV, teksti, PNG ja JPEG enintään 10 Mt, enintään 20 tuotetta kohden. Teksti poimitaan taustalla.

Parametri	Tyyppi		Kuvaus
file	file	pakollinen	Asiakirja.
is_public	boolean		Näytä julkisessa passissa (oletus false).

Pyyntö

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

Määrittää, linkitetäänkö asiakirja julkisesta passista.

Parametri	Tyyppi		Kuvaus
is_public	boolean	pakollinen

Pyyntö

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

Poistaa tiedoston ja sen linkin passiin.

Pyyntö

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

Vastaus

{ "message": "Document deleted." }

12 / PäätepisteetToimitusketju

GET /products/{productId}/supply-chain edellyttää products:read

Tuotteen passissa näytetyt vaiheet järjestyksessä.

Pyyntö

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

PUT /products/{productId}/supply-chain edellyttää products:write

Korvaa kaikki vaiheet lähettämälläsi luettelolla lähetetyssä järjestyksessä. Lähetä tyhjä luettelo tyhjentääksesi sen. Vaihetyypit: raw_material, processing, manufacturing, assembly, packaging, distribution.

Parametri	Tyyppi		Kuvaus
steps	array	pakollinen	Enintään 50 vaihetta.
steps[].step_type	string	pakollinen
steps[].supplier_name	string	pakollinen
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

Pyyntö

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 / PäätepisteetKäännökset

GET /passports/{id}/translations edellyttää passports:read

Jokainen käännetty kentän arvo kielittäin lähteineen: auto (konekäännös, luotu julkaisun yhteydessä) tai manual.

Pyyntö

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

Vastaus

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

PUT /passports/{id}/translations/{locale} edellyttää passports:write

Asettaa yhden kielen käännökset kenttäavaimittain. Käsin tehtyä käännöstä ei koskaan korvata konekäännöksellä. Poista käännös lähettämällä tyhjä merkkijono.

Parametri	Tyyppi		Kuvaus
fields	object	pakollinen	field_key: käännetty arvo

Pyyntö

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

Vastaus

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

14 / PäätepisteetEheys ja viennit

GET /passports/{id}/integrity edellyttää passports:read

Passin jokainen julkaistu tila hash-ketjutettuna, Ed25519-allekirjoitettuna tietueena: sormenjälki (SHA-256), ketjuarvo ja allekirjoitus. Julkiset avaimet ovat osoitteessa /.well-known/mpp-integrity-keys.json, joten kuka tahansa voi tarkistaa ketjun.

Pyyntö

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

Vastaus

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

Koko tietue sellaisena kuin se allekirjoitettiin, tilannevedos mukaan lukien: mitä passissa luki sillä hetkellä, aina jokaisen liitetyn tiedoston hashiin asti.

Pyyntö

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

GET /passports/{id}/epcis edellyttää passports:read

Passi GS1 EPCIS 2.0 JSON-LD -asiakirjana: tuotteen käyttöönotto, jokainen toimitusketjun vaihe havaintona, yksittäiset akut sekä toisen elinkaaren passi muunnoksena. Tunnisteet ovat GS1 Digital Link -URI-tunnisteita, kun tuotteella on GTIN.

Pyyntö

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

15 / PäätepisteetToimittajapyynnöt

POST /passports/{id}/supplier-requests edellyttää passports:write

Lähettää toimittajalle sähköpostitse yksityisen linkin valitsemiesi kenttien täyttämiseen tämän omalla kielellä. Mitään ei siirry passiin ennen kuin joku työtilasi jäsen hyväksyy sen.

Parametri	Tyyppi		Kuvaus
supplier_name	string	pakollinen
supplier_email	string	pakollinen
field_keys	array	pakollinen	Kenttäavaimet passin mallista.
locale	string		Sähköpostin ja lomakkeen kieli, esim. de.
due_at	date		Vastauksen määräpäivä; 14 päivää, jos se jätetään pois.
message	string

Pyyntö

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 edellyttää passports:read

Kaikki passia koskevat pyynnöt tiloineen.

Pyyntö

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

GET /supplier-requests/{id} edellyttää passports:read

Yksi pyyntö toimittajan vastauksineen, huomautuksineen ja liitettyjen tiedostojen nimineen.

Pyyntö

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

16 / PäätepisteetMyynnin jälkeiset palvelut

POST /passports/{id}/items edellyttää items:write

Anna tuotteen yksittäisille kappaleille (kaikki alat paitsi akut, jotka käyttävät /units) oma sarjanumero: kukin saa oman osoitteen ja QR-koodin, piilotetun aitouskoodin etikettiään varten, ja omistaja voi rekisteröidä sen. Lähetä enintään 10 000 tuotetta tai sarjanumeroväli. GTIN-koodin kanssa osoite on GS1 Digital Link /01/{gtin}/21/{serial}.

Parametri	Tyyppi		Kuvaus
items[].serial	string	pakollinen	Enintään 20 kirjainta, numeroa, pistettä, yhdysmerkkiä tai alaviivaa.
items[].batch	string		Erä, enintään 20 merkkiä.
items[].manufactured_on	string		Valmistuspäivä, VVVV-KK-PP.
range	object		items-kentän sijaan: prefix, start, count, digits ja batch, esimerkiksi sarjanumerot SN-00001 ... SN-00500.

Pyyntö

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

Vastaus

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

GET /passports/{id}/items/{serial} edellyttää items:read

Yksittäinen tuote ja sen osoite, tila, rekisteröintitieto, takuun päättymispäivä, aitoustarkistukset ja historia. Avain, jolla on items:write, saa myös piilokoodin tulostusta varten. GET /passports/{id}/items listaa ne (suodattimet status ja batch, per_page enintään 500).

Pyyntö

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

Vastaus

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

Aseta status arvoon stolen tai recalled, niin sen sivu varoittaa skannaajia status_note-tekstilläsi; varastettua tuotetta ei voi rekisteröidä. retired poistaa sivun käytöstä. Myös batch ja manufactured_on voidaan muuttaa.

Parametri	Tyyppi		Kuvaus
status	string		active, stolen, recalled tai retired.
status_note	string		Näytetään tuotteen sivulla, enintään 500 merkkiä.

Pyyntö

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 edellyttää aftersales:read

Tuotteitasi rekisteröineet henkilöt: nimi, sähköposti, maa, ostopäivä, jälleenmyyjä, takuupäivät ja suostumus uutisiin ja tarjouksiin (marketing_consent=1 listaa vain heidät). Oletuksena aktiiviset rekisteröinnit; status=pending, transferred tai ended muille; since= tietyn päivän jälkeisille muutoksille.

Pyyntö

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

GET /service-requests edellyttää aftersales:read

Korjaukset, takuuvaatimukset, palautukset, varaosat ja kysymykset passiesi kautta, uusimmat ensin, suodattimet status ja type. GET /service-requests/{reference} lisää keskustelun.

Pyyntö

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

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

Vastauksesi lähetetään asiakkaalle sähköpostitse hänen omalla kielellään, ja mukana on linkki hänen pyyntönsä sivulle. internal: true lisää muistiinpanon, jonka vain tiimisi näkee. PATCH /service-requests/{reference} uudella statuksella vie pyyntöä eteenpäin (asiakkaalle ilmoitetaan, kun se on käsittelyssä, ratkaistu tai suljettu).

Parametri	Tyyppi		Kuvaus
body	string	pakollinen	Vastaus, enintään 5 000 merkkiä.
internal	boolean		Muistiinpano tiimillesi vastauksen sijaan.
status	string		new, in_progress, waiting, resolved tai closed.

Pyyntö

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 / PäätepisteetJoukkomuokkaukset ja kuvat

PATCH /products/bulk-fields edellyttää products:write

Asettaa tuotetiedon tai passin kentän enintään 5 000 tuotteelle. mode on set, fill (vain tyhjiin) tai clear. Enintään 100 tuotetta päivitetään suoraan pyynnössä; suuremmat joukot asetetaan jonoon (202).

Parametri	Tyyppi		Kuvaus
product_ids	array	pakollinen
target	string	pakollinen	product \| field
key	string	pakollinen
value	string
mode	string		set \| fill \| clear

Pyyntö

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

Vastaus

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

POST /products/{id}/images edellyttää products:write

JPG-, PNG- tai WebP-kuvan multipart-lataus (enintään 15MB, 8 tuotetta kohden). Ensimmäinen kuva on julkisen passin kansikuva.

Parametri	Tyyppi		Kuvaus
image	file	pakollinen
alt	string		Kuvan kuvaus.

Pyyntö

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 edellyttää products:write

Anna image_ids haluamassasi järjestyksessä; ensimmäisestä tulee kansikuva.

Parametri	Tyyppi		Kuvaus
image_ids	array	pakollinen

Pyyntö

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

Poistaa kuvan ja sen tiedoston.

Pyyntö

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

18 / PäätepisteetWebhookit

GET /webhooks edellyttää webhooks:manage

Työtilaasi rekisteröidyt päätepisteet. Salaisuudet eivät ole tässä mukana; hae yksi päätepiste nähdäksesi sen salaisuuden.

Pyyntö

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

POST /webhooks edellyttää webhooks:manage

Rekisteröi julkisen HTTPS-URL-osoitteen yhdelle tai useammalle tapahtumalle. Vastaus sisältää allekirjoitussalaisuuden. Yksityiset tai sisäiset palvelimet hylätään.

Parametri	Tyyppi		Kuvaus
url	string	pakollinen
events	array	pakollinen	Mikä tahansa alla luetelluista tapahtumista.

Pyyntö

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

Vastaus

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

Pyyntö

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

PUT /webhooks/{id} edellyttää webhooks:manage

Muuta URL-osoitetta tai tapahtumia, tai keskeytä ja jatka päätepistettä. Jatkaminen nollaa virhelaskurin; päätepiste keskeytetään automaattisesti 10 peräkkäisen epäonnistuneen toimituksen jälkeen.

Parametri	Tyyppi		Kuvaus
url	string
events	array
is_active	boolean

Pyyntö

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 edellyttää webhooks:manage

Asettaa jonoon webhook.test-toimituksen, jotta voit tarkistaa vastaanottimesi ja allekirjoituskoodisi.

Pyyntö

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

Vastaus

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

GET /webhooks/{id}/deliveries edellyttää webhooks:manage

Viimeisimmät toimitukset uusimmasta alkaen, päätepisteesi palauttaman HTTP-tilan ja vastauksen 500 ensimmäisen merkin kanssa.

Parametri	Tyyppi		Kuvaus
per_page	integer		Enintään 100.

Pyyntö

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

DELETE /webhooks/{id} edellyttää webhooks:manage

Pyyntö

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

Vastaus

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

19 / TapahtumatWebhookit

Kyselyjen sijaan rekisteröi sovelluksessa webhook-päätepiste (Webhooks-sivu, saatavilla Starter-paketista alkaen), niin MyProductPassport lähettää JSONia POST-pyynnöllä URL-osoitteeseesi tapahtumien sattuessa:

Tapahtuma	Käynnistyy, kun
product.created	Tuote luodaan (sovellus, API tai CSV-tuonti)
product.updated	Tuote päivitetään
product.deleted	Tuote poistetaan
passport.created	Passi luodaan
passport.published	Passi julkaistaan
passport.archived	Passi arkistoidaan
supplier_request.submitted	Toimittaja lähettää pyytämäsi tiedot
owner.registered	Omistaja vahvistaa rekisteröintinsä
owner.transferred	Tuote siirtyy uudelle rekisteröidylle omistajalle
service_request.created	Asiakas lähettää palvelupyynnön passin kautta
service_request.updated	Palvelupyyntö saa vastauksen tai uuden tilan
item.status_changed	Tuote merkitään varastetuksi, takaisinvedetyksi tai käytöstä poistetuksi, tai merkintä poistetaan
item.verification_failed	Suojatun tagin lukeminen epäonnistuu, vääriä koodeja kertyy tai sarjanumero nähdään liian monessa paikassa
webhook.test	Lähetät testitoimituksen sovelluksesta

Jokainen toimitus on JSON-kirjekuori: toimitustunnus (sama tunnus lähetetään uudelleenyrityksissä, joten voit poistaa kaksoiskappaleet), tapahtuma, yrityksen numero, aikaleima ja tapahtuman tiedot. Passitapahtumat sisältävät passin uuid:n ja julkisen URL-osoitteen, joten toista pyyntöä tarvitaan harvoin:

Toimituksen sisältö

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

Otsakkeet sisältävät tapahtuman nimen, toimitustunnuksen, Unix-aikaleiman ja raakasisällön HMAC-allekirjoituksen, jotta voit varmistaa sen tulleen meiltä ja hylätä toistot:

Toimituksen otsakkeet

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>

Vastaa millä tahansa 2xx-koodilla 10 sekunnin kuluessa. Kaikki muu yritetään uudelleen viisi kertaa noin 90 minuutin aikana (30 s, 1 min, 5 min, 15 min, 1 h); 10 peräkkäisen epäonnistumisen jälkeen päätepiste keskeytetään, kunnes otat sen uudelleen käyttöön.

Todenna (PHP)

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

Eväste	Tarkoitus	Vanheneminen
myproductpassport-session	Pitää sinut kirjautuneena ja sivuston turvallisena	2 tuntia
XSRF-TOKEN	Suojaa lomakkeita sivustojen väliseltä pyyntöjen väärentämiseltä	2 tuntia
cookie_consent	Muistaa evästevalintasi	12 kuukautta
locale_suggested countdown_dismissed exit_intent_dismissed	Muistaa, että suljit viestin, jotta sitä ei näytetä uudelleen	Enintään 30 päivää

Eväste	Tarkoitus	Vanheneminen
_ga, _ga_*	Google Analytics: laskee käynnit ja näyttää, miten sivustoa käytetään	2 vuotta
_gcl_au	Google Ads: mittaa, mitkä mainokset johtavat rekisteröitymisiin	90 päivää
mpp_ref	Muistaa kumppanin, jonka linkkiä seurasit, jotta se hyvitetään, jos rekisteröidyt myöhemmin	90 päivää

API-viite

01 / AloittaminenTodennus

02 / AloittaminenPyyntörajat

03 / AloittaminenVirheet

04 / AloitusSivutus

05 / AloittaminenTekoälyavustajan liitäntä (MCP)

06 / PäätepisteetTili

07 / PäätepisteetTuotteet

08 / PäätepisteetPassit

09 / PäätepisteetVaatimustenmukaisuus

10 / PäätepisteetToimialat

11 / PäätepisteetAsiakirjat

12 / PäätepisteetToimitusketju

13 / PäätepisteetKäännökset

14 / PäätepisteetEheys ja viennit

15 / PäätepisteetToimittajapyynnöt

16 / PäätepisteetMyynnin jälkeiset palvelut

17 / PäätepisteetJoukkomuokkaukset ja kuvat

18 / PäätepisteetWebhookit

19 / TapahtumatWebhookit

Ennen kuin lähdet…

Olet listalla!