---
title: "Automatyzacja Cyfrowych Paszportów Produktów za pomocą Webhooków — qr3.app Blog"
description: "Cyfrowy Paszport Produktu to nie statyczna strona — każde zeskanowanie to zdarzenie, na którym możesz budować. Reaguj na qr.scanned dla analityki, ponownych zamówień i flag wycofania, utrzymuj dane paszportu aktualne z systemu ERP i weryfikuj każdy payload za pomocą HMAC-SHA256. Przewodnik na poziomie deweloperskim z kodem."
canonical: "https://qr3.app/pl/blog/dpp-webhooks-automation/"
lang: "pl"
robots: "index,follow,max-image-preview:large,max-snippet:-1"
---

# Automatyzacja Cyfrowych Paszportów Produktów za pomocą Webhooków — qr3.app Blog

> Cyfrowy Paszport Produktu to nie statyczna strona — każde zeskanowanie to zdarzenie, na którym możesz budować. Reaguj na qr.scanned dla analityki, ponownych zamówień i flag wycofania, utrzymuj dane paszportu aktualne z systemu ERP i weryfikuj każdy payload za pomocą HMAC-SHA256. Przewodnik na poziomie deweloperskim z kodem.

Canonical: <https://qr3.app/pl/blog/dpp-webhooks-automation/>

[← Blog](/pl/blog/) [Poradniki](/pl/blog/category/tutorials/)

30 maja 2026 5 min czytania [Poradniki](/pl/blog/category/tutorials/) [dpp](/pl/blog/tag/dpp/)[webhooks](/pl/blog/tag/webhooks/)[automation](/pl/blog/tag/automation/)[qr-scanned](/pl/blog/tag/qr-scanned/)[sdk](/pl/blog/tag/sdk/)

# Automatyzacja Cyfrowych Paszportów Produktów za pomocą Webhooków

Cyfrowy Paszport Produktu to nie statyczna strona — każde zeskanowanie to zdarzenie, na którym możesz budować. Reaguj na qr.scanned dla analityki, ponownych zamówień i flag wycofania, utrzymuj dane paszportu aktualne z systemu ERP i weryfikuj każdy payload za pomocą HMAC-SHA256. Przewodnik na poziomie deweloperskim z kodem.

autor: **QR3 Redaktion**

![Automatyzacja Cyfrowych Paszportów Produktów za pomocą Webhooków](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/dpp-webhooks-automation/hero.png)

Większość zespołów traktuje Cyfrowy Paszport Produktu jak stronę: tworzysz go, drukujesz kod QR i zapominasz o nim. To pozostawia najbardziej użyteczny sygnał niewykorzystany. Za każdym razem, gdy ktoś skanuje kod QR na produkcie, jest to **zdarzenie** — prawdziwa osoba, w prawdziwym kraju, trzymająca prawdziwy egzemplarz, w prawdziwym momencie. Podłącz te zdarzenia do swojego stosu technologicznego, a paszport przestaje być statyczną stroną i staje się front-endem potoku automatyzacji. Ten przewodnik pokazuje, jak subskrybować `qr.scanned`, weryfikować każdy payload oraz przekształcać skany i aktualizacje w realne przepływy pracy za pomocą SDK qr3.

## Dlaczego DPP jest źródłem zdarzeń, a nie statyczną stroną

Wartość paszportu nie tkwi w stronie, którą konsument widzi raz. Tkwi w strumieniu interakcji wokół niego: skanach w terenie, zmianach danych z systemu ERP, przejściach cyklu życia. Każda z nich jest czymś, na co Twoje systemy mogą reagować w czasie rzeczywistym.

Webhooki odwracają zwykły model odpytywania (polling). Zamiast pytać *„czy coś się wydarzyło?"* w odstępach czasowych, qr3 dzwoni do **Ciebie** w momencie, gdy to się dzieje. Typy zdarzeń emitowane przez platformę obejmują `qr.scanned`, a także `qr.created`, `qr.updated` i `qr.deleted` dla zmian cyklu życia. Tym, którego większość zespołów nie wykorzystuje wystarczająco, jest `qr.scanned`: uruchamia się, gdy konsument, technik lub celnik faktycznie skanuje produkt w terenie.

