Żviluppaturi / REST API

Referenza tal-API

Kollox f'MyProductPassport huwa disponibbli permezz ta' REST API awtentikat b'key: oħloq prodotti, iġġenera u ippubblika Passaporti Diġitali tal-Prodotti, ibgħat data tal-batteriji live, u iċċekkja l-konformità, direttament mill-ERP, il-PIM jew il-build pipeline tiegħek.

v1 https://myproductpassport.eu/api/v1 Ibda b'xejn Speċifikazzjoni OpenAPI ↓

01 / Kif tibdaAwtentikazzjoni

Kull talba hija awtentikata b'key tal-API mgħoddija bħala Bearer token. Il-keys jinħolqu fl-app taħt API Keys, jintwerew darba u jinħażnu hashed; kull key għandha s-sett ta' permessi tagħha, lista ta' IPs permessi fakultattiva u data ta' skadenza fakultattiva. Il-keys jistgħu jinbidlu mingħajr waqfien.

Intestatura tat-talba

Authorization: Bearer pk_your_api_key

Fuq kull pjan. Iċ-ċwievet tal-API jistgħu jinħolqu u jintużaw fuq kull pjan, inkluż dak b'xejn. Il-pjan jiddeċiedi kemm-il talba fil-minuta tista' tagħmel ċavetta (hawn taħt) u kemm-il prodott u passaport jista' jkollu l-ispazju tax-xogħol.

Modalità tat-test. Ċavetta tat-test (pk_test_...) tmexxi kull sejħa eżattament kif tagħmel ċavetta live, bl-istess validazzjoni, IDs u risposti, u mbagħad treġġagħha lura: xejn ma jiġi ssejvjat, ma tintbagħat l-ebda email jew webhook u ma jinżamm l-ebda fajl. Ir-risposti jkollhom "test_mode": true u header X-MPP-Mode: test. Ibni u ittestja integrazzjoni mad-data reali tiegħek, imbagħad daħħal ċavetta live minflokha.

Il-permessi jingħataw għal kull key, għalhekk integrazzjoni tieħu biss dak li għandha bżonn:

Permess	Aċċessi mogħtija
products:read	Aqra l-prodotti
products:write	Oħloq, aġġorna u ħassar il-prodotti
passports:read	Aqra l-passaporti
passports:write	Iġġenera passaporti
passports:publish	Ippubblika u arkivja l-passaporti
webhooks:manage	Oħloq, ittestja u neħħi l-endpoints tal-webhooks
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 / Kif tibdaLimiti tar-rata

Il-limiti huma għal kull key, għal kull minuta, u jiddependu mill-pjan:

Pjan	Talbiet / minuta
B'xejn	30
Micro	60
E-Tikketta	60
Starter	120
Professional	300
Business	600
Battery	600

Kull tweġiba ġġorr l-intestaturi X-RateLimit-Limit u X-RateLimit-Remaining. Jekk taqbeż il-limitu jirritorna 429:

429 Too Many Requests

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

03 / Kif tibdaŻbalji

L-iżbalji huma JSON b'kodiċi tal-istatus konvenzjonali. L-aktar komuni:

Status	Tifsira	Korp ta' eżempju
401	Key nieqsa, invalida, revokata jew skaduta	`{"error": "Invalid or revoked API key."}`
403	Iċ-ċavetta m'għandhiex permess, l-IP mhix fil-lista permessa, jew intlaħaq il-limitu tal-pjan	`{"message": "API key does not have 'products:write' permission."}`
404	Ir-riżors ma jeżistix fl-ispazju tax-xogħol tiegħek	`{"message": "Not found."}`
422	Il-validazzjoni falliet	`{"message": "…", "errors": {"gtin": ["…"]}}`
429	Inqabeż il-limitu tar-rata	`{"error": "Rate limit exceeded."}`

04 / Kif tibdaPaġinazzjoni

L-endpoints tal-listi jirritornaw 25 oġġett għal kull paġna bl-oġġetti standard links u meta. Għaddi ?page=2 biex tiċċaqlaq fil-ġabra.

05 / Kif tibdaKonnettur għall-assistent tal-IA (MCP)

Qabbad lil Claude, Cursor jew kull assistent li jitkellem il-Model Context Protocol, u itlobu bi kliem sempliċi biex joħloq prodotti, jimla passaporti b'dak li tgħidlu u jiċċekkja x'għad fadal. Juża ċavetta tal-API bil-permessi u l-limitu ta' talbiet tagħha. Jista' joħloq abbozzi u jimla oqsma; qatt ma jippubblika, jarkivja jew iħassar xejn: dawn jibqgħu għandek fl-app.

