Deweloperzy / REST API

Dokumentacja API

Cały MyProductPassport jest dostępny przez REST API uwierzytelniane kluczem: twórz produkty, generuj i publikuj cyfrowe paszporty produktów, przesyłaj bieżące dane baterii i sprawdzaj zgodność bezpośrednio z ERP, PIM lub potoku kompilacji.

v1 https://myproductpassport.eu/api/v1 Zacznij za darmo Specyfikacja OpenAPI ↓

01 / Pierwsze krokiUwierzytelnianie

Każde zapytanie jest uwierzytelniane kluczem API przekazywanym jako token Bearer. Klucze tworzy się w aplikacji w sekcji Klucze API, są wyświetlane tylko raz i przechowywane jako skrót; każdy klucz ma własny zestaw uprawnień, opcjonalną listę dozwolonych adresów IP i opcjonalną datę wygaśnięcia. Klucze można wymieniać bez przestojów.

Nagłówek żądania

Authorization: Bearer pk_your_api_key

W każdym planie. Klucze API można tworzyć i używać w każdym planie, także darmowym. Plan określa, ile żądań na minutę może wysłać klucz (poniżej) oraz ile produktów i paszportów może mieć obszar roboczy.

Tryb testowy. Klucz testowy (pk_test_...) wykonuje każde wywołanie dokładnie tak jak klucz produkcyjny, z tą samą walidacją, identyfikatorami i odpowiedziami, a następnie je cofa: nic nie jest zapisywane, nie są wysyłane żadne e-maile ani webhooki i nie jest przechowywany żaden plik. Odpowiedzi zawierają "test_mode": true oraz nagłówek X-MPP-Mode: test. Zbuduj i przetestuj integrację na swoich rzeczywistych danych, a następnie zastąp go kluczem produkcyjnym.

Uprawnienia są nadawane dla każdego klucza, więc integracja otrzymuje tylko to, czego potrzebuje:

Uprawnienie	Uprawnienia
products:read	Odczyt produktów
products:write	Tworzenie, aktualizowanie i usuwanie produktów
passports:read	Odczyt paszportów
passports:write	Generuj paszporty
passports:publish	Publikowanie i archiwizowanie paszportów
webhooks:manage	Tworzenie, testowanie i usuwanie punktów końcowych webhooków
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 / Pierwsze krokiLimity żądań

Limity obowiązują na klucz i na minutę i zależą od planu:

Plan	Żądania / minutę
Bezpłatny	30
Micro	60
E-Label	60
Starter	120
Professional	300
Business	600
Battery	600

Każda odpowiedź zawiera nagłówki X-RateLimit-Limit i X-RateLimit-Remaining. Przekroczenie limitu zwraca 429:

429 Too Many Requests

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

03 / Pierwsze krokiBłędy

Błędy są zwracane w formacie JSON ze standardowym kodem statusu. Najczęstsze:

Status	Znaczenie	Przykładowa treść
401	Brakujący, nieprawidłowy, unieważniony lub wygasły klucz	`{"error": "Invalid or revoked API key."}`
403	Kluczowi brakuje uprawnienia, adres IP nie jest na liście dozwolonych lub osiągnięto limit planu	`{"message": "API key does not have 'products:write' permission."}`
404	Zasób nie istnieje w Twojej przestrzeni roboczej	`{"message": "Not found."}`
422	Walidacja nie powiodła się	`{"message": "…", "errors": {"gtin": ["…"]}}`
429	Przekroczono limit żądań	`{"error": "Rate limit exceeded."}`

04 / Pierwsze krokiPaginacja

Endpointy list zwracają 25 elementów na stronę ze standardowymi obiektami links i meta. Przekaż ?page=2, aby przechodzić przez kolekcję.

05 / Pierwsze krokiŁącznik asystenta AI (MCP)

Połącz Claude, Cursor lub dowolnego asystenta obsługującego Model Context Protocol i poproś go prostymi słowami, aby tworzył produkty, wypełniał paszporty na podstawie tego, co mu powiesz, i sprawdzał, czego jeszcze brakuje. Używa klucza API z jego uprawnieniami i limitem żądań. Może tworzyć wersje robocze i wypełniać pola; nigdy niczego nie publikuje, nie archiwizuje ani nie usuwa: to zostaje w Twoich rękach w aplikacji.

