Programozott hozzáférés a termékútlevelekhez — webshop/ERP-szinkronhoz, tömeges automatizáláshoz.

Pro csomagtól

A nyílt béta alatt az API minden béta-fióknak elérhető — a Pro-korlát a béta után lép életbe.

Hitelesítés

Minden kérés API-kulccsal hitelesít, Authorization fejlécben:

Authorization: Bearer vk_<a kulcsod>

Kulcsot a Beállítások → Fejlesztői API alatt hozol létre. A nyílt kulcsot csak egyszer, létrehozáskor mutatjuk meg — tárold biztonságos helyen. A kulcs a teljes fiókod termékeihez ad írási/olvasási hozzáférést, ezért kezeld titkosan.

Gyors teszt böngészőben

A kulcs kizárólag az Authorization fejlécben megy — biztonsági okból nem URL-paraméterként (az bekerülne a böngésző-előzménybe és a szerver-logokba). Próbáld ki például curl-lel:

curl -H "Authorization: Bearer vk_<a kulcsod>" https://veridyn.eu/api/v1/categories

Kulcs-hatókör (scope)

Kulcs létrehozásakor hatókört választasz: Teljes (olvasás + írás) vagy Csak olvasás (read-only). A read-only kulcs kizárólag GET-et hívhat — POST/PATCH/DELETE esetén a válasz 403 read_only. ERP- vagy megjelenítő-integrációhoz használj read-only kulcsot.

Kérés-korlát (rate limit)

Kulcsonként, csomagtól függően 120–600 kérés / perc (Pro 120 · Business 300 · Enterprise 600; a nyílt béta alatt 300). Minden válasz tartalmazza az X-RateLimit-Limit, X-RateLimit-Remaining és X-RateLimit-Reset (unix idő) fejléceket. A limit átlépésekor a válasz 429 rate_limited, Retry-After fejléccel — várd meg a jelzett időt, majd próbáld újra.

Idempotencia

A POST kérésekhez adhatsz egy egyedi Idempotency-Key fejlécet. Ha ugyanazzal a kulccsal újraküldöd (pl. hálózati hiba után), a korábbi választ kapod vissza — nem jön létre duplikátum. A visszajátszott választ az Idempotency-Replayed: true fejléc jelzi.

OpenAPI

Gépi olvasható API-leírás (OpenAPI 3.1) — Postman-importhoz, SDK-/kód-generáláshoz:

https://veridyn.eu/api/v1/openapi.json

⚡ Interaktív API-referencia

Böngészhető, kereshető végpont-referencia — közvetlenül a fenti specből renderelve.

DPP-szótár (JSON-LD névtér)

A publikus útlevél gépi változata JSON-LD: a szabványos mezők schema.org-ról jönnek, a DPP-specifikus mezők pedig a dpp: névtérből. Ez a névtér feloldható — megnyitva megnézheted, mit jelent minden mező, Accept: application/ld+json fejléccel pedig a gépi @context dokumentumot adja.

https://veridyn.eu/ns/dpp/v1/

Egy útlevél gépi változata: a publikus URL ?format=jsonld paraméterrel (vagy Accept: application/ld+json fejléccel).

Postman-kollekció

Kész, importálható gyűjtemény (előre beállított változókkal + példa-kérésekkel). Import után csak töltsd ki a base_url és api_key gyűjtemény-változókat.

⬇ Postman-kollekció letöltése

Generálj saját SDK-t

Az OpenAPI-specből bármely nyelvre generálhatsz hivatalos klienst az openapi-generator-ral — nincs kézzel karbantartott SDK, mindig naprakész. Pl. PHP:

npx @openapitools/openapi-generator-cli generate \
  -i https://veridyn.eu/api/v1/openapi.json \
  -g php -o ./veridyn-sdk

A -g értéke lehet typescript-fetch, python, java és sok más.

Gyorsindító (kód)

PHP

$ch = curl_init('https://veridyn.eu/api/v1/products?limit=5');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => ['Authorization: Bearer vk_...'],
]);
$products = json_decode(curl_exec($ch), true)['data'];

JavaScript (fetch)

const res = await fetch('https://veridyn.eu/api/v1/products?limit=5', {
  headers: { 'Authorization': 'Bearer vk_...' }
});
const { data } = await res.json();

Alap-URL

https://veridyn.eu/api/v1

A válaszok application/json formátumúak, UTF-8 kódolással.

Sandbox (teszt-fiók)

Integrációt nem az éles fiókon szokás fejleszteni. A Beállítások → Sandbox alatt kérhetsz egy külön teszt-fiókot saját API-kulccsal: ugyanaz az API, ugyanazok a sémák, de az éles adatoktól teljesen elszigetelve.

• Ugyanaz az alap-URL és hitelesítés — csak a kulcs más. A kód, amit a sandboxban megírsz, változtatás nélkül megy élesben.
• A teszt-útlevelek jelöltek: a lapon TESZT sáv, a fejben noindex — próbaadat nem kerülhet a keresőbe valódi termékútlevélként.
• Jogi hatású kimenő hívás innen nem indul: sem uniós regiszter-bejelentés, sem mentés a szolgáltatódhoz. Webhook viszont megy — épp azért, hogy a saját teszt-végpontodon lásd a működést.
• A teszt-adat üríthető egy gombbal (a kulcsok megmaradnak), így minden próba tiszta lappal indulhat.
• A sandbox a fiókod csomagját tükrözi — amit élesben tudsz, azt tudod a tesztben is.