Indirizz tas-server (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 u klijenti oħra li jibdew server lokali

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

L-għodod li joffri:

Għodda	X'jagħmel
list_products	Il-prodotti tal-ispazju tax-xogħol, l-aktar ġodda l-ewwel, 25 kull paġna, bis-settur u l-aħħar passaport.
get_product	Prodott wieħed bid-dettalji, is-settur, it-taqsimiet regolatorji u l-aħħar passaport.
list_sectors	Il-mudelli tas-setturi li prodott jista' juża (tessuti, elettronika, batteriji, inbid u aktar), bl-ID tagħhom. Is-settur ta' prodott jiddeċiedi liema oqsma tal-passaport huma obbligatorji.
create_product	Iżid prodott mal-ispazju tax-xogħol. Uża sector_id minn list_sectors. compliance_sections iżid taqsimiet regolatorji mal-passaport: gpsr, epr, france, chemicals, eudr.
list_passports	Il-passaporti tal-ispazju tax-xogħol, l-aktar ġodda l-ewwel, 25 kull paġna, bl-istatus (draft, published, archived), il-perċentwal ta' kompletezza u l-indirizz pubbliku.
get_passport	Passaport wieħed: status, verżjoni, perċentwal ta' kompletezza, indirizz pubbliku u links tal-kodiċi QR.
create_passport	Joħloq abbozz ta' passaport għal prodott. Ma jiġix ippubblikat: jippubblikah bniedem fl-app.
get_passport_fields	X'jitlob passaport: iċ-ċwievet tal-oqsma obbligatorji u fakultattivi, xi jfisser kull wieħed (tikketta, deskrizzjoni, eżempju), il-valuri li għandu u liema obbligatorji neqsin.
update_passport_fields	Jikteb valuri tal-oqsma f'abbozz jew f'passaport ippubblikat (wieħed ippubblikat jiġi aġġornat f'postu: l-istess indirizz, l-istess kodiċi QR). Ċwievet minn get_passport_fields; test vojt ineħħi valur. Ikteb biss fatti li jgħidu l-utent jew id-dokumenti tiegħu.
get_compliance	Il-kompletezza ta' passaport: perċentwal, status u l-oqsma obbligatorji li għadhom neqsin.

Ipprovah b'ċavetta tat-test. B'ċavetta tat-test (pk_test_...) il-bidliet tal-assistent jiġu ċċekkjati u mbagħad imħassra, biex tara x'jagħmel qabel ma tagħtih ċavetta vera.

06 / EndpointsKont

GET /me

Jirritorna l-kont awtentikat, il-livell tal-abbonament tiegħu, u kemm intuża mil-limitu tal-prodotti. Utli bħala kontroll tal-konnessjoni.

Talba

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

Tweġiba

{
  "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 / EndpointsProdotti

GET /products jeħtieġ products:read

Jelenka l-prodotti fl-ispazju tax-xogħol tiegħek, l-aktar ġodda l-ewwel, 25 għal kull paġna. Kull prodott jinkludi s-settur tiegħu u sommarju tal-aħħar passaport.

Parametru	Tip		Deskrizzjoni
page	integer		Numru tal-paġna.

Talba

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

Tweġiba

{
  "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 jeħtieġ products:write

Joħloq prodott wieħed. Jirritorna 403 jekk il-limitu tal-prodotti tal-pjan ikun intuża.

Parametru	Tip		Deskrizzjoni
name	string	meħtieġ	Isem il-prodott, sa 255 karattru.
sku	string		L-SKU intern tiegħek, sa 100 karattru.
gtin	string		GTIN-8, 12, 13 jew 14 (ċifri biss).
brand	string		Il-marka murija fuq il-passaport pubbliku.
description	string		Sa 2,000 karattru.
category	string		Kategorija b'test ħieles. Default "general".
sector_id	integer		ID tas-settur, li jagħżel il-mudell tal-oqsma tal-passaport.
country_of_origin	string		Kodiċi tal-pajjiż, eż. "PT".
weight	number		Piż nett.
weight_unit	string		Wieħed minn kg, g, lb, oz. Default kg.
materials	array		Oġġetti ta' {name, percentage 0-100}.
has_packaging	boolean		Iżżid mal-passaport il-kampi tal-mudell tal-ippakkjar (ċwievet li jibdew b' pkg_), taħt l-istess kodiċi QR.

Talba

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

Tweġiba

{
  "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 jeħtieġ products:write

Joħloq sa 100 prodott f'sejħa waħda. Il-lott kollu jiġi rrifjutat b'403 jekk jaqbeż il-limitu tal-prodotti li fadallek. Għal katalogi b'eluf ta' prodotti, sejjaħ dan l-endpoint f'loop jew uża l-importazzjoni CSV fl-app.

Parametru	Tip		Deskrizzjoni
products	array	meħtieġ	Minn 1 sa 100 oġġett tal-prodott bl-istess oqsma bħal Oħloq prodott (mingħajr materjali).

Talba

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

Tweġiba

{
  "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} jeħtieġ products:read

Jirritorna prodott wieħed bis-settur tiegħu u sommarju tal-aħħar passaport. 404 jekk l-id mhux fl-ispazju tax-xogħol tiegħek.

Talba

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

PUT /products/{id} jeħtieġ products:write

Jaġġorna prodott parzjalment. Ibgħat biss l-oqsma li trid tibdel; il-lista tal-oqsma hija l-istess bħal Oħloq prodott.

Talba

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} jeħtieġ products:write

Iħassar prodott b'mod li jista' jiġi rkuprat. Il-passaporti ppubblikati tal-prodott jibqgħu jaħdmu, għalhekk il-kodiċijiet QR stampati qatt ma jibqgħu mingħajr paġna.

Talba

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

Tweġiba

{ "message": "Product deleted." }

08 / EndpointsPassaporti

GET /passports jeħtieġ passports:read

Jelenka l-passaporti, l-aktar ġodda l-ewwel, 25 għal kull paġna, b'sommarju tal-prodott u l-oqsma kollha tal-passaport.

Parametru	Tip		Deskrizzjoni
page	integer		Numru tal-paġna.

Talba

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

Tweġiba

{
  "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 jeħtieġ passports:write

Jiġġenera abbozz ta' passaport għal prodott, billi jimla minn qabel l-oqsma mid-data tal-prodott u l-mudell tas-settur. Jirritorna l-abbozz bil-punteġġ tal-konformità tiegħu. Prodott li diġà għandu passaport attiv jirritorna 409 b'dak il-passaport: ikkoreġih b'PUT /passports/{id}/fields, li jżomm l-indirizz u l-kodiċi QR tiegħu.

Talba

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

GET /passports/{id} jeħtieġ passports:read

Jirritorna passaport wieħed bil-prodott, l-oqsma, l-URL pubbliku u l-GS1 Digital Link.

Talba

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

POST /passports/{id}/publish jeħtieġ passports:publish

Jippubblika abbozz ta' passaport, u jattiva l-paġna pubblika u l-kodiċi QR tiegħu. Abbozzi biss jistgħu jiġu ppubblikati; kull ħaġa oħra tirritorna 404.

Talba

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

POST /passports/{id}/archive jeħtieġ passports:publish

Jarkivja passaport u jneħħi l-paġna pubblika tiegħu miċ-ċirkolazzjoni.

Talba

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

POST /passports/bulk-publish jeħtieġ passports:publish

Jippubblika sa 50 abbozz ta' passaport f'sejħa waħda u jirrapporta r-riżultati għal kull passaport, għalhekk falliment wieħed qatt ma jwaqqaf il-lott.

Parametru	Tip		Deskrizzjoni
passport_ids	array	meħtieġ	Minn 1 sa 50 ID tal-passaport.

Talba

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

Tweġiba

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

POST /passports/{id}/successor jeħtieġ passports:write

Għal prodott li ġie ppreparat għall-użu mill-ġdid, adattat għal skop ieħor jew immanifatturat mill-ġdid, ir-Regolament dwar il-Batteriji (Artikolu 77(7)) jeħtieġ passaport ġdid marbut mal-oriġinali. Dan joħloq rekord ġdid tal-prodott u abbozz ta' passaport mimli minn qabel mill-wieħed ippubblikat, marbut miegħu. L-oriġinali jibqa' attiv u ż-żewġ passaporti juru l-link. Ippubblika l-ġdid b'POST /passports/{id}/publish.

Parametru	Tip		Deskrizzjoni
stage	string	meħtieġ	prepared_for_reuse, repurposed jew remanufactured.

Talba

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

Tweġiba

{
  "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 jeħtieġ passports:read

Jirritorna l-keys tal-oqsma li jitlob il-mudell tas-settur tal-passaport (meħtieġa u fakultattivi), il-valuri attwali, u liema keys meħtieġa għadhom neqsin. Użah biex tibni l-payload għal PUT /passports/{id}/fields.

Talba

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

Tweġiba

{
  "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 jeħtieġ passports:write

Jikteb kwalunkwe sett ta' valuri tal-kampi fuq passaport abbozz jew live: is-sett sħiħ tal-Anness XIII għal batterija, il-kampi ta' mudell ta' settur, jew iċ-ċwievet tiegħek. Ibgħat biss iċ-ċwievet li trid tibdel; valur null jew vojt ineħħi dak il-qasam. Passaport live jiġi aġġornat f'postu, l-indirizz u l-kodiċi QR tiegħu ma jinbidlux, u t-traduzzjonijiet awtomatiċi tiegħu jiġu ġġenerati mill-ġdid. Il-konformità terġa' tiġi evalwata. Abbozz ma jiġix ippubblikat b'din is-sejħa; uża POST /passports/{id}/publish.

Parametru	Tip		Deskrizzjoni
fields	object	meħtieġ	Mappa minn key tal-qasam għal valur. Il-keys huma ittri żgħar, ċifri u underscores; valuri sa 5,000 karattru. Sa 200 key għal kull sejħa.

Talba

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

Tweġiba

{
  "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 jeħtieġ passports:write

Jibgħat id-data ta' din il-batterija (punt 4 tal-Anness XIII tar-Regolament (UE) 2023/1542) fuq passaport ippubblikat, għal sistemi BMS u tal-flotot. Ibgħat kwalunkwe subsett tal-oqsma hawn taħt; il-konformità terġa' tiġi ċċekkjata wara l-aġġornament. Dawn il-valuri jintwerew biss lil viżitaturi approvati mis-sid tal-passaport (Artikolu 77(2)), qatt fuq il-paġna pubblika. capacity_fade, power_capability u internal_resistance jinħażnu bħala l-qari attwali ta' din il-batterija (current_*), separati mill-valuri oriġinali tal-mudell.

Parametru	Tip	Deskrizzjoni
state_of_health	string	eż. "97% f'412-il ċiklu".
state_of_certified_energy	string	Enerġija ċertifikata li fadal (batteriji tal-EV).
battery_status	string	original, repurposed, re-used, remanufactured jew waste.
capacity_fade	string	It-tnaqqis fil-kapaċità s'issa. Maħżun bħala current_capacity_fade.
power_capability	string	Kapaċità tal-enerġija attwali. Maħżuna bħala current_power_capability.
internal_resistance	string	Reżistenza interna mkejla. Maħżuna bħala current_internal_resistance.
use_data	string	Ċikli, avvenimenti negattivi, temperatura u stat tal-iċċarġjar, sa 5,000 karattru.

Talba

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

Tweġiba

{
  "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 jeħtieġ passports:write

Kull batterija teħtieġ il-passaport tagħha (Regolament (UE) 2023/1542, Artikolu 77(1)). Irreġistra sa 10,000 batterija ta' mudell ta' batterija f'sejħa waħda, kull waħda bin-numru tas-serje tagħha (sa 20 ittra, ċifra, tikka, sing jew underscore), u b'mod fakultattiv manufacturing_date, battery_status u d-data tagħha tal-punt 4 tal-Anness XIII. In-numri tas-serje eżistenti jiġu aġġornati; il-valuri li tħalli barra jinżammu. B'GTIN fuq il-prodott, l-indirizz ta' kull batterija huwa l-GS1 Digital Link tagħha, /01/{gtin}/21/{serial}. Id-data tal-punt 4 tintwera biss lil spettaturi li s-sid japprova.

Parametru	Tip		Deskrizzjoni
units[].serial	string	meħtieġ	In-numru tas-serje tal-batterija.
units[].manufacturing_date	string		Xahar u sena, eż. "2026-09".
units[].battery_status	string		original jew waste. Bidla fl-istatus teħtieġ il-valuri mkejla fiha (Anness XIII 4(a)); waste jeħtieġ ukoll responsible_party_type (producer, pro jew waste_operator), responsible_party_name u responsible_party_contact (Artikolu 77(7)). recycled, flimkien ma' recycled_at u recycler_name, itemm il-passaport (Artikolu 77(8)). Batterija adattata għal użu ieħor, użata mill-ġdid jew immanifatturata mill-ġdid tieħu passaport ġdid: POST /passports/{id}/units/{serial}/successor.
units[].state_of_health	string		Ukoll 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 u use_data.

Talba

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

Tweġiba

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

PATCH /passports/{id}/units/{serial} jeħtieġ passports:write

Għal sistema tal-ġestjoni tal-batterija li tibgħat id-data ta' batterija waħda: kwalunkwe wieħed minn battery_status, state_of_health, state_of_certified_energy, current_capacity_fade, current_power_capability, current_internal_resistance u use_data. Uża GET fuq l-istess path biex taqrah, jew GET /passports/{id}/units għal-lista (per_page sa 500).

Talba

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

Tweġiba

{
  "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 jeħtieġ passports:read

L-Anness XIII, punt 4(a) jitlob il-valuri tal-prestazzjoni u tad-durabbiltà meta l-batterija titqiegħed fis-suq u meta jinbidel l-istatus tagħha. Dak il-qari jinżamm kif kien, ikun x'ikun li jintbagħat wara; ibgħat record_snapshot: true ma' PATCH biex iżżomm ukoll qari perjodiku.

Talba

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

Tweġiba

{
  "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 jeħtieġ passports:write

Artikolu 77(7): batterija li tkun ġiet ippreparata għall-użu mill-ġdid, adattata għal użu ieħor jew immanifatturata mill-ġdid ikollha passaport ġdid marbut mal-oriġinali tagħha. Dan jirreġistra l-batterija mill-ġdid, b'numru tas-serje u identifikatur ġodda, taħt mudell ta' batterija tat-tieni ħajja tal-ispazju tax-xogħol tiegħek (magħmul minn dan il-mudell jekk għad m'hemmx wieħed), jorbot it-tnejn u jżomm il-valuri mkejla fil-mument tal-bidla. Il-batterija oriġinali żżomm il-passaport tagħha. Ikkompleta u ppubblika l-mudell tat-tieni ħajja b'POST /passports/{id}/publish.

Parametru	Tip		Deskrizzjoni
stage	string	meħtieġ	prepared_for_reuse, repurposed jew remanufactured.
values	object	meħtieġ	Il-valuri mkejla fil-bidla: mill-inqas wieħed minn remaining_capacity_ah jew current_capacity_fade, wieħed minn current_power_capability jew power_fade, wieħed minn current_internal_resistance jew internal_resistance_increase, u expected_lifetime_cycles_remaining (Anness IV, Parti A).
serial	string		In-numru tas-serje l-ġdid. Standard: in-numru tas-serje oriġinali flimkien ma' -RU, -RP jew -RM.
measured_at	string		Meta tkejlu l-valuri.
member_state	string		Kodiċi ta' żewġ ittri tal-Istat Membru fejn ġie ttestjat l-istat tas-saħħa (Artikolu 73(1), punt (a)).
target_passport_id	integer		Mudell tat-tieni ħajja eżistenti ta' dan il-mudell tal-batterija li taħtu tiġi rreġistrata.

Talba

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

Tweġiba

{
  "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 jeħtieġ passports:write

Jaħżen fuq passaport is-sottomissjoni lir-Reġistru DPP tal-UE u r-riżultat tagħha: status, ID ta' korrelazzjoni, l-identifikatur tar-reġistrazzjoni li jirritorna r-Reġistru, u link fakultattiv għal kopja ta' riżerva ospitata minn fornitur tas-servizz DPP. Ir-reġistrazzjoni nnifisha ssir fir-Reġistru tal-Kummissjoni (formola web jew upload ta' fajl); dan iżomm ir-riżultat mal-passaport. GET /passports/{id} jirritorna l-istess blokk taħt registry.

Parametru	Tip	Deskrizzjoni
status	string	not_submitted, submitted, registered jew failed.
product_group	string	Grupp ta' prodotti tar-Reġistru, pereżempju batteries.
granularity	string	mudell, lott jew oġġett.
upi	string	Identifikatur uniku tal-prodott bħala URL https. Id-default huwa l-URL tal-passaport pubbliku.
correlation_id	string	ID ta' korrelazzjoni assenjat mir-Reġistru mas-sottomissjoni.
uri	string	Identifikatur tar-reġistrazzjoni rritornat mir-Reġistru.
backup_url	string	Link https għall-kopja backup hostjata minn fornitur tas-servizzi DPP.
submitted_at	date	Data tas-sottomissjoni.
registered_at	date	Data tar-reġistrazzjoni.
error	string	Deskrizzjoni tal-iżball għal sottomissjoni li falliet.

Talba

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

Tweġiba

{
  "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 jeħtieġ passports:read

Il-kodiċi QR tal-passaport bħala fajl: svg (default), png (bil-marka, lest għall-istampar) jew pdf (folja tat-tikketti).

Parametru	Tip		Deskrizzjoni
format	string		svg \| png \| pdf

Talba

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

09 / EndpointsKonformità

GET /passports/{passportId}/compliance jeħtieġ passports:read

Iwettaq kontroll tal-konformità live ta' passaport mal-oqsma meħtieġa tas-settur tiegħu u jirrapporta eżattament x'hemm nieqes.

Talba

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

Tweġiba

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

10 / EndpointsSetturi

GET /sectors

Is-setturi li taħthom jista' jiġi ppreżentat prodott: is-setturi tas-sistema tal-pjattaforma flimkien ma' dawk definiti mill-ispazju tax-xogħol tiegħek. Uża l-id meta toħloq prodotti, u ċ-ċwievet tal-kampi meta tikteb il-kampi tal-passaport.

Talba

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

Tweġiba

{
  "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 / EndpointsDokumenti

GET /products/{productId}/documents jeħtieġ products:read

Dikjarazzjonijiet ta' konformità, rapporti tat-testijiet u ċertifikati mehmuża mal-prodott. Dokument pubbliku huwa marbut minn kull passaport ippubblikat tal-prodott.

Talba

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

Tweġiba

{
  "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 jeħtieġ products:write

Upload multipart. PDF, Word, Excel, CSV, test, PNG u JPEG sa 10 MB, massimu ta' 20 għal kull prodott. It-test jiġi estratt fl-isfond.

Parametru	Tip		Deskrizzjoni
file	file	meħtieġ	Id-dokument.
is_public	boolean		Urih fuq il-passaport pubbliku (default false).

Talba

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} jeħtieġ products:write

Jiddeċiedi jekk id-dokument huwiex marbut mill-passaport pubbliku.

Parametru	Tip		Deskrizzjoni
is_public	boolean	meħtieġ

Talba

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} jeħtieġ products:write

Ineħħi l-fajl u l-link tiegħu mal-passaport.

Talba

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

Tweġiba

{ "message": "Document deleted." }

12 / EndpointsKatina tal-provvista

GET /products/{productId}/supply-chain jeħtieġ products:read

Il-passi murija fuq il-passaport tal-prodott, f'ordni.

Talba

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

PUT /products/{productId}/supply-chain jeħtieġ products:write

Jissostitwixxi kull pass bil-lista li tibgħat, fl-ordni li tintbagħat. Ibgħat lista vojta biex tbattalha. Tipi ta' pass: raw_material, processing, manufacturing, assembly, packaging, distribution.

Parametru	Tip		Deskrizzjoni
steps	array	meħtieġ	Sa 50 pass.
steps[].step_type	string	meħtieġ
steps[].supplier_name	string	meħtieġ
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

Talba

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 / EndpointsTraduzzjonijiet

GET /passports/{id}/translations jeħtieġ passports:read

Kull valur ta' qasam tradott skont il-lingwa, bis-sors tiegħu: auto (magna, magħmul mal-pubblikazzjoni) jew manual.

Talba

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

Tweġiba

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

PUT /passports/{id}/translations/{locale} jeħtieġ passports:write

Jissettja t-traduzzjonijiet għal lingwa waħda skont iċ-ċavetta tal-qasam. Traduzzjoni manwali qatt ma tinkiteb fuqha b'waħda awtomatika. Ibgħat string vojt biex tneħħi waħda.

Parametru	Tip		Deskrizzjoni
fields	object	meħtieġ	field_key: valur tradott

Talba

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

Tweġiba

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

14 / EndpointsIntegrità u esportazzjonijiet

GET /passports/{id}/integrity jeħtieġ passports:read

Kull stat ippubblikat tal-passaport bħala rekord marbut f'katina ta' hash u ffirmat b'Ed25519: impronta diġitali (SHA-256), valur tal-katina u firma. Iċ-ċwievet pubbliċi jinsabu f'/.well-known/mpp-integrity-keys.json, għalhekk kulħadd jista' jivverifika l-katina.

Talba

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

Tweġiba

{ "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} jeħtieġ passports:read

Ir-rekord sħiħ kif ġie ffirmat, inkluż is-snapshot: dak li kien jgħid il-passaport f'dak il-mument, sal-hash ta' kull fajl mehmuż.

Talba

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

GET /passports/{id}/epcis jeħtieġ passports:read

Il-passaport bħala dokument JSON-LD GS1 EPCIS 2.0: l-oġġett ikkummissjonat, kull pass tal-katina tal-provvista bħala osservazzjoni, il-batteriji individwali, u passaport tat-tieni ħajja bħala trasformazzjoni. L-identifikaturi huma URIs tal-GS1 Digital Link meta l-prodott ikollu GTIN.

Talba

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

15 / EndpointsTalbiet lill-fornituri

POST /passports/{id}/supplier-requests jeħtieġ passports:write

Jibgħat email lil fornitur b'link privat biex jimla l-oqsma li tagħżel, bil-lingwa tiegħu. Xejn ma jasal fil-passaport qabel ma xi ħadd fl-ispazju tax-xogħol tiegħek japprovah.

Parametru	Tip		Deskrizzjoni
supplier_name	string	meħtieġ
supplier_email	string	meħtieġ
field_keys	array	meħtieġ	Keys tal-oqsma mill-mudell tal-passaport.
locale	string		Il-lingwa tal-email u tal-formola, eż. de.
due_at	date		Id-data sa meta trid tasal it-tweġiba; 14-il jum jekk titħalla barra.
message	string

Talba

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 jeħtieġ passports:read

Kull talba għall-passaport bl-istatus tagħha.

Talba

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

GET /supplier-requests/{id} jeħtieġ passports:read

Talba waħda bit-tweġibiet tal-fornitur, in-nota u l-ismijiet tal-fajls mehmuża.

Talba

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

16 / EndpointsWara l-bejgħ

POST /passports/{id}/items jeħtieġ items:write

Agħti lill-oġġetti ta' prodott (ta' kwalunkwe settur ħlief il-batteriji, li jużaw /units) in-numru tas-serje tagħhom: kull wieħed jieħu l-indirizz u l-kodiċi QR tiegħu, kodiċi tal-awtentiċità moħbi għat-tikketta, u s-sid jista' jirreġistrah. Ibgħat sa 10,000 oġġett jew firxa. B'GTIN l-indirizz huwa GS1 Digital Link /01/{gtin}/21/{serial}.

Parametru	Tip		Deskrizzjoni
items[].serial	string	meħtieġ	Sa 20 ittra, numru, punt, sing jew underscore.
items[].batch	string		Lott, sa 20 karattru.
items[].manufactured_on	string		Data tal-manifattura, SSSS-XX-JJ.
range	object		Minflok items: prefix, start, count, digits u batch, pereżempju SN-00001 sa SN-00500.

Talba

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

Tweġiba

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

GET /passports/{id}/items/{serial} jeħtieġ items:read

L-oġġett bl-indirizz, l-istatus, jekk huwiex irreġistrat u sa meta tibqa' l-garanzija, il-verifiki tal-awtentiċità u l-istorja tiegħu. Ċavetta b'items:write tieħu wkoll il-kodiċi moħbi għall-istampar. GET /passports/{id}/items jelenkahom (filtri status u batch, per_page sa 500).

Talba

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

Tweġiba

{
  "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} jeħtieġ items:write

Issettja status għal stolen jew recalled u l-paġna tiegħu twissi lil kull min jiskenjah, bl-status_note tiegħek; oġġett misruq ma jistax jiġi rreġistrat. retired jitfi l-paġna. Jistgħu jinbidlu wkoll batch u manufactured_on.

Parametru	Tip		Deskrizzjoni
status	string		active, stolen, recalled jew retired.
status_note	string		Jidher fuq il-paġna tal-oġġett, sa 500 karattru.

Talba

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 jeħtieġ aftersales:read

In-nies li rreġistraw il-prodotti tiegħek: isem, email, pajjiż, data tax-xiri, bejjiegħ, dati tal-garanzija u jekk qablux għal aħbarijiet u offerti (marketing_consent=1 jelenka lilhom biss). Standard: ir-reġistrazzjonijiet attivi; status=pending, transferred jew ended għall-oħrajn; since= għal bidliet wara data.

Talba

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

GET /service-requests jeħtieġ aftersales:read

Tiswijiet, talbiet taħt garanzija, teħid lura, partijiet ta' rikambju u mistoqsijiet mibgħuta mill-passaporti tiegħek, l-aktar ġodda l-ewwel, bil-filtri status u type. GET /service-requests/{reference} iżid il-konversazzjoni.

Talba

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

POST /service-requests/{reference}/replies jeħtieġ aftersales:write

Ir-risposta tiegħek tintbagħat lill-klijent bl-email b'link għall-paġna tat-talba tiegħu, bil-lingwa tiegħu. internal: true iżid nota li t-tim tiegħek biss jara. PATCH /service-requests/{reference} b'status imexxiha 'l quddiem (il-klijent jiġi infurmat meta tkun qed tiġi pproċessata, solvuta jew magħluqa).

Parametru	Tip		Deskrizzjoni
body	string	meħtieġ	Ir-risposta, sa 5,000 karattru.
internal	boolean		Nota għat-tim tiegħek minflok risposta.
status	string		new, in_progress, waiting, resolved jew closed.

Talba

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 / EndpointsEditjar bl-ingrossa u stampi

PATCH /products/bulk-fields jeħtieġ products:write

Jissettja dettall tal-prodott jew qasam tal-passaport fuq sa 5,000 prodott. mode huwa set, fill (biss fejn ikun vojt) jew clear. Sa 100 prodott jiġu aġġornati fit-talba nnifisha; settijiet akbar jitpoġġew fil-kju (202).

Parametru	Tip		Deskrizzjoni
product_ids	array	meħtieġ
target	string	meħtieġ	product \| field
key	string	meħtieġ
value	string
mode	string		set \| fill \| clear

Talba

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

Tweġiba

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

POST /products/{id}/images jeħtieġ products:write

Upload multipart ta' JPG, PNG jew WebP (sa 15MB, 8 għal kull prodott). L-ewwel stampa hija l-istampa prinċipali fuq il-passaport pubbliku.

Parametru	Tip		Deskrizzjoni
image	file	meħtieġ
alt	string		Deskrizzjoni tal-istampa.

Talba

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 jeħtieġ products:write

Għaddi image_ids fl-ordni li trid; l-ewwel waħda ssir l-istampa prinċipali.

Parametru	Tip		Deskrizzjoni
image_ids	array	meħtieġ

Talba

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} jeħtieġ products:write

Ineħħi l-istampa u l-fajl tagħha.

Talba

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

18 / EndpointsWebhooks

GET /webhooks jeħtieġ webhooks:manage

L-endpoints irreġistrati għall-ispazju tax-xogħol tiegħek. Is-sigrieti mhumiex inklużi hawn; ġib endpoint wieħed biex tara s-sigriet tiegħu.

Talba

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

POST /webhooks jeħtieġ webhooks:manage

Jirreġistra URL HTTPS pubbliku għal avveniment wieħed jew aktar. It-tweġiba tinkludi s-sigriet tal-firma. Hosts privati jew interni jiġu rrifjutati.

Parametru	Tip		Deskrizzjoni
url	string	meħtieġ
events	array	meħtieġ	Kwalunkwe wieħed mill-avvenimenti elenkati hawn taħt.

Talba

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

Tweġiba

{
  "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} jeħtieġ webhooks:manage

Talba

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

PUT /webhooks/{id} jeħtieġ webhooks:manage

Ibdel l-URL jew l-avvenimenti, jew issospendih u erġa' ibdih. Meta terġa' tibdih jiġi rrisettjat l-għadd ta' fallimenti; endpoint jiġi sospiż awtomatikament wara 10 kunsinni li fallew wara xulxin.

Parametru	Tip		Deskrizzjoni
url	string
events	array
is_active	boolean

Talba

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 jeħtieġ webhooks:manage

Ipoġġi fil-kju kunsinna webhook.test biex tkun tista' tiċċekkja r-riċevitur u l-kodiċi tal-firma tiegħek.

Talba

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

Tweġiba

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

GET /webhooks/{id}/deliveries jeħtieġ webhooks:manage

Kunsinni reċenti, l-aktar ġodda l-ewwel, bl-istatus HTTP li rritorna l-endpoint tiegħek u l-ewwel 500 karattru tal-korp tiegħu.

Parametru	Tip		Deskrizzjoni
per_page	integer		Sa 100.

Talba

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

DELETE /webhooks/{id} jeħtieġ webhooks:manage

Talba

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

Tweġiba

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

19 / AvvenimentiWebhooks

Minflok ma tistaqsi kontinwament, irreġistra endpoint tal-webhook fl-app (paġna Webhooks, disponibbli fuq il-pjanijiet Starter u 'l fuq) u MyProductPassport jibgħat JSON b'POST lill-URL tiegħek hekk kif iseħħu l-affarijiet:

Avveniment	Jiskatta meta
product.created	Jinħoloq prodott (app, API jew importazzjoni CSV)
product.updated	Prodott jiġi aġġornat
product.deleted	Jitħassar prodott
passport.created	Passaport jiġi ġġenerat
passport.published	Passaport isir attiv
passport.archived	Passaport jiġi arkivjat
supplier_request.submitted	Fornitur jibgħat l-informazzjoni li tlabt
owner.registered	Sid jikkonferma r-reġistrazzjoni tiegħu
owner.transferred	Oġġett jgħaddi għand sid irreġistrat ġdid
service_request.created	Klijent jibgħat talba għal servizz minn passaport
service_request.updated	Talba għal servizz tieħu risposta jew status ġdid
item.status_changed	Oġġett jiġi mmarkat bħala misruq, imsejjaħ lura jew irtirat, jew l-immarkar jitneħħa
item.verification_failed	Qari sigur ifalli, kodiċijiet ħżiena jinġemgħu, jew numru tas-serje jidher f'wisq postijiet
webhook.test	Tibgħat kunsinna tat-test mill-app

Kull kunsinna hija envelopp JSON: ID tal-kunsinna (l-istess ID jerġa' jintbagħat fit-tentattivi mill-ġdid, biex tkun tista' tneħħi d-duplikati), l-avveniment, in-numru tat-tentattiv, timbru tal-ħin u d-data tal-avveniment. L-avvenimenti tal-passaporti jġorru l-uuid u l-URL pubbliku tal-passaport, għalhekk rarament ikollok bżonn talba oħra:

Korp tal-kunsinna

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

L-headers fihom l-isem tal-avveniment, l-id tal-kunsinna, timestamp Unix u firma HMAC tal-body mhux ipproċessat, biex tkun tista' tivverifika li ġie mingħandna u tirrifjuta r-ripetizzjonijiet:

Intestaturi tal-kunsinna

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>

Wieġeb bi kwalunkwe 2xx fi żmien 10 sekondi. Kull ħaġa oħra terġa' tiġi pprovata ħames darbiet fuq madwar 90 minuta (30 s, 1 min, 5 min, 15 min, 1 siegħa); wara 10 fallimenti konsekuttivi l-endpoint jiġi sospiż sakemm terġa' tattivah.

Ivverifika (PHP)

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

Cookie	Skop	Skadenza
myproductpassport-session	Iżommok illoggjat u s-sit sigur	Sagħtejn
XSRF-TOKEN	Jipproteġi l-formoli minn falsifikazzjoni ta' talbiet bejn is-siti	Sagħtejn
cookie_consent	Jiftakar l-għażla tiegħek tal-cookies	12-il xahar
locale_suggested countdown_dismissed exit_intent_dismissed	Jiftakar li għalaqt messaġġ, biex ma jerġax jintwera	Sa 30 jum

Cookie	Skop	Skadenza
_ga, _ga_*	Google Analytics: jgħodd iż-żjarat u juri kif jintuża s-sit	Sentejn
_gcl_au	Google Ads: ikejjel liema reklami jwasslu għal reġistrazzjonijiet	90 jum
mpp_ref	Jiftakar is-sieħeb li segwejt il-link tiegħu, biex jiġi kkreditat jekk tirreġistra aktar tard	90 jum

Referenza tal-API

01 / Kif tibdaAwtentikazzjoni

02 / Kif tibdaLimiti tar-rata

03 / Kif tibdaŻbalji

04 / Kif tibdaPaġinazzjoni

05 / Kif tibdaKonnettur għall-assistent tal-IA (MCP)

06 / EndpointsKont

07 / EndpointsProdotti

08 / EndpointsPassaporti

09 / EndpointsKonformità

10 / EndpointsSetturi

11 / EndpointsDokumenti

12 / EndpointsKatina tal-provvista

13 / EndpointsTraduzzjonijiet

14 / EndpointsIntegrità u esportazzjonijiet

15 / EndpointsTalbiet lill-fornituri

16 / EndpointsWara l-bejgħ

17 / EndpointsEditjar bl-ingrossa u stampi

18 / EndpointsWebhooks

19 / AvvenimentiWebhooks

Qabel ma titlaq…

Int fuq il-lista!