Adres serwera (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 i inne klienty uruchamiające lokalny serwer

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

Dostępne narzędzia:

Narzędzie	Co robi
list_products	Produkty obszaru roboczego, od najnowszych, po 25 na stronę, z sektorem i najnowszym paszportem.
get_product	Jeden produkt ze szczegółami, sektorem, sekcjami regulacyjnymi i najnowszym paszportem.
list_sectors	Szablony sektorów, których może używać produkt (tekstylia, elektronika, baterie, wino i inne), z ich identyfikatorami. Sektor produktu decyduje, które pola paszportu są obowiązkowe.
create_product	Dodaje produkt do obszaru roboczego. Użyj sector_id z list_sectors. compliance_sections dodaje do paszportu sekcje regulacyjne: gpsr, epr, france, chemicals, eudr.
list_passports	Paszporty obszaru roboczego, od najnowszych, po 25 na stronę, ze statusem (draft, published, archived), procentem zgodności i adresem publicznym.
get_passport	Jeden paszport: status, wersja, procent zgodności, adres publiczny i linki do kodu QR.
create_passport	Tworzy wersję roboczą paszportu dla produktu. Nie jest publikowana: publikuje ją osoba w aplikacji.
get_passport_fields	Czego wymaga paszport: klucze pól obowiązkowych i opcjonalnych, znaczenie każdego (etykieta, opis, przykład), obecne wartości i brakujące pola obowiązkowe.
update_passport_fields	Zapisuje wartości pól w wersji roboczej lub opublikowanym paszporcie (opublikowany jest aktualizowany na miejscu: ten sam adres, ten sam kod QR). Klucze z get_passport_fields; pusty tekst usuwa wartość. Zapisuj tylko fakty podane przez użytkownika lub jego dokumenty.
get_compliance	Kompletność paszportu: procent, status i brakujące jeszcze pola obowiązkowe.

Wypróbuj z kluczem testowym. Z kluczem testowym (pk_test_...) zmiany asystenta są sprawdzane, a potem cofane, więc widzisz, co by zrobił, zanim dasz mu klucz produkcyjny.

06 / Punkty końcoweKonto

GET /me

Zwraca uwierzytelnione konto, jego plan subskrypcji i wykorzystanie limitu produktów. Przydatne do sprawdzenia połączenia.

Żądanie

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

Odpowiedź

{
  "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 / Punkty końcoweProdukty

GET /products wymaga products:read

Wyświetla produkty w Twojej przestrzeni roboczej od najnowszych, 25 na stronę. Każdy produkt zawiera swój sektor i podsumowanie najnowszego paszportu.

Parametr	Rodzaj		Opis
page	integer		Numer strony.

Żądanie

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

Odpowiedź

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

Tworzy jeden produkt. Zwraca 403, jeśli limit produktów w planie został wykorzystany.

Parametr	Rodzaj		Opis
name	string	wymagane	Nazwa produktu, do 255 znaków.
sku	string		Twój wewnętrzny SKU, do 100 znaków.
gtin	string		GTIN-8, 12, 13 lub 14 (tylko cyfry).
brand	string		Marka wyświetlana w publicznym paszporcie.
description	string		Do 2000 znaków.
category	string		Kategoria w dowolnym tekście. Domyślnie „general”.
sector_id	integer		Identyfikator sektora, który wybiera szablon pól paszportu.
country_of_origin	string		Kod kraju, np. „PT”.
weight	number		Masa netto.
weight_unit	string		Jedna z wartości kg, g, lb, oz. Domyślnie kg.
materials	array		Obiekty {name, percentage 0-100}.
has_packaging	boolean		Dodaje do paszportu pola szablonu opakowania (klucze zaczynające się od pkg_), pod tym samym kodem QR.

Żądanie

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

Odpowiedź

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

Tworzy do 100 produktów w jednym wywołaniu. Cała partia jest odrzucana z kodem 403, jeśli przekroczyłaby pozostały limit produktów. Przy katalogach liczących tysiące pozycji wywołuj ten punkt końcowy w pętli lub użyj importu CSV w aplikacji.

Parametr	Rodzaj		Opis
products	array	wymagane	Od 1 do 100 obiektów produktu z tymi samymi polami co „Utwórz produkt” (bez materiałów).

Żądanie

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

Odpowiedź

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

Zwraca jeden produkt z sektorem i podsumowaniem najnowszego paszportu. 404, jeśli id nie należy do Twojej przestrzeni roboczej.

Żądanie

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

PUT /products/{id} wymaga products:write

Częściowo aktualizuje produkt. Wyślij tylko pola, które chcesz zmienić; lista pól jest taka sama jak w Utwórz produkt.

Żądanie

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

Usuwa produkt w sposób miękki (soft delete). Opublikowane paszporty produktu nadal działają, więc wydrukowane kody QR nigdy nie prowadzą donikąd.

Żądanie

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

Odpowiedź

{ "message": "Product deleted." }

08 / Punkty końcowePaszporty

GET /passports wymaga passports:read

Wyświetla paszporty od najnowszych, 25 na stronę, z podsumowaniem produktu i wszystkimi polami paszportu.

Parametr	Rodzaj		Opis
page	integer		Numer strony.

Żądanie

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

Odpowiedź

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

Generuje roboczy paszport produktu, wypełniając pola danymi produktu i szablonem sektora. Zwraca wersję roboczą z wynikiem zgodności. Jeśli produkt ma już aktywny paszport, zwraca 409 z tym paszportem: popraw go przez PUT /passports/{id}/fields, co zachowuje jego adres i kod QR.

Żądanie

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

GET /passports/{id} wymaga passports:read

Zwraca jeden paszport z produktem, polami, publicznym adresem URL i GS1 Digital Link.

Żądanie

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

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

Publikuje wersję roboczą paszportu, udostępniając jego publiczną stronę i kod QR. Publikować można tylko wersje robocze; wszystko inne zwraca 404.

Żądanie

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

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

Archiwizuje paszport i wycofuje jego stronę publiczną z obiegu.

Żądanie

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

POST /passports/bulk-publish wymaga passports:publish

Publikuje do 50 wersji roboczych paszportów w jednym wywołaniu i raportuje wynik dla każdego paszportu, więc jeden błąd nigdy nie przerywa całej partii.

Parametr	Rodzaj		Opis
passport_ids	array	wymagane	Od 1 do 50 identyfikatorów paszportów.

Żądanie

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

Odpowiedź

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

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

Dla produktu przygotowanego do ponownego użycia, o zmienionym przeznaczeniu lub zregenerowanego rozporządzenie w sprawie baterii (art. 77 ust. 7) wymaga nowego paszportu powiązanego z oryginałem. Operacja tworzy nowy rekord produktu i roboczy paszport wypełniony na podstawie opublikowanego i z nim powiązany. Oryginał pozostaje aktywny, a oba paszporty pokazują powiązanie. Opublikuj nowy przez POST /passports/{id}/publish.

Parametr	Rodzaj		Opis
stage	string	wymagane	prepared_for_reuse, repurposed lub remanufactured.

Żądanie

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

Odpowiedź

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

Zwraca klucze pól wymagane przez szablon sektora paszportu (obowiązkowe i opcjonalne), obecnie zapisane wartości i brakujące klucze obowiązkowe. Użyj tego, aby zbudować treść dla PUT /passports/{id}/fields.

Żądanie

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

Odpowiedź

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

Zapisuje dowolny zestaw wartości pól w paszporcie roboczym lub opublikowanym: pełny zestaw z załącznika XIII dla baterii, pola szablonu sektora lub własne klucze. Wyślij tylko klucze, które chcesz zmienić; wartość null lub pusta usuwa pole. Opublikowany paszport jest aktualizowany w miejscu, jego adres i kod QR się nie zmieniają, a tłumaczenia maszynowe są generowane ponownie. Zgodność jest oceniana od nowa. To wywołanie nie publikuje wersji roboczej; użyj POST /passports/{id}/publish.

Parametr	Rodzaj		Opis
fields	object	wymagane	Mapa klucza pola na wartość. Klucze to małe litery, cyfry i podkreślenia; wartości do 5000 znaków. Do 200 kluczy na wywołanie.

Żądanie

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

Odpowiedź

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

Przesyła własne dane tej baterii (załącznik XIII pkt 4 rozporządzenia (UE) 2023/1542) do opublikowanego paszportu, dla systemów BMS i flotowych. Wyślij dowolny podzbiór poniższych pól; zgodność jest ponownie sprawdzana po aktualizacji. Wartości te są pokazywane tylko odwiedzającym zatwierdzonym przez właściciela paszportu (art. 77 ust. 2), nigdy na stronie publicznej. capacity_fade, power_capability i internal_resistance są zapisywane jako bieżące odczyty tej baterii (current_*), oddzielnie od pierwotnych wartości modelu.

Parametr	Rodzaj	Opis
state_of_health	string	np. „97% po 412 cyklach”.
state_of_certified_energy	string	Pozostała energia certyfikowana (baterie do pojazdów elektrycznych).
battery_status	string	original, repurposed, re-used, remanufactured lub waste.
capacity_fade	string	Dotychczasowy spadek pojemności. Zapisywany jako current_capacity_fade.
power_capability	string	Obecna moc. Zapisywana jako current_power_capability.
internal_resistance	string	Zmierzona rezystancja wewnętrzna. Zapisywana jako current_internal_resistance.
use_data	string	Cykle, zdarzenia negatywne, temperatura i stan naładowania, do 5000 znaków.

Żądanie

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

Odpowiedź

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

Każda bateria potrzebuje własnego paszportu (rozporządzenie (UE) 2023/1542, art. 77 ust. 1). Zarejestruj do 10 000 baterii danego modelu w jednym wywołaniu, każdą z własnym numerem seryjnym (do 20 liter, cyfr, kropek, łączników lub podkreśleń) i opcjonalnie manufacturing_date, battery_status oraz danymi z załącznika XIII pkt 4. Istniejące numery seryjne są aktualizowane; pominięte wartości pozostają bez zmian. Jeśli produkt ma GTIN, adresem każdej baterii jest jej GS1 Digital Link, /01/{gtin}/21/{serial}. Dane z pkt 4 widzą tylko osoby zatwierdzone przez właściciela.

Parametr	Rodzaj		Opis
units[].serial	string	wymagane	Numer seryjny baterii.
units[].manufacturing_date	string		Miesiąc i rok, np. "2026-09".
units[].battery_status	string		original lub waste. Zmiana statusu wymaga wartości zmierzonych przy tej zmianie (załącznik XIII pkt 4 lit. a)); status waste wymaga też pól responsible_party_type (producer, pro lub waste_operator), responsible_party_name i responsible_party_contact (art. 77 ust. 7). Status recycled wraz z recycled_at i recycler_name kończy paszport (art. 77 ust. 8). Bateria przeznaczona do innego celu, ponownie użyta lub regenerowana otrzymuje nowy paszport: POST /passports/{id}/units/{serial}/successor.
units[].state_of_health	string		Także 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 i use_data.

Żądanie

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

Odpowiedź

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

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

Dla systemu zarządzania baterią przesyłającego dane jednej baterii: dowolne z battery_status, state_of_health, state_of_certified_energy, current_capacity_fade, current_power_capability, current_internal_resistance i use_data. Wyślij GET na tę samą ścieżkę, aby je odczytać, lub GET /passports/{id}/units, aby pobrać listę (per_page do 500).

Żądanie

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

Odpowiedź

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

Załącznik XIII pkt 4 lit. a) wymaga wartości dotyczących wydajności i trwałości w chwili wprowadzenia baterii do obrotu i przy zmianie jej statusu. Te odczyty są zachowywane w pierwotnej postaci, niezależnie od późniejszych aktualizacji; aby zachować także okresowy odczyt, wyślij record_snapshot: true w żądaniu PATCH.