Végpontok

Metódus	Útvonal	Leírás
GET	/categories	Elérhető termékkategóriák.
GET	/schema/{category}	A kategória teljes mezőlistája — kötelező + opcionális, típus, enum, nyelvi mezők.
GET	/products	Termékek listája (összefoglaló). Paraméterek: q, status, page, limit — illetve updated_since és cursor a csak-a-változások szinkronhoz.
POST	/products	Új termékútlevél. Törzs: { category, data }.
POST	/products:batch	Tömeges létrehozás — legfeljebb 500 termék egy kérésben. Törzs: { category, products: [ … ], on_duplicate? }. Soronkénti riportot ad.
GET	/products/{id}	Egy termék teljes adata + passport-URL.
PATCH	/products/{id}	Frissítés (részleges) — új verziót hoz létre. Törzs: { data, change_type? }. A change_type opcionális: correction (a modellen volt rossz adat → a már kiadott tétel-/darab-útlevelek elavulnak, frissíthetők) vagy change (a termék változott adott dátumtól → a korábbi darabok adata helyes marad, nem írjuk felül).
GET	/products/{id}/qr	QR-kód (SVG) a publikus passporthoz.
GET	/events	A kimenő webhook-események története (?after_id= & limit=) — duplikátum-szűréshez és kimaradt események pótlásához.
GET	/products/{id}/children	A tétel/egység gyerek-útlevelek listája.
POST	/products/{id}/children	Tétel/egység útlevél. Egy: { level, lot|serial, data } · tömeges: { level, items:[…] } (max 500). Örökli a szülő adatait.
PATCH	/products/{id}/children	Gyerek-útlevelek tömeges frissítése (max 500): { items:[{ serial|lot|id, data }] }. Élő BMS-adathoz — soronkénti riporttal.
POST	/products/{id}/archive /products/{id}/restore	Archiválás és visszaállítás. Szándékosan nem PATCH: a láthatóság-váltás nem adat-változás, ezért nem gyárt üres verziót a változás-történetbe. Törzs nem kell.
GET	/products/{id}/versions /products/{id}/versions/{no}	A változás-történet: a verziók listája, illetve egy adott verzió mező-szintű különbsége (mi változott, miről mire).
GET POST DELETE	/products/{id}/grants /products/{id}/grants/{gid}	Lejáró hozzáférési linkek hatóságnak / jogos érdekű félnek — a bizalmas mezőkhöz bejelentkezés nélkül. DELETE visszavon.
GET POST DELETE	/products/{id}/documents /products/{id}/documents/{docId}	Tanúsítványok és dokumentumok. Feltöltés base64-ben (PDF, PNG, JPEG, WebP), letöltés a fájllal, törlés. A darab-azonosítós GET a fájlt adja, nem JSON-t.
GET POST	/supplier-requests	Beszállítói adatbekérések: lista és indítás. A válasz tartalmazza a beszállítói linket.
GET POST DELETE	/supplier-requests/{rid} /supplier-requests/{rid}/merge	Egy adatbekérés a beküldött értékekkel, a beküldés beolvasztása (új termék-verzió), illetve visszavonás.
POST	/eo/token	Rövid életű JWT a szabvány szerinti gazdasági-szereplő felülethez. Törzs: { ttl? }.
GET	/products/{id}/scans	Termék-szintű beolvasás-összegző: total, unique, byCountry, byDevice. Paraméter: days=7|30|90|365.
GET	/products/{id}/batterypass	Az akkumulátor-útlevél CEN-CENELEC JTC24 (BatteryPass) alakban. Paraméter: profile=feb27|full — a feb27 a 2027-02-18-tól kötelező szűkebb halmaz, a full a teljes adatmodell. Csak battery kategóriára.
GET	/scans	Bérlő-szintű beolvasás-összegző: a fentiek + byCategory, byLevel.

Mit kell megadni? (kötelező vs. opcionális)

Minden kategóriának van egy kötelező magja — enélkül a séma-validáció elutasít (422). Minden más mező opcionális, de bármikor beküldheted ugyanabban a data objektumban (több adat = jobb passport + jövőbiztosabb megfelelés). A pontos, gépi mezőlistát a /schema/{category} adja — required: true/false, típus, enum és localized jelöléssel.

curl https://veridyn.eu/api/v1/schema/textile \
  -H "Authorization: Bearer vk_<kulcs>"

Összes mező kategóriánként

✓ = kötelező · — = opcionális · ↳ beágyazott al-mező · 🌐 nyelvenkénti (localized) · 🔒 csak hatósági szinten látszik. Ez a lista a sémából generálódik — mindig naprakész.

Nyelvek

A languages (pl. ["hu","en"]) deklarálja, mely nyelveken van szabad-szöveges tartalom. A lokalizált mezőket (ápolás, életciklus… — a /schema-ban "localized": true) csak az első (elsődleges) nyelven kötelező kitölteni; a többi opcionális, hiánynál egy elérhető nyelvre esik vissza. A passport UI-címkéi ettől függetlenül automatikusan 24 nyelvre fordulnak.

Példák

Tömeges betöltés az ERP-ből

