Parcelník API

Prehľad

Parcelník API je REST rozhranie nad JSON s prenosom výhradne cez HTTPS. Robí to isté ako objednávka v portáli: rovnaké balíky, ceny, kontroly pokrytia a pravidlá fakturácie. Je určené realitným kanceláriám, developerom, bankám a ďalším firmám, ktoré preverujú pozemky opakovane.

Základná adresa

https://api.parcelnik.sk/api/v1/integration

Formát

JSON v UTF-8, časy v ISO 8601 (UTC), ceny v eurocentoch

Verzia

v1 (v ceste /api/v1), aktualizované 10. 10. 2026

Prostredie

Produkčné. Samostatný sandbox zatiaľ nemáme; na test odporúčame Rýchly prehľad (9 €) alebo nám napíšte o testovací účet s fakturáciou.

Hodnoty v príkladoch (kódy obcí, identifikátory parciel a objednávok) sú ilustračné. Skutočné identifikátory vždy získajte z predchádzajúceho volania.

Začíname

1. Účet. Zaregistrujte sa alebo nás požiadajte o firemný účet s fakturáciou na objednavky@parcelnik.sk.
2. API kľúč. V portáli otvorte Integrácie, zadajte názov kľúča (napr. „CRM produkcia“) a platnosť 30, 90 alebo 365 dní. Kľúč začína pk_ a zobrazí sa iba raz.
3. Prvé volanie. Overte kľúč na ponuke balíkov:

export PARCELNIK_API_KEY="pk_…"
curl -s "https://api.parcelnik.sk/api/v1/integration/offer" -H "Authorization: Bearer $PARCELNIK_API_KEY"

Autentifikácia

Každá požiadavka posiela kľúč v hlavičke Authorization: Bearer pk_…. Kľúč koná za váš účet: vidí len vaše objednávky a objednáva na váš účet.

• Na účet môžete mať najviac 10 aktívnych kľúčov; každý môžete kedykoľvek odvolať.
• Ukladáme len odtlačok kľúča (SHA-256), nie kľúč samotný. Stratený kľúč neobnovíme, vytvorte nový.
• API kľúč nefunguje v portáli a prihlásenie do portálu nefunguje v API. Účty administrátorov API používať nesmú (403).
• Deaktiváciou účtu sa odvolajú všetky jeho kľúče aj pripojení AI asistenti.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="parcelnik", error="invalid_token"

{ "statusCode": 401, "message": "Neplatný alebo chýbajúci API kľúč.", "error": "Unauthorized" }

Postup objednávky

Parcelu vyberáte rovnako ako v katastri: obec → katastrálne územie → číslo parcely.

1. GET /municipalities?q=nájdite obec a jej kód
2. GET /municipalities/{code}/cadastral-areasvyberte katastrálne územie
3. GET /cadastral-areas/{id}/parcels?number=nájdite parcelu (parcelId)
4. GET /parcels/{id}/coveragezistite medzery v pokrytí
5. POST /ordersobjednajte a potvrďte medzery
6. GET /orders/{id}sledujte stav, kým nie je COMPLETE
7. GET /orders/{id}/reportstiahnite PDF

Rýchly prehľad je zvyčajne hotový do niekoľkých minút. Základné preverenie do 2 pracovných dní (dopĺňame list vlastníctva a overenie územného plánu), Kompletný audit do 30 pracovných dní.

Fakturácia a platby

API nikdy neplatí ani neudeľuje súhlasy za zákazníka. Cenu vždy určuje server podľa cenníka v /offer; v požiadavke sa cena neposiela. Promo kódy sa uplatňujú len v portáli.

Referencia endpointov

Všetky cesty sú relatívne k https://api.parcelnik.sk/api/v1/integration a vyžadujú hlavičku Authorization. Neznáme polia v tele požiadavky server odmietne (400).

• GET/offerPonuka balíkov
• GET/municipalitiesVyhľadanie obce
• GET/municipalities/{code}/cadastral-areasKatastrálne územia obce
• GET/cadastral-areas/{id}/parcelsVyhľadanie parcely
• GET/parcels/{id}/coveragePokrytie parcely
• POST/ordersVytvorenie objednávky
• GET/ordersZoznam objednávok
• GET/orders/{id}Detail objednávky
• GET/orders/{id}/reportStiahnutie reportu (PDF)

curl -s "https://api.parcelnik.sk/api/v1/integration/offer" \
  -H "Authorization: Bearer $PARCELNIK_API_KEY"

