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

Pro csomagtól

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

GET-kérésekhez fejléc nélkül, közvetlenül a böngészőben is kipróbálhatod — a kulcsot ?api_key= paraméterként add meg:

https://veridyn.eu/api/v1/categories?api_key=vk_<a kulcsod>

⚠️ Csak teszteléshez. Az URL-be írt kulcs bekerül a böngésző-előzménybe és a szerver-logokba, ezért éles integrációban mindig a Authorization: Bearer fejlécet használd. POST/PATCH csak fejléccel (curl/Postman) hívható.

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 }.
GET	/products/{id}/qr	QR-kód (SVG) a publikus passporthoz.

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":"hello@lumora.hu"
      }
    }
  }'

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.

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.
404	not_found	Nincs ilyen termék / útvonal.
409	gtin_taken	A GTIN már foglalt.
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

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. A kézbesítés best-effort (rövid timeout); az utolsó kézbesítés státusza a Beállításokban látszik.

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