curl -X POST https://veridyn.eu/api/v1/products:batch   -H "Authorization: Bearer vk_<kulcs>"   -H "Content-Type: application/json"   -H "Idempotency-Key: erp-2026-09-24-001"   -d '{
    "category": "battery",
    "on_duplicate": "skip",
    "products": [
      { "sku": "VE60-001", "productName": "PowerCell 60", "...": "..." },
      { "sku": "VE60-002", "productName": "PowerCell 60 XL", "...": "..." }
    ]
  }'

A válasz soronkénti riport: created / updated / exists (ilyen SKU már van) / invalid (a hibákkal) / plan_limit. A részleges siker normális — a hibás sor nem állítja meg a többit.

Az Idempotency-Key fejléc mentesít az újrapróbálás kockázatától: időtúllépés után ugyanazzal a kulccsal megismételt kérés a korábbi választ adja vissza, nem hoz létre másodszor semmit.

Termék létrehozása

curl -X POST https://veridyn.eu/api/v1/products \
  -H "Authorization: Bearer vk_<kulcs>" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "textile",
    "data": {
      "productName": "Bio pamut póló",
      "sku": "TEE-001",
      "brandName": "Lumora",
      "languages": ["hu","en"],
      "fiberComposition": [{"fiber":"pamut","percentage":100}],
      "countryOfManufacture": "PT",
      "careInstructions": {"hu":"Mosás 30 °C","en":"Wash at 30 °C"},
      "repair": {"repairable": true, "sparePartsAvailable": false},
      "endOfLife": {
        "recyclingInstructions": {"hu":"Textilgyűjtő","en":"Textile bin"},
        "disposalInstructions": {"hu":"Ne a kukába","en":"Not household waste"}
      },
      "economicOperator": {
        "role":"manufacturer","legalName":"Lumora Kft.","address":"Budapest",
        "country":"HU","contactEmail":"[email protected]"
      }
    }
  }'

Válasz (201):

{
  "data": {
    "id": "a1993ef7-7562-43bb-92ff-eb63f02dcde9",
    "category": "textile",
    "status": "active",
    "version_no": 1,
    "passport_url": "https://veridyn.eu/<fiók>/p/a1993ef7-…",
    "qr_url": "https://veridyn.eu/api/v1/products/a1993ef7-…/qr",
    "data": { "productName": "Bio pamut póló", … }
  }
}

Listázás

curl https://veridyn.eu/api/v1/products?limit=25 \
  -H "Authorization: Bearer vk_<kulcs>"

Egy termék lekérése

curl https://veridyn.eu/api/v1/products/{id} \
  -H "Authorization: Bearer vk_<kulcs>"

Frissítés (új verzió)

curl -X PATCH https://veridyn.eu/api/v1/products/{id} \
  -H "Authorization: Bearer vk_<kulcs>" \
  -H "Content-Type: application/json" \
  -d '{"data": {"recycledContentPercentage": 30}}'

A megadott mezők ráolvasnak a meglévő adatra (részleges frissítés), majd validálunk, és új, megőrzött verzió jön létre — a teljes változás-történet megmarad.

Tétel és egység útlevél (szerializálás)

Egy modell alá tétel- vagy egyed-útlevelet készítesz; a gyerek örökli a szülő adatait — csak a példány-specifikus mezőket (lot/serial) adod meg. Egyszerre több is (items[], max 500), a válasz soronként jelzi a sikert/hibát.

curl -X POST https://veridyn.eu/api/v1/products/{id}/children \
  -H "Authorization: Bearer vk_<kulcs>" \
  -H "Content-Type: application/json" \
  -d '{"level":"item","items":[{"serial":"SN-0001"},{"serial":"SN-0002"}]}'

A {id} lehet modell vagy tétel is. Ha egy tétel id-jére POST-olsz level:"item"-mel, a darab a tétel alá kerül, és a tétel lot-ját örökli — a GS1-linkje ilyenkor …/10/lot/21/serial, nem …/21/serial. Így épül a teljes modell → tétel → egység lánc.

Élő adat visszaírása tömegesen

A darab-szintű mezők egy része élő adat: az akkumulátor SoH-ja, ciklusszáma és maradék kapacitása a BMS-ből frissül. Ezt nem darabonként kell visszaírni — egy hívásból legfeljebb 500 gyerek-útlevél frissül. Az azonosítás serial, lot vagy id alapján megy, tehát elég az, amit a gyártásirányítás ismer; a mi belső azonosítónkat nem kell eltárolnod.

curl -X PATCH https://veridyn.eu/api/v1/products/{id}/children \
  -H "Authorization: Bearer vk_<kulcs>" \
  -H "Content-Type: application/json" \
  -d '{"change_type":"change","items":[
        {"serial":"SN-0001","data":{"stateOfHealth":97,"fullCycleCount":412}},
        {"serial":"SN-0002","data":{"stateOfHealth":95,"fullCycleCount":508}}
      ]}'

A válasz soronkénti riport: updated · unchanged · not_found · ambiguous (a sorozatszám nem egyedi a szülő alatt) · validation. A változatlan sorból nem lesz új verzió — egy naponta futó flotta-szinkron így nem hizlalja üres verziókkal a változás-történetet. A change_type az egész kötegre vonatkozik: a BMS-adat frissülése change (a korábbi érték a maga idejében igaz volt), nem correction.

Beolvasás-analitika (scan)

A QR-beolvasások összesített statisztikája — termékenként vagy az egész fiókra —, országra és eszközre bontva. Adatvédelem: nyers IP nincs, az egyedi látogató anonim hash-becslés.