Żądanie

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

Odpowiedź

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

Art. 77 ust. 7: bateria przygotowana do ponownego użycia, poddana zmianie przeznaczenia lub regenerowana ma nowy paszport powiązany z oryginałem. Ta operacja ponownie rejestruje baterię z nowym numerem seryjnym i identyfikatorem w ramach modelu baterii drugiego życia w Twojej przestrzeni roboczej (utworzonego na podstawie tego modelu, jeśli jeszcze nie istnieje), łączy oba paszporty i zachowuje wartości zmierzone przy zmianie. Oryginalna bateria zachowuje swój paszport. Uzupełnij i opublikuj model drugiego życia za pomocą POST /passports/{id}/publish.

Parametr	Rodzaj		Opis
stage	string	wymagane	prepared_for_reuse, repurposed lub remanufactured.
values	object	wymagane	Wartości zmierzone przy zmianie: co najmniej jedna wartość z każdej pary remaining_capacity_ah lub current_capacity_fade, current_power_capability lub power_fade, current_internal_resistance lub internal_resistance_increase, a także expected_lifetime_cycles_remaining (załącznik IV część A).
serial	string		Nowy numer seryjny. Domyślnie: pierwotny numer seryjny z końcówką -RU, -RP lub -RM.
measured_at	string		Kiedy zmierzono wartości.
member_state	string		Dwuliterowy kod państwa członkowskiego, w którym zbadano stan zdrowia (art. 73 ust. 1 lit. a)).
target_passport_id	integer		Istniejący model drugiego życia tego modelu baterii, w ramach którego ma zostać zarejestrowana.

