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.

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.
POST	/products	Új termékútlevél. Törzs: { category, data }.
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	/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.
GET	/products/{id}/scans	Termék-szintű beolvasás-összegző: total, unique, byCountry, byDevice. Paraméter: days=7|30|90|365.
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

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

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

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.
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).

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 · scan.milestone · scan.clone_suspected

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-Signature: sha256=<hmac>

{
  "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. Az utolsó kézbesítés státusza a Beállításokban látszik.

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