curl "https://veridyn.eu/api/v1/products/{id}/scans?days=30" \
  -H "Authorization: Bearer vk_<kulcs>"

{
  "data": {
    "product_id": "a1993ef7-…",
    "range_days": 30,
    "total": 189, "unique": 142,
    "byCountry": { "HU": 142, "DE": 38, "AT": 9 },
    "byDevice":  { "mobile": 168, "tablet": 9, "desktop": 12 }
  }
}

Inkrementális szinkron (csak a változások)

Egy ERP nem tudja minden éjszaka végigolvasni a teljes útlevél-állományt: ahogy nő a katalógus, úgy nő a futásidő is. Az updated_since paraméterrel csak azt kapod vissza, ami az adott időpont óta változott — és a lista ilyenkor minden szintet ad (modell, tétel, egyed), mert egy gyártásirányítás a darab-útleveleket is szinkronizálja.

curl "https://veridyn.eu/api/v1/products?updated_since=2026-09-24T00:00:00Z&limit=100" \
  -H "Authorization: Bearer vk_<kulcs>"

{
  "data": [
    { "id": "a1993ef7-…", "name": "VE60 EV modul", "status": "active",
      "updated_at": "2026-09-24T08:11:32+00:00", "passport_url": "…" },
    { "id": "c7d10b42-…", "name": "VE60-000418", "status": "archived",
      "updated_at": "2026-09-24T14:02:07+00:00", "passport_url": "…" }
  ],
  "per_page": 100,
  "has_more": true,
  "next_cursor": "MjAyNi0wOS0yNCAxNDowMjowN3xjN2QxMGI0Mi0…"
}

A szinkron-válaszban nincs page és total — helyettük has_more és next_cursor van. A következő lapot a kapott next_cursor változtatás nélküli visszaadásával kéred: ?cursor=…. A kurzor opak: ne fejtsd meg és ne állítsd össze magad — a saját gyártmányú értéket 422 bad_cursor hibával elutasítjuk.

curl "https://veridyn.eu/api/v1/products?cursor=MjAyNi0wOS0yNCAxNDowMjowN3xjN2QxMGI0Mi0…" \
  -H "Authorization: Bearer vk_<kulcs>"

Miért kurzor, és nem oldalszám

Mert az oldalszámos lapozás némán kihagy sorokat. A lista a módosítás ideje szerint áll: amíg te a 2. lapot kérdezed, egy már látott termék frissül, a lista élére ugrik, és minden mögötte lévő eggyel hátracsúszik — az a sor, ami épp a lapok határán volt, soha nem kerül a szemed elé. A kliens közben azt hiszi, mindent megkapott. A kurzor a konkrét utolsó feldolgozott sorra mutat, nem egy pozícióra, ezért ez nem fordulhat elő. (Azonos másodpercre eső időbélyegeknél a belső azonosító dönt — importnál ez tucatnyi soron előfordul.)

Az archivált útlevél is megjelenik — ez a lényeg

Az archiválás nem tünteti el a terméket a szinkron-ablakból: status: "archived" értékkel jön vissza. Ez a „sírkő" — ebből tudja a rendszered, hogy le kell vennie a saját listájáról. Ha az archiváltak kiesnének, a kliens örökre aktívként tartaná őket.

Ajánlott menet: tárold el a legutolsó next_cursor-t; a következő futásnál azzal indulsz, és addig lapozol, amíg a has_more hamis nem lesz. Első (teljes) feltöltésnél updated_since=1970-01-01T00:00:00Z — onnantól már csak a változás megy át a vonalon.

Két dolog, amire a kliensnek számítania kell

1. A legfrissebb másodperc még nem jön. A módosítási időbélyeg másodperc-felbontású, ezért a lista mindig csak a már zárt másodpercekig szolgál ki: egy épp most mentett útlevél jellemzően 1–2 másodperc múlva jelenik meg a szinkron-listán. Ez szándékos. Enélkül előfordulhatna, hogy a kurzor belelép egy még nyitott másodpercbe, és az abban a másodpercben később mentett útlevél soha nem kerülne ki — nem késne, hanem elveszne, és nem is derülne ki.

2. Üres lapot is kurzorral kapsz. Ha nem változott semmi, a data üres, a has_more hamis — de a next_cursor akkor sem üres, és előrébb áll, mint az előző. Mindig azt tárold el: a kurzor akkor is halad, amikor nincs változás.

Tanúsítványok és dokumentumok

A megfelelőségi tanúsítvány, a vizsgálati jegyzőkönyv és a biztonsági adatlap PDF-ben él — és jellemzően egy dokumentumkezelőben vagy a laborral folytatott levelezésben keletkezik, nem egy böngésző-fülben. A fájl tartalma ezért base64-ben megy a kérés törzsében:

curl -X POST https://veridyn.eu/api/v1/products/{id}/documents \
  -H "Authorization: Bearer vk_<kulcs>" \
  -H "Content-Type: application/json" \
  -d '{"filename":"ce-tanusitvany.pdf","tier":"public","label":"CE","content_base64":"JVBERi0xLjQK…"}'

A típust a tartalom dönti el, nem a fájlnév. A kiterjesztés hazudhat — és aki szándékosan hazudik vele, annak épp ez a célja —, ezért a bájtokból ismerjük fel a fájltípust. Ha nem PDF, PNG, JPEG vagy WebP, a válasz 415 bad_type, és semmi nem tárolódik. A tárolt fájl neve a mi azonosítónk; a beküldött filename csak megjelenítendő címke.