Payload `qr.scanned` niesie kontekst potrzebny do działania — w tym **kraj** zeskanowania oraz **identyfikator dpp/code**, który określa, który egzemplarz został zeskanowany. To wystarczy, aby napędzać analitykę, uzupełnianie zapasów i logikę wycofania bez udziału człowieka.

## Subskrybowanie qr.scanned

Wskaż punkt końcowy webhooka na swoją usługę i obsłuż zdarzenie. Zweryfikuj sygnaturę na podstawie surowej treści (raw body) przed jej sparsowaniem:

```
import express from "express";
import { createHmac, timingSafeEqual } from "crypto";

const app = express();
const secret = process.env.QR3_WEBHOOK_SECRET!;

// Recompute the HMAC over the exact bytes qr3 signed and compare in constant time.
function verify(raw: Buffer, header: string | undefined): boolean {
  const expected = createHmac("sha256", secret).update(raw).digest("hex");
  const expectedBytes = Buffer.from(`sha256=${expected}`);
  const receivedBytes = Buffer.from(header ?? "");
  return (
    expectedBytes.length === receivedBytes.length &&
    timingSafeEqual(expectedBytes, receivedBytes)
  );
}

// Use the raw body so the signature matches the exact bytes qr3 signed.
app.post("/webhooks/qr3", express.raw({ type: "application/json" }), (req, res) => {
  if (!verify(req.body, req.headers["x-qr3-signature"] as string)) return res.sendStatus(401);
  const event = JSON.parse(req.body.toString("utf8"));

  if (event.type === "qr.scanned") {
    // event payload includes fields like the scan country and the dpp/code id
    handleScan(event);
  }

  res.sendStatus(200);
});
```

Handler jest celowo cienki: weryfikuj, rozgałęziaj według `event.type`, potwierdzaj szybko za pomocą `200`. Wykonuj ciężką pracę (zapisy analityczne, wywołania ERP) asynchronicznie, aby powolny komponent w dole łańcucha nigdy nie blokował potwierdzenia.

## Weryfikacja sygnatur (HMAC-SHA256) — rób to zawsze

Punkt końcowy webhooka to publiczny adres URL. Każdy, kto go znajdzie, może na niego wysłać żądanie POST. Jeśli ufasz treści bez sprawdzenia, kto ją wysłał, atakujący może sfałszować „skany", wywołać fałszywe ponowne zamówienia lub uruchomić fałszywe flagi wycofania. **Zawsze weryfikuj sygnaturę, zanim podejmiesz działanie na podstawie payloadu.**

qr3 podpisuje każdy webhook za pomocą **HMAC-SHA256** na surowej treści żądania, używając Twojego sekretu punktu końcowego. Sygnatura przybywa w nagłówku żądania `X-QR3-Signature` jako `sha256=` wraz z następującym po nim skrótem szesnastkowym. Oblicz ponownie HMAC na tych samych bajtach i porównaj oba w stałym czasie; jeśli się różnią, odrzuć żądanie:

```
app.post("/webhooks/qr3", express.raw({ type: "application/json" }), (req, res) => {
  if (!verify(req.body, req.headers["x-qr3-signature"] as string)) {
    // signature mismatch → not from qr3 (or body was altered in transit)
    return res.sendStatus(401);
  }
  process(JSON.parse(req.body.toString("utf8")));
  res.sendStatus(200);
});
```

Trzy zasady, które utrzymują to w uczciwości:

- **Weryfikuj wobec surowych bajtów.** Ponowna serializacja JSON może zmienić kolejność kluczy i białe znaki, co psuje HMAC. Przechwyć surową treść (powyżej, `express.raw`).

- **Trzymaj sekret w tajemnicy.** Żyje w Twoim środowisku, nigdy w kodzie klienckim ani w repozytorium.

