{ "openapi": "3.1.0", "info": { "title": "Veridyn DPP API", "version": "v1", "description": "EU digitális termékútlevél (DPP) REST API.\n\n**Hitelesítés:** `Authorization: Bearer vk_…` fejléc (Pro csomagtól).\n**Hatókör:** a kulcs lehet `full` (olvasás+írás) vagy `read` (csak GET).\n**Rate limit:** 120 kérés / perc / kulcs (`X-RateLimit-*` fejlécek, túllépésnél 429).\n**Idempotencia:** a POST-oknál `Idempotency-Key` fejléc a duplikátumok ellen.", "contact": { "name": "Veridyn", "email": "hello@veridyn.eu" } }, "servers": [ { "url": "https://veridyn.eu/api/v1" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "vk_… API key" } }, "schemas": { "Product": { "type": "object", "properties": { "id": { "type": "string", "description": "Útlevél UID" }, "category": { "type": "string", "example": "battery" }, "level": { "type": "string", "enum": [ "model", "batch", "item" ] }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "gtin": { "type": "string", "nullable": true }, "lot": { "type": "string", "nullable": true }, "serial": { "type": "string", "nullable": true }, "version_no": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "passport_url": { "type": "string", "format": "uri" }, "gs1_url": { "type": "string", "format": "uri", "nullable": true }, "qr_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "additionalProperties": true, "description": "Kategória-séma szerinti mezők — lásd GET /schema/{category}" } } }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "example": "validation" } } } }, "responses": { "Unauthorized": { "description": "Hiányzó/érvénytelen API-kulcs (401)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Túl sok kérés — rate limit (429)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Nem található (404)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/health": { "get": { "summary": "Állapot-ellenőrzés (auth nélkül)", "security": [], "responses": { "200": { "description": "OK" } } } }, "/categories": { "get": { "summary": "Elérhető termékkategóriák", "responses": { "200": { "description": "Kategórialista" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/schema/{category}": { "get": { "summary": "Egy kategória teljes mező-leírása (kötelező + opcionális)", "parameters": [ { "name": "category", "in": "path", "required": true, "schema": { "type": "string" }, "example": "battery" } ], "responses": { "200": { "description": "Séma-leírás" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/products": { "get": { "summary": "Termékútlevelek listája (könnyű összefoglaló)", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Keresés név/SKU/GTIN szerint" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "all", "active", "archived" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Lapozott lista" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "summary": "Új termékútlevél (modell)", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Opcionális egyedi kulcs — ugyanazzal a kulccsal ismételt POST a korábbi választ adja vissza (nem hoz létre duplikátumot)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "category", "data" ], "properties": { "category": { "type": "string", "example": "battery" }, "data": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "201": { "description": "Létrehozva", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Product" } } } } } }, "403": { "description": "read-only kulcs vagy csomag-limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "GTIN már foglalt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validációs hiba", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/products/{id}": { "get": { "summary": "Egy termékútlevél teljes adata", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Termék", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Product" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "summary": "Mezők frissítése (sekély merge → új verzió)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Opcionális egyedi kulcs — ugyanazzal a kulccsal ismételt POST a korábbi választ adja vissza (nem hoz létre duplikátumot)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Frissítve" }, "403": { "description": "read-only kulcs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validációs hiba", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/products/{id}/qr": { "get": { "summary": "A termék QR-kódja (SVG)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SVG", "content": { "image/svg+xml": { "schema": { "type": "string" } } } } } } }, "/products/{id}/children": { "get": { "summary": "A modell alatti tétel/egység útlevelek", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Gyerek-lista" } } }, "post": { "summary": "Tétel/egység útlevél(ek) létrehozása (egy vagy bulk)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Opcionális egyedi kulcs — ugyanazzal a kulccsal ismételt POST a korábbi választ adja vissza (nem hoz létre duplikátumot)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lot": { "type": "string" }, "serial": { "type": "string" }, "data": { "type": "object" }, "items": { "type": "array", "items": { "type": "object" } } } } } } }, "responses": { "201": { "description": "Létrehozva" }, "403": { "description": "read-only kulcs vagy csomag-limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validációs hiba", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/products/{id}/scans": { "get": { "summary": "Termék-szintű scan-összegző", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "days", "in": "query", "schema": { "type": "integer", "enum": [ 7, 30, 90, 365 ] } } ], "responses": { "200": { "description": "Scan-adatok" } } } }, "/scans": { "get": { "summary": "Bérlő-szintű scan-összegző (ország/eszköz/kategória/szint)", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "enum": [ 7, 30, 90, 365 ] } } ], "responses": { "200": { "description": "Scan-adatok" } } } } } }