A tier mondja meg, ki láthatja: public (a publikus útlevélen is), legitimate_interest vagy authorities — ugyanaz a rangsor, mint a séma-mezőké. Ismeretlen érték esetén a legszűkebbre, a public-ra esik; a bizalmas dokumentumnál tehát mindig add meg.

A méret-korlát 8 MB a dekódolt fájlra. A base64 a kérés törzsét ennél nagyobbá teszi (kb. 4/3-szorosára), és ha az a szerver törzs-korlátját túllépi, a törzs meg sem érkezik — erre 413 payload_too_large a válasz, és megmondjuk benne a szerver tényleges korlátját is, hogy ne a saját kódodban keresd a hibát.

A tényleges maximumot meg is tudod kérdezni, mielőtt bármit feltöltenél: a GET /health (kulcs nélkül is működik) limits.document_upload_max_bytes mezője azt a számot adja, ami a kettőből a szűkebb. Érdemes indulásnál egyszer elkérni.

curl https://veridyn.eu/api/v1/health

{
  "status": "ok",
  "limits": {
    "document_max_bytes": 8388608,
    "request_body_max_bytes": 8388608,
    "document_upload_max_bytes": 6165626,
    "bulk_max_items": 500
  }
}

A letöltés a fájlt adja vissza, nem JSON-t — a saját tartalom-típusával; a ?dl=1 csatolmányként. A DELETE a lemezről is törli.

curl https://veridyn.eu/api/v1/products/{id}/documents/42?dl=1 \
  -H "Authorization: Bearer vk_<kulcs>" -o tanusitvany.pdf

Beszállítói adatbekérés

Az útlevél adatainak egy részét nem te tudod: a szövet rost-összetételét a szövöde, a cellák eredetét a cellagyártó. Adatbekérést indítasz a konkrét mezőkre, a beszállító pedig egy belépés nélküli linken kitölti a saját részét — fiókot nem kell neki adnod. Ez a felületen régóta megvan; API-ból eddig nem: egy beszerzési rendszer így 500 útlevelet fel tudott tölteni, de az 500 adatbekérést kézzel kellett elindítani.

curl -X POST https://veridyn.eu/api/v1/supplier-requests \
  -H "Authorization: Bearer vk_<kulcs>" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"a1993ef7-…","email":"[email protected]",
       "fields":["fiberComposition","countryOfManufacture"],
       "message":"Kérlek, a következő szállítmányhoz.","lang":"en"}'

{
  "data": {
    "id": 17, "status": "pending", "email": "[email protected]",
    "fields": ["fiberComposition", "countryOfManufacture"],
    "expires_at": "2026-10-25 09:14:02",
    "link": "https://veridyn.eu/supplier.php?token=9f3c…",
    "emailed": true
  }
}

A link mindig benne van a válaszban — akkor is, ha az e-mailt mi küldjük ki. Egy gépi integráció jellemzően a saját levelezőjéből ír a beszállítónak (saját sablon, saját feladó, saját nyomonkövetés); ilyenkor a send_email: false kikapcsolja a mi kiküldésünket, és a linket te küldöd el. A fields a kategória-séma mezőkulcsai (GET /schema/{category}); belső mező nem delegálható. A link 30 nap után lejár.

A beküldés átnézése és beolvasztása

Amíg a beszállító nem töltött ki semmit, az adatbekérés pending. Beküldés után submitted, és a részletek végpontján látod, mit írt — nyers mezőkulccsal és emberi mezőnévvel együtt, hogy a jóváhagyó felületnek ne kelljen ismernie a sémát. A beolvasztás külön lépés: a beérkezett adat nem kerül automatikusan a termékbe.

curl https://veridyn.eu/api/v1/supplier-requests/17 \
  -H "Authorization: Bearer vk_<kulcs>"

curl -X POST https://veridyn.eu/api/v1/supplier-requests/17/merge \
  -H "Authorization: Bearer vk_<kulcs>"

A beolvasztás csak a KÉRT mezőket írja át. A beszállító (vagy a token ismeretében bárki) beküldhet többet is, de amit nem kértél tőle, az nem nyúl a termékhez — a márkanevet nem írhatja át az, akitől csak a gyártás országát kérdezted.

Ha a beolvasztott adat érvénytelen (422 validation), a termék érintetlen marad, és az adatbekérés sem záródik le: tisztázod a beszállítóval, majd újra megpróbálod. Siker esetén új verzió keletkezik, és product.updated webhook megy ki source: "supplier_merge" jelzéssel — így a saját rendszeredben látszik, hogy nem te írtad át, hanem egy beküldés.

Archiválás és visszaállítás

Ha egy termék kifut, archiválod — de az útlevelet nem töröljük: a QR-kód és a link ezután is működik, az útlevél „archivált" jelöléssel jelenik meg. Ezt a jogszabályi megőrzés meg is kívánja: egy már piacon lévő darab útlevelének élnie kell akkor is, amikor a modellt már nem gyártod.

curl -X POST https://veridyn.eu/api/v1/products/{id}/archive \
  -H "Authorization: Bearer vk_<kulcs>"

curl -X POST https://veridyn.eu/api/v1/products/{id}/restore \
  -H "Authorization: Bearer vk_<kulcs>"