Żądanie

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

Odpowiedź

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

Zapisuje w paszporcie zgłoszenie do unijnego rejestru DPP i jego wynik: status, identyfikator korelacji, identyfikator rejestracji zwrócony przez rejestr oraz opcjonalny link do kopii zapasowej przechowywanej przez dostawcę usług DPP. Sama rejestracja odbywa się w rejestrze Komisji (formularz internetowy lub przesłanie pliku); tu wynik jest przechowywany razem z paszportem. GET /passports/{id} zwraca ten sam blok w registry.

Parametr	Rodzaj	Opis
status	string	not_submitted, submitted, registered lub failed.
product_group	string	Grupa produktów w rejestrze, na przykład batteries.
granularity	string	model, partia lub egzemplarz.
upi	string	Niepowtarzalny identyfikator produktu jako adres URL https. Domyślnie adres URL publicznego paszportu.
correlation_id	string	Identyfikator korelacji nadany przez Rejestr przy zgłoszeniu.
uri	string	Identyfikator rejestracji zwrócony przez rejestr.
backup_url	string	Link https do kopii zapasowej przechowywanej przez dostawcę usług DPP.
submitted_at	date	Data zgłoszenia.
registered_at	date	Data rejestracji.
error	string	Opis błędu nieudanego zgłoszenia.

