{ "openapi": "3.1.0", "info": { "title": "Parcelník API", "version": "1.0.0", "description": "Integračné REST API Parcelníka: vyhľadanie parcely v katastri, kontrola pokrytia, objednávka reportu a stiahnutie PDF. Dokumentácia: https://parcelnik.sk/api", "contact": { "email": "objednavky@parcelnik.sk", "url": "https://parcelnik.sk/api" }, "termsOfService": "https://parcelnik.sk/obchodne-podmienky" }, "servers": [ { "url": "https://api.parcelnik.sk/api/v1/integration", "description": "Produkcia" } ], "security": [ { "apiKey": [] } ], "paths": { "/offer": { "get": { "operationId": "getOffer", "summary": "Ponuka balíkov", "description": "Objednateľné balíky s cenou a dodacou lehotou a povolené účely.\n\nLimit: 60 požiadaviek za minútu.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Offer" } } } }, "401": { "description": "Chýbajúci alebo neplatný API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Účet nesmie používať API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Prekročený limit požiadaviek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/municipalities": { "get": { "operationId": "searchMunicipalities", "summary": "Vyhľadanie obce", "description": "Najviac 10 obcí podľa názvu (bez ohľadu na diakritiku).\n\nLimit: 60 požiadaviek za minútu.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Municipality" } } } } }, "401": { "description": "Chýbajúci alebo neplatný API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Účet nesmie používať API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Prekročený limit požiadaviek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Neplatný parameter q.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Názov obce alebo jeho začiatok.", "schema": { "type": "string", "minLength": 2, "maxLength": 80 } } ] } }, "/municipalities/{code}/cadastral-areas": { "get": { "operationId": "listCadastralAreas", "summary": "Katastrálne územia obce", "description": "Katastrálne územia obce s daným kódom.\n\nLimit: 60 požiadaviek za minútu.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CadastralArea" } } } } }, "401": { "description": "Chýbajúci alebo neplatný API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Účet nesmie používať API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Prekročený limit požiadaviek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Obec neexistuje.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Kód obce.", "schema": { "type": "string" } } ] } }, "/cadastral-areas/{id}/parcels": { "get": { "operationId": "searchParcels", "summary": "Vyhľadanie parcely", "description": "Najviac 20 parciel podľa parcelného čísla v katastrálnom území.\n\nLimit: 60 požiadaviek za minútu.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Parcel" } } } } }, "401": { "description": "Chýbajúci alebo neplatný API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Účet nesmie používať API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Prekročený limit požiadaviek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Neplatný parameter number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifikátor katastrálneho územia.", "schema": { "type": "string" } }, { "name": "number", "in": "query", "required": true, "description": "Parcelné číslo, napr. 1234/5.", "schema": { "type": "string", "minLength": 1, "maxLength": 30 } } ] } }, "/parcels/{id}/coverage": { "get": { "operationId": "getCoverage", "summary": "Pokrytie parcely", "description": "Ktoré časti reportu sa pre parcelu nedajú pripraviť. Položky so statusom gap treba potvrdiť pri objednávke.\n\nLimit: 30 požiadaviek za minútu.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CoverageItem" } } } } }, "401": { "description": "Chýbajúci alebo neplatný API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Účet nesmie používať API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Prekročený limit požiadaviek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Parcela sa nenašla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "parcelId.", "schema": { "type": "string" } } ] } }, "/orders": { "post": { "operationId": "createOrder", "summary": "Vytvorenie objednávky", "description": "Objedná report pre jednu parcelu. Účty s platbou vopred dostanú stav AWAITING_PAYMENT a zákazník zaplatí v portáli. Najviac 30 objednávok za hodinu na účet.\n\nLimit: 20 požiadaviek za minútu.", "responses": { "201": { "description": "Objednávka vytvorená", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedOrder" } } } }, "401": { "description": "Chýbajúci alebo neplatný API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Účet nesmie používať API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Prekročený limit požiadaviek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Neplatné vstupy alebo nepotvrdená medzera v pokrytí.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Online platby dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrder" } } } } }, "get": { "operationId": "listOrders", "summary": "Zoznam objednávok", "description": "Posledných 100 objednávok účtu, od najnovšej.\n\nLimit: 60 požiadaviek za minútu.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } } } }, "401": { "description": "Chýbajúci alebo neplatný API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Účet nesmie používať API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Prekročený limit požiadaviek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}": { "get": { "operationId": "getOrder", "summary": "Detail objednávky", "description": "Stav objednávky; hotová obsahuje semafor rizík (signals).\n\nLimit: 60 požiadaviek za minútu.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "401": { "description": "Chýbajúci alebo neplatný API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Účet nesmie používať API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Prekročený limit požiadaviek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Identifikátor nie je UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Objednávka neexistuje alebo nepatrí účtu.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifikátor objednávky.", "schema": { "type": "string", "format": "uuid" } } ] } }, "/orders/{id}/report": { "get": { "operationId": "downloadReport", "summary": "Stiahnutie reportu", "description": "Doručený report vo formáte PDF.\n\nLimit: 60 požiadaviek za minútu.", "responses": { "200": { "description": "PDF reportu", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Chýbajúci alebo neplatný API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Účet nesmie používať API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Prekročený limit požiadaviek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Objednávka neexistuje, nepatrí účtu alebo report nie je pripravený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifikátor hotovej objednávky.", "schema": { "type": "string", "format": "uuid" } } ] } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Osobný API kľúč (pk_…) z portálu, časť Integrácie." } }, "schemas": { "Error": { "type": "object", "required": [ "statusCode", "message" ], "properties": { "statusCode": { "type": "integer" }, "message": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "error": { "type": "string" } } }, "BundleId": { "type": "string", "enum": [ "instant-overview", "basic-check", "full-audit" ] }, "Purpose": { "type": "string", "enum": [ "family-house", "recreation", "garden", "investment", "commercial", "other" ] }, "Offer": { "type": "object", "required": [ "bundles", "purposes" ], "properties": { "bundles": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "price", "priceCents", "delivery" ], "properties": { "id": { "$ref": "#/components/schemas/BundleId" }, "name": { "type": "string" }, "price": { "type": "string", "examples": [ "9 €" ] }, "priceCents": { "type": "integer" }, "delivery": { "type": "string" } } } }, "purposes": { "type": "array", "items": { "$ref": "#/components/schemas/Purpose" } } } }, "Municipality": { "type": "object", "required": [ "code", "name", "districtCode" ], "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "districtCode": { "type": "string" }, "districtName": { "type": [ "string", "null" ] }, "regionName": { "type": [ "string", "null" ] } } }, "CadastralArea": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "municipalityCode": { "type": "string" } } }, "Parcel": { "type": "object", "required": [ "parcelId", "parcelNumber" ], "properties": { "parcelId": { "type": "string" }, "parcelNumber": { "type": "string" }, "register": { "type": [ "string", "null" ] }, "areaSquareMetres": { "type": [ "number", "null" ] } } }, "CoverageItem": { "type": "object", "required": [ "id", "label", "status" ], "properties": { "id": { "type": "string", "enum": [ "geometry", "map-layers", "terrain", "zoning" ] }, "label": { "type": "string" }, "status": { "type": "string", "enum": [ "available", "gap", "unknown" ] }, "note": { "type": "string" } } }, "CreateOrder": { "type": "object", "additionalProperties": false, "required": [ "bundleId", "parcelId", "cadastralAreaId", "label" ], "properties": { "bundleId": { "$ref": "#/components/schemas/BundleId" }, "parcelId": { "type": "string", "maxLength": 64 }, "cadastralAreaId": { "type": "string", "maxLength": 64 }, "label": { "type": "string", "minLength": 5, "maxLength": 300 }, "purpose": { "$ref": "#/components/schemas/Purpose" }, "acknowledgedCoverageGaps": { "type": "array", "items": { "type": "string", "enum": [ "geometry", "map-layers", "terrain", "zoning" ] } } } }, "Signal": { "type": "object", "required": [ "area", "level", "levelText", "text" ], "properties": { "area": { "type": "string" }, "level": { "type": "string", "enum": [ "ok", "warn", "risk", "unknown" ] }, "levelText": { "type": "string" }, "text": { "type": "string" } } }, "Order": { "type": "object", "required": [ "id", "bundle", "parcel", "status", "statusText", "createdAt", "portalUrl" ], "properties": { "id": { "type": "string", "format": "uuid" }, "bundle": { "type": "string" }, "parcel": { "type": "string" }, "status": { "type": "string", "enum": [ "AWAITING_PAYMENT", "AWAITING_CONFIRMATION", "PROCESSING", "AUTO_RETRY", "NEEDS_REVIEW", "AWAITING_ATTACHMENT", "COMPLETE", "FAILED", "CANCELLED", "SUBMISSION_UNKNOWN" ] }, "statusText": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "paymentUrl": { "type": "string", "format": "uri" }, "confirmUrl": { "type": "string", "format": "uri" }, "portalUrl": { "type": "string", "format": "uri" }, "signals": { "type": "array", "items": { "$ref": "#/components/schemas/Signal" } } } }, "CreatedOrder": { "allOf": [ { "$ref": "#/components/schemas/Order" }, { "type": "object", "required": [ "paymentRequired", "confirmationRequired" ], "properties": { "paymentRequired": { "type": "boolean" }, "confirmationRequired": { "type": "boolean" } } } ] } } } }