Törzs nem kell. A művelet nem hoz létre új verziót: a láthatóság-váltás nem adat-változás, egy üres különbségű verzió csak zajt vinne a változás-történetbe — ezért is külön végpont, és nem PATCH. Webhookot kiváltunk: product.archived, illetve product.restored.

A keretet nem szabadítja fel: a csomag modell-számlálója az archiváltakat is beleszámolja, tehát az archiválás nem nyit helyet újnak, és a visszaállítás nem is foglal.

Változás-történet (verziók)

Minden PATCH új, megőrzött verziót hoz létre, és a lánc hash-sel pecsételt — utólag nem írható át. A történet gépileg is olvasható: a lista a verziókat adja, a /versions/{no} pedig azt, hogy melyik mező változott, miről mire.

curl https://veridyn.eu/api/v1/products/{id}/versions \
  -H "Authorization: Bearer vk_<kulcs>"

curl https://veridyn.eu/api/v1/products/{id}/versions/3 \
  -H "Authorization: Bearer vk_<kulcs>"

Mindkettő olvasás, tehát csak-olvasó kulccsal is megy — egy auditáló rendszernek nem kell írási jogot adnod. A change_type is látszik: a correction hibás adat javítása (a már kiadott darab-útlevelek elavulnak), a change pedig valós termék-változás adott dátumtól (a korábbi darabok adata helyes marad).

Hozzáférési linkek (hatóság, jogos érdekű fél)

A publikus útlevél a nyilvános mezőket mutatja. A rendelet viszont szélesebb hozzáférést ír elő a piacfelügyeleti hatóságnak és a jogos érdekű feleknek (pl. újrahasznosító, javító). Erre valók a lejáró hozzáférési linkek: bejelentkezés nélkül nyitnak, egyetlen útlevélre, és lejáratkor maguktól elnémulnak — nem kell fiókot osztogatnod.

curl -X POST https://veridyn.eu/api/v1/products/{id}/grants \
  -H "Authorization: Bearer vk_<kulcs>" \
  -H "Content-Type: application/json" \
  -d '{"tier":"authority","label":"NKFH 2026/114","expires_in_days":30}'

{
  "data": {
    "id": 42, "tier": "authority", "label": "NKFH 2026/114",
    "status": "active", "expires_at": "2026-10-25 09:14:02",
    "use_count": 0, "last_used_at": null,
    "token": "9f3c…",
    "passport_url": "https://veridyn.eu/acme/p/a1993ef7-…?grant=9f3c…",
    "history_url":  "https://veridyn.eu/history.php?id=a1993ef7-…&grant=9f3c…"
  }
}

Mező	Jelentés
tier	legitimate_interest vagy authority. Más szinttel nem adható ki link (422 bad_tier): a tulajdonosi szint a saját fiókod, azt nem lehet linkkel kiosztani.
expires_in_days	Opcionális — és a hiánya örök linket jelent. Egy hatósági vizsgálat véges, ezért érdemes mindig megadni; lejárat után a link 410-et ad.
label	Szabad szöveg: kinek adtad ki. Csak neked látszik, a linket kapó fél nem látja.
history_url	Csak authority szinten van kitöltve: a hatóság a teljes változás-történetet is megnyithatja, a jogos érdekű fél nem.
use_count	Hányszor nyitották meg. Egy frissen kiadott link mindig 0 — a kiadás nem számít felhasználásnak.

A GET az adott útlevél élő linkjeit listázza, a DELETE /products/{id}/grants/{gid} pedig azonnal visszavon egyet — a token ezután 410-et ad.

Séma-verzió: mikor kell hozzányúlnod az integrációhoz

A termékkategóriák mezőlistája a jogszabállyal együtt mozog. Eddig semmi nem jelezte, ha egy séma megváltozott — az integrációk némán romlottak el. A GET /schema/{category} ezért verziót és ETag-et ad:

curl -i https://veridyn.eu/api/v1/schema/battery \
  -H "Authorization: Bearer vk_<kulcs>"

HTTP/1.1 200 OK
ETag: "battery.1.0.02894917d482"
X-DPP-Schema-Version: 1.0
Cache-Control: public, max-age=3600

Az ETag a gépi szerződésből áll: a mezők nevéből, típusából, kötelezőségéből, enum-értékeikből és hozzáférési szintjükből. Amit tehát nem változtat meg: a címke, a súgószöveg, a fordítás. Így nem kapsz vaklármát attól, hogy egy mező magyar megnevezése pontosabb lett.

curl -i https://veridyn.eu/api/v1/schema/battery \
  -H "Authorization: Bearer vk_<kulcs>" \
  -H 'If-None-Match: "battery.1.0.02894917d482"'

HTTP/1.1 304 Not Modified

Tedd be az ETag-et az indító-szkriptedbe vagy a napi futásba: amíg 304-et kapsz, a szerződés áll, és nincs dolgod. Ha 200 jön, a válasz version, revised és contract_hash mezőiből látszik, mi mozdult.

Ha egy kategórián visszafelé nem kompatibilis váltás van készülőben, a válasz Deprecation és Sunset fejlécet is kap (RFC 8594), a Sunset pedig a legkorábbi dátum, amikor a régi alak megszűnik. Alaphelyzetben egyik fejléc sem jelenik meg — ha látod, akkor van valódi határidőd.

Válasz & hibák

Siker: a hasznos adat a data kulcs alatt. Hiba esetén:

{ "error": "Érvénytelen adatok.", "code": "validation", "errors": [ … ] }