- **Domyślnie zamykaj (fail closed).** Brak ważnej sygnatury → `401`, żadnych efektów ubocznych. Nigdy nie „przetwarzaj mimo wszystko" przy niezgodności.

## Wzorce: analityka / ponowne zamówienie / wycofanie

Gdy już ufasz zdarzeniu, garść wzorców pokrywa większość tego, czego chcą zespoły:

```
function handleScan(event: { type: string; data: { country?: string; dpp_id?: string } }) {
  // 1) Analytics — where and how often are products scanned?
  metrics.increment("dpp.scan", { country: event.data.country });

  // 2) Re-order — a scan can signal consumption or field activity
  if (event.data.country) maybeReplenish(event.data.dpp_id, event.data.country);

  // 3) Recall flag — scans of a flagged unit alert your team
  if (isRecalled(event.data.dpp_id)) alertRecall(event.data.dpp_id, event.data.country);
}
```

- **Analityka:** agreguj skany według kraju i egzemplarza, aby zobaczyć rzeczywiste zaangażowanie — które rynki faktycznie skanują i które SKU mają najwięcej interakcji posprzedażowych.

- **Ponowne zamówienie / uzupełnianie:** nagły wzrost skanów w regionie może zasilać sygnały popytu lub uruchamiać przepływy uzupełniania zapasów w Twoim systemie ERP.

- **Wycofanie / bezpieczeństwo:** jeśli egzemplarz jest objęty wycofaniem, skan to szansa, aby dotrzeć do tego, kto go trzyma — powiadom swój zespół lub wyświetl komunikat na samym paszporcie.

Żaden z tych przypadków nie wymaga odpytywania ani nocnego przetwarzania wsadowego. Dzieją się w momencie zeskanowania produktu.

## Utrzymywanie aktualności danych za pomocą client.dpp.update

Reagowanie na skany to połowa pętli; druga połowa to utrzymywanie samego paszportu w dokładnym stanie. Regulacje takie jak **ESPR (EU 2024/1781)** i **Rozporządzenie w sprawie baterii (EU 2023/1542)** oczekują, że dane paszportu będą odzwierciedlać rzeczywistość przez cały cykl życia produktu — przeliczony ślad węglowy, zaktualizowane instrukcje naprawy, osiągnięte cele dotyczące zawartości materiałów z recyklingu.

Napędzaj te aktualizacje z systemu zapisów (system of record). Gdy wartość zmienia się w Twoim systemie ERP, prześlij ją do paszportu:

```
import { QR3 } from "@qr3/sdk";

const client = new QR3({ apiKey: process.env.QR3_API_KEY! });

// GTIN and serial are immutable; data fields are updatable.
await client.dpp.update(dppId, {
  battery_data: { carbon_footprint_kg: 58, recycled_content_pct: 16 },
});
```

Ponieważ kod QR koduje stabilny adres URL resolvera (`https://qr3.app/dpp/{gtin}/{serial}`, dodaj `?format=jsonld` dla JSON-LD), nigdy nie drukujesz ponownie etykiety, aby zmienić dane. Tożsamość pozostaje stała; treść za nią pozostaje aktualna. Połącz to z `qr.updated`, a możesz rozesłać powiadomienie za każdym razem, gdy paszport się zmienia — zamykając pętlę między Twoim systemem ERP, paszportem i każdym, kto obserwuje w dole łańcucha.

## Tabela zdarzeń: zdarzenie → co zautomatyzować

| Zdarzenie | Uruchamia się, gdy | Co zautomatyzować |
| --- | --- | --- |
| `qr.scanned` | Kod QR produktu zostaje zeskanowany w terenie | Analityka według kraju, sygnały uzupełniania, alerty wycofania |
| `qr.created` | Tworzony jest nowy paszport | Zaindeksuj go, zsynchronizuj z PIM/ERP, powiadom zespół katalogowy |
| `qr.updated` | Zmieniają się dane paszportu | Ponownie zbuforuj publiczną stronę, roześlij powiadomienia o zmianach |
| `qr.deleted` | Paszport zostaje usunięty | Oznacz rekordy wewnętrzne jako nagrobki (tombstone), wycofaj odniesienia w dole łańcucha |