{
  "bundles": [
    {
      "id": "instant-overview",
      "name": "Rýchly prehľad",
      "price": "9 €",
      "priceCents": 900,
      "delivery": "okamžite"
    },
    {
      "id": "basic-check",
      "name": "Základné preverenie",
      "price": "49 €",
      "priceCents": 4900,
      "delivery": "do 2 pracovných dní"
    },
    {
      "id": "full-audit",
      "name": "Kompletný audit",
      "price": "299 €",
      "priceCents": 29900,
      "delivery": "1. časť (Základné preverenie) do 2 pracovných dní, celý audit do 30 pracovných dní"
    }
  ],
  "purposes": ["family-house", "recreation", "garden", "investment", "commercial", "other"]
}

curl -s "https://api.parcelnik.sk/api/v1/integration/municipalities" \
  -H "Authorization: Bearer $PARCELNIK_API_KEY"

[
  {
    "code": "SK0102508241",
    "name": "Bernolákovo",
    "districtCode": "SK0102",
    "districtName": "Senec",
    "regionName": "Bratislavský kraj"
  }
]

curl -s "https://api.parcelnik.sk/api/v1/integration/municipalities/{code}/cadastral-areas" \
  -H "Authorization: Bearer $PARCELNIK_API_KEY"

[
  { "id": "CU.3149", "name": "Bernolákovo", "municipalityCode": "SK0102508241" }
]

curl -s "https://api.parcelnik.sk/api/v1/integration/cadastral-areas/{id}/parcels" \
  -H "Authorization: Bearer $PARCELNIK_API_KEY"

[
  {
    "parcelId": "CP.205486",
    "parcelNumber": "1234/5",
    "register": "C",
    "areaSquareMetres": 812
  }
]

curl -s "https://api.parcelnik.sk/api/v1/integration/parcels/{id}/coverage" \
  -H "Authorization: Bearer $PARCELNIK_API_KEY"

[
  { "id": "geometry", "label": "Hranica parcely v katastri", "status": "available" },
  { "id": "map-layers", "label": "Mapové vrstvy (riziká, chránené územia, pamiatky, CHVO)", "status": "available" },
  { "id": "terrain", "label": "Výškový model terénu", "status": "available" },
  {
    "id": "zoning",
    "label": "Register územných plánov obce",
    "status": "gap",
    "note": "Obec nemá v štátnom registri zaevidovaný územný plán."
  }
]

curl -s -X POST "https://api.parcelnik.sk/api/v1/integration/orders" \
  -H "Authorization: Bearer $PARCELNIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d @objednavka.json

{
  "bundleId": "basic-check",
  "parcelId": "CP.205486",
  "cadastralAreaId": "CU.3149",
  "label": "parc. č. 1234/5, k. ú. Bernolákovo",
  "purpose": "family-house",
  "acknowledgedCoverageGaps": ["zoning"]
}

{
  "id": "6f1c2a9e-4d1b-4b8e-9a0c-2f3e5d7a8b10",
  "bundle": "Základné preverenie",
  "parcel": "parc. č. 1234/5, k. ú. Bernolákovo",
  "status": "PROCESSING",
  "statusText": "pripravuje sa",
  "createdAt": "2026-10-10T08:15:02.114Z",
  "portalUrl": "https://parcelnik.sk/app/orders",
  "paymentRequired": false,
  "confirmationRequired": false
}

curl -s "https://api.parcelnik.sk/api/v1/integration/orders" \
  -H "Authorization: Bearer $PARCELNIK_API_KEY"

[
  {
    "id": "6f1c2a9e-4d1b-4b8e-9a0c-2f3e5d7a8b10",
    "bundle": "Základné preverenie",
    "parcel": "parc. č. 1234/5, k. ú. Bernolákovo",
    "status": "AWAITING_ATTACHMENT",
    "statusText": "pripravuje sa (dopĺňame list vlastníctva)",
    "createdAt": "2026-10-10T08:15:02.114Z",
    "portalUrl": "https://parcelnik.sk/app/orders"
  }
]

curl -s "https://api.parcelnik.sk/api/v1/integration/orders/{id}" \
  -H "Authorization: Bearer $PARCELNIK_API_KEY"

{
  "id": "6f1c2a9e-4d1b-4b8e-9a0c-2f3e5d7a8b10",
  "bundle": "Rýchly prehľad",
  "parcel": "parc. č. 1234/5, k. ú. Bernolákovo",
  "status": "COMPLETE",
  "statusText": "hotová",
  "createdAt": "2026-10-10T08:15:02.114Z",
  "portalUrl": "https://parcelnik.sk/app/orders",
  "signals": [
    {
      "area": "Záplavy",
      "level": "ok",
      "levelText": "v poriadku",
      "text": "Parcela nezasahuje do mapovaných záplavových území."
    },
    {
      "area": "Ochranné pásma",
      "level": "warn",
      "levelText": "pozor",
      "text": "Parcela môže zasahovať do ochranného pásma cesty, železnice alebo vedenia."
    }
  ]
}