HTTP	code	Jelentés
401	unauthorized	Hiányzó/érvénytelen API-kulcs.
403	plan_required	Az API a Pro csomagtól érhető el (a nyílt béta alatt minden béta-fiók használhatja).
404	not_found	Nincs ilyen termék / útvonal.
409	gtin_taken	A GTIN már foglalt.
422	gtin_not_yours	A GTIN nem a fiókod GS1 cégprefixébe esik (Beállítások → GS1 cégprefix). Csak akkor fordulhat elő, ha beállítottál cégprefixet.
403	plan_limit	Elérted a szint keretét (csomag + extra). Tömeges hívásnál a túllógó elemek errors-ba kerülnek.
422	validation	Érvénytelen adat (részletek az errors-ban).
403	read_only	Csak olvasásra jogosult kulccsal próbáltál írni (POST/PATCH/DELETE).
429	rate_limited	Átlépted a percenkénti kérés-keretet. A Retry-After fejléc megmondja, mennyit kell várni.
400	bad_json	A kérés törzse nem érvényes JSON. Az API csak JSON törzset fogad (Content-Type: application/json).
413	too_big	A feltöltött dokumentum nagyobb a megengedettnél. A tényleges korlátot a GET /health limits.document_upload_max_bytes mondja meg.
413	payload_too_large	A kérés törzse meg sem érkezett — a kiszolgáló post_max_size korlátján fennakadt. Nem a JSON a hibás, hanem a méret.
422	bad_cursor	A cursor nem a tőlünk kapott next_cursor. Add vissza változtatás nélkül — a kurzor opak.
422	bad_tier	Ezzel a hozzáférési szinttel nem adható ki link (csak legitimate_interest és authority).
501	needs_migration	A szolgáltatás egy még nem aktivált adatbázis-frissítést igényel. Szándékosan hibázunk, nem adunk fél adatot — jelezd nekünk, és élesítjük.

BatteryPass gazdasági-szereplő API

A fenti /api/v1 a mi felületünk. Emellett üzemeltetünk egy szabvány szerinti felületet is: a CEN-CENELEC JTC 24 életciklus-API (EN 18222) „Digital Product Passport – Life Cycle API v1.1" végpontjait, azon a nyelven, ahogy az akkumulátor-ökoszisztéma többi szereplője beszél. Ezt akkor érdemes használni, ha a partnered szabványos integrációt vár, nem a mi API-nkat.

Megfelelőség: a felület a BatteryPass-Ready megfelelőségi suite mind a 11 tesztjén átmegy (olvasás azonosítóval és termékazonosítóval, adatelem-olvasás, hozzáférés-szűrés, visszavont útlevél, módosítás, attribútum hozzáadása és törlése, jogosultság-ellenőrzés, piacra hozatal). A vizsgálat élő rendszert tesztel, nem beküldött fájlt.

Alap-URL és hitelesítés

https://veridyn.eu/eo — hitelesítés: Authorization: Bearer {JWT}. A tokenben szerepkör van (public, purchaser, authority, economic_operator…), és a válasz mezőnként szűrődik hozzá — ugyanazzal a gépezettel, ami a publikus útlevelet is szűri. Írni csak a gazdasági szereplő tud.

Honnan van a token

A tokent a saját fejlesztői kulcsoddal kéred — nincs külön regisztráció:

curl -X POST https://veridyn.eu/api/v1/eo/token \
  -H "Authorization: Bearer vk_<kulcs>" \
  -H "Content-Type: application/json" \
  -d '{"ttl":3600}'

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs…",
    "token_type": "Bearer",
    "role": "economic_operator",
    "expires_in": 3600,
    "expires_at": "2026-09-25T11:14:02+00:00",
    "api_base": "https://veridyn.eu/eo"
  }
}

A token a kulcs fiókjára szól — a bérlőt szándékosan nem a kérésből vesszük, így nem lehet más fiók útlevelére szóló tokent kérni. Szerepkör csak economic_operator lehet: ez az „ez az én termékem" szerep. A authority vagy recycler más fél nevében szól, azt magának senki nem oszthatja ki — arra a lejáró hozzáférési linkek valók.

A ttl másodpercben, 5 perc és 24 óra között (alapértelmezés 1 óra). A plafon szándékos: a JWT önhordó, nincs feketelistánk, tehát egy elvesztett hosszú életű tokent nem tudnánk visszavonni. Rövid token + újrakérés a helyes minta. Csak-olvasó kulcsból nem születik token (403 read_only), mert a gazdasági szereplő szerepkör írásra is jogosít.

Metódus	Útvonal	Leírás
POST	/dpps	Új útlevél a beküldött JTC24-dokumentumból. Válasz: az azonosító (szöveg), 201.
GET	/dpps/{dppId}	Olvasás útlevél-azonosítóval.
PATCH	/dpps/{dppId}	Részleges módosítás (RFC 7396) — új verziót hoz létre. A null érték törli a mezőt.
DELETE	/dpps/{dppId}	Visszavonás. Az útlevél megmarad (a hatóság visszamenőleg is kérheti), de ezen a felületen 404.
GET/PATCH	/dpps/{dppId}/elements/{path}	Egy adatelem olvasása/módosítása, pontozott útvonallal.
GET/PATCH	/dpps/{dppId}/collections/{group}	Egy adatcsoport (pl. performanceAndDurability).
GET	/dppsByProductId/{productId}	Az aktív verzió termékazonosító alapján.
GET	/dppsByProductIdAndDate/{productId}	A megadott időpontban érvényes verzió. Paraméter: date.
POST	/dppsByProductIds	Tömeges azonosító-feloldás. Paraméterek: limit, cursor.