Żądanie

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

Odpowiedź

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

Kod QR paszportu jako plik: svg (domyślnie), png (z Twoją marką, gotowy do druku) lub pdf (arkusz etykiet).

Parametr	Rodzaj		Opis
format	string		svg \| png \| pdf

Żądanie

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

09 / Punkty końcoweZgodność

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

Przeprowadza bieżącą kontrolę zgodności paszportu z polami wymaganymi dla jego sektora i dokładnie wskazuje, czego brakuje.

Żądanie

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

Odpowiedź

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

10 / Punkty końcoweSektory

GET /sectors

Sektory, do których można przypisać produkt: sektory systemowe platformy oraz sektory zdefiniowane przez Twoją przestrzeń roboczą. Używaj id przy tworzeniu produktów, a kluczy pól przy zapisywaniu pól paszportu.

Żądanie

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

Odpowiedź

{
  "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 / Punkty końcoweDokumenty

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

Deklaracje zgodności, sprawozdania z badań i certyfikaty dołączone do produktu. Dokument publiczny jest podlinkowany w każdym opublikowanym paszporcie produktu.

Żądanie

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

Odpowiedź

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

Przesyłanie multipart. PDF, Word, Excel, CSV, tekst, PNG i JPEG do 10 MB, maksymalnie 20 na produkt. Tekst jest wyodrębniany w tle.

Parametr	Rodzaj		Opis
file	file	wymagane	Dokument.
is_public	boolean		Pokaż w publicznym paszporcie (domyślnie false).

Żądanie

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

Określa, czy dokument jest podlinkowany w publicznym paszporcie.

Parametr	Rodzaj		Opis
is_public	boolean	wymagane

Żądanie

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

Usuwa plik i jego powiązanie z paszportem.

Żądanie

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

Odpowiedź

{ "message": "Document deleted." }

12 / Punkty końcoweŁańcuch dostaw

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

Etapy wyświetlane w paszporcie produktu, w kolejności.

Żądanie

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

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

Zastępuje wszystkie etapy przesłaną listą, w przesłanej kolejności. Wyślij pustą listę, aby go wyczyścić. Typy etapów: raw_material, processing, manufacturing, assembly, packaging, distribution.

Parametr	Rodzaj		Opis
steps	array	wymagane	Do 50 etapów.
steps[].step_type	string	wymagane
steps[].supplier_name	string	wymagane
steps[].supplier_location	string
steps[].supplier_country	string		ISO 3166-1 alfa-2.
steps[].lat / lng	number
steps[].description	string
steps[].certifications	array
steps[].date	date

Żądanie

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 / Punkty końcoweTłumaczenia

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

Każda przetłumaczona wartość pola według języka, ze źródłem: auto (maszynowe, tworzone przy publikacji) lub ręczne.

Żądanie

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

Odpowiedź

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

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

Ustawia tłumaczenia dla jednego języka według klucza pola. Tłumaczenie ręczne nigdy nie jest nadpisywane maszynowo. Wyślij pusty ciąg, aby je usunąć.

Parametr	Rodzaj		Opis
fields	object	wymagane	field_key: przetłumaczona wartość

Żądanie

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

Odpowiedź

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

14 / Punkty końcoweIntegralność i eksport

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

Każdy opublikowany stan paszportu jako rekord powiązany łańcuchem skrótów i podpisany kluczem Ed25519: odcisk (SHA-256), wartość łańcucha i podpis. Klucze publiczne znajdują się pod adresem /.well-known/mpp-integrity-keys.json, dzięki czemu każdy może zweryfikować łańcuch.

Żądanie

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

Odpowiedź

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

Kompletny rekord w postaci, w jakiej został podpisany, wraz z migawką: treść paszportu w tamtym momencie, aż po skrót każdego załączonego pliku.

Żądanie

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

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

Paszport jako dokument GS1 EPCIS 2.0 w formacie JSON-LD: uruchomienie produktu (commissioning), każdy etap łańcucha dostaw jako obserwacja, poszczególne baterie oraz paszport drugiego życia jako transformacja. Identyfikatory są identyfikatorami URI GS1 Digital Link, gdy produkt ma GTIN.

Żądanie

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

15 / Punkty końcoweProśby do dostawców

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

Wysyła do dostawcy e-mail z prywatnym linkiem do uzupełnienia wybranych pól w jego języku. Żadne dane nie trafiają do paszportu, dopóki nie zatwierdzi ich ktoś z Twojej przestrzeni roboczej.

Parametr	Rodzaj		Opis
supplier_name	string	wymagane
supplier_email	string	wymagane
field_keys	array	wymagane	Klucze pól z szablonu paszportu.
locale	string		Język e-maila i formularza, np. de.
due_at	date		Termin odpowiedzi; domyślnie 14 dni, jeśli nie zostanie podany.
message	string

Żądanie

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

Wszystkie prośby dotyczące paszportu wraz z ich statusem.

Żądanie

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

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

Jedna prośba z odpowiedziami dostawcy, notatką i nazwami załączonych plików.

Żądanie

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

16 / Punkty końcoweObsługa posprzedażowa

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

Nadaj egzemplarzom produktu (każdy sektor poza bateriami, które używają /units) własny numer seryjny: każdy otrzymuje własny adres i kod QR, ukryty kod autentyczności na etykietę i może zostać zarejestrowany przez właściciela. Wyślij do 10 000 egzemplarzy lub zakres. Z numerem GTIN adresem jest GS1 Digital Link /01/{gtin}/21/{serial}.

Parametr	Rodzaj		Opis
items[].serial	string	wymagane	Do 20 liter, cyfr, kropek, łączników lub podkreśleń.
items[].batch	string		Partia, do 20 znaków.
items[].manufactured_on	string		Data produkcji, RRRR-MM-DD.
range	object		Zamiast items: prefix, start, count, digits i batch, na przykład od SN-00001 do SN-00500.

Żądanie

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

Odpowiedź

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

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

Egzemplarz z adresem, statusem, informacją, czy jest zarejestrowany i do kiedy ma gwarancję, sprawdzeniami autentyczności i historią. Klucz z items:write otrzymuje też ukryty kod do wydruku. GET /passports/{id}/items zwraca listę (filtry status i batch, per_page do 500).

Żądanie

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

Odpowiedź

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

Ustaw status na stolen lub recalled, a strona egzemplarza ostrzeże każdego, kto go zeskanuje, wyświetlając Twoją notatkę status_note; skradzionego egzemplarza nie można zarejestrować. retired wyłącza jego stronę. Można też zmienić batch i manufactured_on.

Parametr	Rodzaj		Opis
status	string		active, stolen, recalled lub retired.
status_note	string		Wyświetlany na stronie egzemplarza, do 500 znaków.

Żądanie

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

Osoby, które zarejestrowały Twoje produkty: imię, e-mail, kraj, data zakupu, sprzedawca, daty gwarancji i czy zgodziły się na nowości i oferty (marketing_consent=1 zwraca tylko te). Domyślnie aktywne rejestracje; status=pending, transferred lub ended dla pozostałych; since= dla zmian po danej dacie.

Żądanie

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

GET /service-requests wymaga aftersales:read

Naprawy, reklamacje gwarancyjne, zwroty, części zamienne i pytania wysłane z Twoich paszportów, od najnowszych, z filtrami status i type. GET /service-requests/{reference} dodaje rozmowę.

Żądanie

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

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

Twoja odpowiedź trafia do klienta e-mailem z linkiem do strony zgłoszenia, w jego języku. internal: true dodaje notatkę widoczną tylko dla Twojego zespołu. PATCH /service-requests/{reference} ze statusem przesuwa zgłoszenie dalej (klient jest informowany, gdy zgłoszenie jest w realizacji, zostaje rozwiązane lub zamknięte).

Parametr	Rodzaj		Opis
body	string	wymagane	Odpowiedź, do 5000 znaków.
internal	boolean		Notatka dla zespołu zamiast odpowiedzi.
status	string		new, in_progress, waiting, resolved lub closed.

Żądanie

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 / Punkty końcoweEdycja zbiorcza i zdjęcia

PATCH /products/bulk-fields wymaga products:write

Ustawia dane produktu lub pole paszportu dla maksymalnie 5000 produktów. mode przyjmuje wartość set, fill (tylko tam, gdzie pole jest puste) lub clear. Do 100 produktów jest aktualizowanych w ramach żądania; większe zbiory trafiają do kolejki (202).

Parametr	Rodzaj		Opis
product_ids	array	wymagane
target	string	wymagane	product \| field
key	string	wymagane
value	string
mode	string		set \| fill \| clear

Żądanie

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

Odpowiedź

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

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

Przesyłanie multipart pliku JPG, PNG lub WebP (do 15MB, 8 na produkt). Pierwsze zdjęcie jest zdjęciem głównym w publicznym paszporcie.

Parametr	Rodzaj		Opis
image	file	wymagane
alt	string		Opis zdjęcia.

Żądanie

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

Przekaż image_ids w wybranej kolejności; pierwsze zdjęcie staje się zdjęciem głównym.

Parametr	Rodzaj		Opis
image_ids	array	wymagane

Żądanie

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

Usuwa zdjęcie i jego plik.

Żądanie

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

18 / Punkty końcoweWebhooks

GET /webhooks wymaga webhooks:manage

Endpointy zarejestrowane dla Twojej przestrzeni roboczej. Sekrety nie są tu uwzględnione; pobierz pojedynczy endpoint, aby zobaczyć jego sekret.

Żądanie

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

POST /webhooks wymaga webhooks:manage

Rejestruje publiczny adres URL HTTPS dla jednego lub kilku zdarzeń. Odpowiedź zawiera sekret podpisu. Hosty prywatne lub wewnętrzne są odrzucane.

Parametr	Rodzaj		Opis
url	string	wymagane
events	array	wymagane	Dowolne ze zdarzeń wymienionych poniżej.

Żądanie

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

Odpowiedź

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

Żądanie

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

PUT /webhooks/{id} wymaga webhooks:manage

Zmień adres URL lub zdarzenia albo wstrzymaj i wznów punkt końcowy. Wznowienie zeruje licznik błędów; punkt końcowy jest wstrzymywany automatycznie po 10 kolejnych nieudanych dostarczeniach.

Parametr	Rodzaj		Opis
url	string
events	array
is_active	boolean

Żądanie

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

Dodaje do kolejki dostarczenie webhook.test, aby można było sprawdzić odbiornik i kod podpisu.

Żądanie

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

Odpowiedź

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

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

Ostatnie dostarczenia, od najnowszych, ze statusem HTTP zwróconym przez Twój endpoint i pierwszymi 500 znakami odpowiedzi.

Parametr	Rodzaj		Opis
per_page	integer		Do 100.

Żądanie

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

DELETE /webhooks/{id} wymaga webhooks:manage

Żądanie

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

Odpowiedź

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

19 / ZdarzeniaWebhooks

Zamiast odpytywać API, zarejestruj w aplikacji endpoint webhooka (strona Webhooki, dostępna od planu Starter) a MyProductPassport będzie wysyłać JSON metodą POST na Twój adres URL, gdy coś się wydarzy:

Zdarzenie	Uruchamiane, gdy
product.created	Produkt zostaje utworzony (aplikacja, API lub import CSV)
product.updated	Produkt zostaje zaktualizowany
product.deleted	Produkt zostaje usunięty
passport.created	Paszport zostaje wygenerowany
passport.published	Paszport zostaje opublikowany
passport.archived	Paszport zostaje zarchiwizowany
supplier_request.submitted	Dostawca przesyła żądane informacje
owner.registered	Właściciel potwierdza rejestrację
owner.transferred	Egzemplarz przechodzi na nowego zarejestrowanego właściciela
service_request.created	Klient wysyła zgłoszenie serwisowe z paszportu
service_request.updated	Zgłoszenie serwisowe otrzymuje odpowiedź lub nowy status
item.status_changed	Egzemplarz zostaje oznaczony jako skradziony, wycofany z rynku lub wycofany z użytku albo oznaczenie zostaje usunięte
item.verification_failed	Odczyt bezpiecznego tagu się nie udaje, gromadzą się błędne kody lub numer seryjny pojawia się w zbyt wielu miejscach
webhook.test	Wysyłasz testowe dostarczenie z aplikacji

Każde dostarczenie to koperta JSON: identyfikator dostarczenia (przy ponowieniach wysyłany jest ten sam identyfikator, więc możesz usuwać duplikaty), zdarzenie, numer próby, znacznik czasu i dane zdarzenia. Zdarzenia paszportu zawierają uuid i publiczny adres URL paszportu, więc rzadko potrzebujesz drugiego zapytania:

Treść dostarczenia

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

Nagłówki zawierają nazwę zdarzenia, id dostarczenia, znacznik czasu Unix i podpis HMAC surowej treści, dzięki czemu możesz sprawdzić, że pochodzi od nas, i odrzucać powtórzenia:

Nagłówki dostarczenia

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>

Odpowiedz dowolnym kodem 2xx w ciągu 10 sekund. Każda inna odpowiedź jest ponawiana pięć razy w ciągu około 90 minut (30 s, 1 min, 5 min, 15 min, 1 h); po 10 kolejnych niepowodzeniach punkt końcowy zostaje wstrzymany, dopóki go nie włączysz.

Weryfikacja (PHP)

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

Plik cookie	Cel	Ważność
myproductpassport-session	Utrzymuje zalogowanie i bezpieczeństwo strony	2 godziny
XSRF-TOKEN	Chroni formularze przed atakami typu cross-site request forgery	2 godziny
cookie_consent	Zapamiętuje wybór dotyczący plików cookie	12 miesięcy
locale_suggested countdown_dismissed exit_intent_dismissed	Zapamiętuje zamknięcie komunikatu, aby nie wyświetlać go ponownie	Do 30 dni

Plik cookie	Cel	Ważność
_ga, _ga_*	Google Analytics: liczy odwiedziny i pokazuje, jak strona jest używana	2 lata
_gcl_au	Google Ads: mierzy, które reklamy prowadzą do rejestracji	90 dni
mpp_ref	Zapamiętuje partnera, którego link Państwo kliknęli, aby przypisać mu ewentualną późniejszą rejestrację	90 dni

Dokumentacja API

01 / Pierwsze krokiUwierzytelnianie

02 / Pierwsze krokiLimity żądań

03 / Pierwsze krokiBłędy

04 / Pierwsze krokiPaginacja

05 / Pierwsze krokiŁącznik asystenta AI (MCP)

06 / Punkty końcoweKonto

07 / Punkty końcoweProdukty

08 / Punkty końcowePaszporty

09 / Punkty końcoweZgodność

10 / Punkty końcoweSektory

11 / Punkty końcoweDokumenty

12 / Punkty końcoweŁańcuch dostaw

13 / Punkty końcoweTłumaczenia

14 / Punkty końcoweIntegralność i eksport

15 / Punkty końcoweProśby do dostawców

16 / Punkty końcoweObsługa posprzedażowa

17 / Punkty końcoweEdycja zbiorcza i zdjęcia

18 / Punkty końcoweWebhooks

19 / ZdarzeniaWebhooks

Zanim odejdziesz…

Jesteś na liście!