curl -s "https://api.parcelnik.sk/api/v1/integration/orders/{id}/report" \
  -H "Authorization: Bearer $PARCELNIK_API_KEY"

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="….pdf"
Cache-Control: private, no-store

%PDF-1.7 …

Stavy objednávky

Pole status je stabilný kód pre váš program, statusText je text pre ľudí a môže sa meniť. Nové stavy môžeme v rámci v1 pridať; neznámy stav považujte za „pripravuje sa“.

Semafor rizík v hotovej objednávke má úrovne ok, warn, risk a unknown. Úroveň unknown znamená, že zdroj neodpovedal; nie je to dobrý výsledok.

Chyby

Chyby majú HTTP kód a telo s poľom message. Obchodné chyby sú v slovenčine; pri chybách validácie vstupu je to zoznam technických hlásení v angličtine.

{
  "statusCode": 400,
  "message": [
    "label must be longer than or equal to 5 characters"
  ],
  "error": "Bad Request"
}

Limity

• 60 požiadaviek za minútu na integračné API, z jednej adresy.
• 30 za minútu na kontrolu pokrytia, 20 za minútu na vytváranie objednávok.
• Najviac 30 objednávok za hodinu na jeden účet (spolu cez API aj AI asistentov).

Po prekročení dostanete 429 Too Many Requests. Opakujte s exponenciálnym odstupom (napr. 2, 4, 8 s). Stav objednávky sa pýtajte najviac raz za minútu; webhooky zatiaľ neposkytujeme. Potrebujete vyšší limit? Napíšte nám.

Bezpečnosť

• Kľúč používajte len na serveri. Nikdy ho nedávajte do JavaScriptu v prehliadači, mobilnej aplikácie ani do repozitára; ukladajte ho v správcovi tajomstiev.
• Pre každý systém vytvorte vlastný kľúč s obmedzenou platnosťou a pravidelne ich meňte.
• Pri podozrení na únik kľúč ihneď odvolajte v Integráciách.
• Do label nevkladajte mená ani iné osobné údaje klientov; stačí parcela alebo adresa.
• Reporty s listom vlastníctva obsahujú osobné údaje vlastníkov. Ukladajte ich zabezpečene a len po nevyhnutnú dobu.

Príklady

Celý postup od vyhľadania obce po stiahnutie PDF:

# 1. Obec
curl -s "https://api.parcelnik.sk/api/v1/integration/municipalities?q=Bernolakovo" \
  -H "Authorization: Bearer $PARCELNIK_API_KEY"

# 2. Katastrálne územia obce
curl -s "https://api.parcelnik.sk/api/v1/integration/municipalities/SK0102508241/cadastral-areas" \
  -H "Authorization: Bearer $PARCELNIK_API_KEY"

# 3. Parcela podľa čísla
curl -s "https://api.parcelnik.sk/api/v1/integration/cadastral-areas/CU.3149/parcels?number=1234/5" \
  -H "Authorization: Bearer $PARCELNIK_API_KEY"

# 4. Pokrytie a objednávka
curl -s "https://api.parcelnik.sk/api/v1/integration/parcels/CP.205486/coverage" \
  -H "Authorization: Bearer $PARCELNIK_API_KEY"

curl -s -X POST "https://api.parcelnik.sk/api/v1/integration/orders" \
  -H "Authorization: Bearer $PARCELNIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bundleId":"instant-overview","parcelId":"CP.205486","cadastralAreaId":"CU.3149","label":"parc. č. 1234/5, k. ú. Bernolákovo","acknowledgedCoverageGaps":["zoning"]}'

# 5. Stav a PDF
curl -s "https://api.parcelnik.sk/api/v1/integration/orders/<ID>" -H "Authorization: Bearer $PARCELNIK_API_KEY"
curl -s -o report.pdf "https://api.parcelnik.sk/api/v1/integration/orders/<ID>/report" \
  -H "Authorization: Bearer $PARCELNIK_API_KEY"

AI asistenti (MCP)

Tie isté operácie sú dostupné aj ako nástroje pre ChatGPT a Claude cez MCP server https://api.parcelnik.sk/mcp s prihlásením OAuth 2.1. Objednávku od asistenta musí zákazník vždy potvrdiť v portáli. Návod na pripojenie je v portáli v časti Integrácie.

Zmeny API

V rámci v1 pridávame len spätne kompatibilné zmeny (nové polia, endpointy, stavy). Ignorujte polia, ktoré nepoznáte. Nekompatibilnú zmenu vydáme ako novú verziu a vopred ju oznámime e-mailom držiteľom kľúčov.

• 10. 10. 2026 – verejná dokumentácia a špecifikácia OpenAPI.
• 3. 10. 2026 – kľúče s obmedzenou platnosťou, administrátorské účty odmietnuté.
• 28. 9. 2026 – prvé vydanie integračného API v1.

Otázky k integrácii: objednavky@parcelnik.sk.