Biztonsági mentés és regiszter: az (EU) 2023/1542 szerint az útlevél adatait független szolgáltatónál is tárolni kell, a piacra hozatalt pedig be kell jelenteni. Ha a fiókhoz be van állítva mentés-szolgáltató, minden létrehozás és módosítás után automatikusan elmegy hozzá a másolat — a hívások nyoma visszakereshető.

Webhookok

A Beállítások → Webhookok alatt regisztrálsz egy HTTPS URL-t. Amikor egy termékútlevél létrejön / frissül / archiválódik, a Veridyn egy aláírt JSON-t POST-ol arra az URL-re — így a rendszered valós időben értesül, kérdezgetés nélkül.

Események

product.created · product.updated · product.archived · product.restored · children.updated · scan.milestone · scan.clone_suspected

A children.updated a gyerek-útlevelek tömeges frissítéséről szól, és szándékosan egyetlen, összesítő esemény — nem soronként egy. Adata: { parent_id, category, count, items }, ahol az items a ténylegesen megváltozott gyerek-útleveleket sorolja { id, serial, lot } alakban (a unchanged sorok nem kerülnek bele). A soronkénti indoklást a hívás válasza tartalmazza, nem a webhook — azt a hívó kapja meg, aki a frissítést indította.

A scan.milestone akkor jön, amikor egy termékútlevél beolvasás-száma átlép egy mérföldkövet (10, 50, 100, 250, 500, 1000, …) — pl. „az útleveledet 1000-szer nyitották meg". Adata: { product_id, count, milestone }.

A scan.clone_suspected lehetséges hamisítást jelez: egy egyedi (sorszámos) útlevelet szokatlanul sokszor és sok különböző országból/eszközről olvastak be — ez másolt QR-kódra utalhat. Adata: { product_id, count, countries, unique_devices }.

Kézbesítés

POST https://your-system.example/veridyn-webhook
Content-Type: application/json
X-Veridyn-Event: product.updated
X-Veridyn-Event-Id: evt_9f21c4a08b73d5e6f1a20c44
X-Veridyn-Timestamp: 2026-07-02T13:19:11+00:00
X-Veridyn-Signature: sha256=<hmac>

{
  "event_id": "evt_9f21c4a08b73d5e6f1a20c44",
  "event": "product.updated",
  "data": { "id": "a1993ef7-…", "category": "textile", "version_no": 2 },
  "sent_at": "2026-07-02T13:19:11+00:00"
}

Aláírás-ellenőrzés

Az X-Veridyn-Signature a nyers törzs HMAC-SHA256 aláírása a webhook secret-jével (a Beállításokban látod). Így ellenőrzöd — pl. PHP-ban:

$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_VERIDYN_SIGNATURE'] ?? '')) {
    http_response_code(401); exit; // érvénytelen aláírás
}

Válaszolj 2xx státusszal. Ha a kézbesítés sikertelen (nem 2xx / időtúllépés), automatikusan újrapróbáljuk exponenciális backoff-fal (kb. 1 perc → 5 perc → 30 perc → 2 óra → 6 óra, max 6 próbálkozás), tartós hiba esetén feladjuk (kb. 8,5 óra után). Az utolsó kézbesítés státusza a Beállításokban látszik, és onnan kézzel újraküldhető.

Duplikátum-szűrés és kimaradt események pótlása

Az újrapróbálkozás azt jelenti, hogy ugyanaz az esemény többször is megérkezhet — például ha a válaszod időtúllépésbe fut, de a feldolgozás nálad már lefutott. Ezért minden eseménynek van event_id-ja: tárold el a feldolgozottakat, és a már látott azonosítót dobd el. Egy tömeges children.updated eseménynél ez különösen számít, mert egyetlen duplikátum 500 sor kétszeri feldolgozását jelentené.

Ha a rendszered tartósan elérhetetlen volt (karbantartás, hétvégi leállás), a 6 próbálkozás elfogyhat, és az esemény elveszne. Erre való a GET /events: az összes kimenő eseményt visszaadja időrendben, kézbesítési állapottal együtt. Jegyezd meg a legutolsó feldolgozott id-t, és onnan folytasd — nem oldalszámmal, mert közben új esemény keletkezhet.

curl "https://veridyn.eu/api/v1/events?after_id=1487&limit=100" \
  -H "Authorization: Bearer vk_<kulcs>"

{
  "data": [
    {
      "id": 1488,
      "event_id": "evt_9f21c4a08b73d5e6f1a20c44",
      "event": "product.updated",
      "data": { "id": "a1993ef7-…", "category": "textile", "version_no": 2 },
      "sent_at": "2026-07-02T13:19:11+00:00",
      "delivery": { "status": "failed", "attempts": 6, "http_status": 502, "url": "https://…" }
    }
  ],
  "after_id": 1487,
  "next_id": 1488
}

A delivery.status lehet delivered (sikeresen kiment), pending (még próbálkozunk) vagy failed (feladtuk). Az esemény akkor is itt van, ha a kézbesítés soha nem sikerült — épp ezért lehet belőle pótolni.

← Beállítások / API-kulcsok