Zacznij od `qr.scanned` dla zaangażowania i sygnałów terenowych; dodaj zdarzenia cyklu życia w miarę synchronizowania paszportów z szerszymi systemami.

## FAQ

**Czy muszę weryfikować sygnaturę, jeśli mój adres URL punktu końcowego jest tajny?**
Tak. Adres URL nie jest sekretem — wycieka w logach, serwerach proxy i historii przeglądarki. Sprawdzenie HMAC w nagłówku `X-QR3-Signature` pod kątem surowej treści (raw body) to jedyna rzecz, która udowadnia, że payload faktycznie pochodzi z qr3.

**Co się stanie, jeśli mój punkt końcowy będzie niedostępny, gdy uruchomi się zdarzenie?**
Potwierdź szybko za pomocą `200`, gdy tylko zweryfikujesz, i wykonuj powolną pracę asynchronicznie, aby przejściowe problemy w dole łańcucha nigdy nie blokowały odpowiedzi. Utrzymuj własną idempotencję na identyfikatorze dpp/code, aby ponowiona dostawa nie była liczona podwójnie.

**Czy mogę zaktualizować GTIN lub numer seryjny za pomocą client.dpp.update?**
Nie — GTIN i numer seryjny są niezmienne; stanowią stabilną tożsamość produktu. Aktualizowalne są tylko pola danych. Ta niezmienność to dokładnie to, co pozwala wydrukowanemu kodowi QR pozostać ważnym na zawsze.

## Źródła

- [EU ESPR — Regulation (EU) 2024/1781](https://eur-lex.europa.eu/eli/reg/2024/1781/oj)

- [EU Battery Regulation 2023/1542](https://eur-lex.europa.eu/eli/reg/2023/1542/oj)

- [HMAC — RFC 2104](https://www.rfc-editor.org/rfc/rfc2104)

**Zacznij za darmo** i podłącz swój pierwszy webhook DPP: [app.qr3.app/sign-up](https://app.qr3.app/sign-up)

## Powiązane artykuły

- [![](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/gs1-resolver-test-suite-dpp-links/hero.png) Poradniki Pakiet testów Resolvera GS1: DPP-Linki — rzetelna weryfikacja przed uruchomieniem produkcyjnym Stabilny pakiet testów GS1 umożliwia weryfikację Resolvera 1.2. Sprawdź przekierowania, zestawy linków, CORS, języki i przypadki błędów przed uruchomieniem produkcyjnym.](/pl/blog/gs1-resolver-test-suite-dpp-links/)
- [![](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/dpp-battery-passport-2027-20260715/hero.png) Wiadomości branżowe BatteryPass-Ready uruchamia środowisko testowe dla Cyfrowego Paszportu Baterii Konsorcjum BatteryPass-Ready uruchomiło 24 czerwca 2026 r. publiczne środowisko testowe dla Cyfrowego Paszportu Baterii, z myślą o obowiązku UE od lutego 2027 r.](/pl/blog/dpp-battery-passport-2027-20260715/)
- [![](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/sector-20260713/hero.png) Wiadomości branżowe Cyfrowy paszport baterii 2027: co producenci muszą wiedzieć już teraz Webinary, narzędzia open source i nowe normy: unijny paszport baterii nabiera tempa. Przegląd sytuacji w lipcu 2026 r. i otwartych kwestii do lutego 2027 r.](/pl/blog/sector-20260713/)
- [![](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/sector-20260711/hero.png) Wiadomości branżowe Cyfrowy paszport baterii 2026: środowiska testowe, normy i otwarte pytania Jak przemysł radzi sobie z Cyfrowym Paszportem Baterii? Przegląd środowisk testowych, norm CEN/CENELEC, narzędzi open source i zmian regulacyjnych w lipcu 2026 r.](/pl/blog/sector-20260711/)

[← Wszystkie artykuły](/pl/blog/) [Zacznij za darmo](https://app.qr3.app/sign-up)