{"openapi":"3.1.0","info":{"title":"Verifento – overenie zákazníka","version":"1.0.0","summary":"Zdieľaná databáza incidentov pre požičovne, prenájmové a rezervačné firmy aj pre obchod medzi firmami.","description":"Verifento je B2B platforma, ktorá firmám umožňuje overiť zákazníka pred prenájmom alebo pred obchodom medzi firmami proti zdieľanej databáze incidentov nahlásených inými firmami. Odpoveďou je STUPEŇ RIZIKA a počty záznamov – nikdy nie odporúčanie „prenajať / neprenajať“. Rozhodnutie robí človek; čl. 22 GDPR zakazuje rozhodnutie založené výlučne na automatizovanom spracúvaní.\n\nIdentifikátory sa do databázy nikdy neukladajú v čitateľnej podobe – používa sa slepý index (HMAC-SHA256). Platforma teda nevie, koho ste overovali, len že ste sa pýtali.","contact":{"name":"Verifento","url":"https://verifento.com/pre-vyvojarov"},"license":{"name":"Proprietárne","url":"https://verifento.com/terms"}},"servers":[{"url":"https://verifento.com","description":"Produkcia"}],"security":[{"apiKey":[]}],"tags":[{"name":"overenie","description":"Overenie zákazníka proti zdieľanej databáze."},{"name":"nahlasovanie","description":"Zápis incidentu z vlastného systému. Vyžaduje kľúč s oprávnením `incidenty:zapis`."}],"paths":{"/api/v1/verify":{"post":{"tags":["overenie"],"operationId":"overZakaznika","summary":"Overí jedného zákazníka","description":"Vráti stupeň rizika pre zadaný identifikátor. Pri kľúči s predponou `vf_test_` sa do databázy nesiahne a vrátia sa pevné odpovede pre vyhradené čísla – viď `/pre-vyvojarov`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["typ","identifikator"],"properties":{"typ":{"type":"string","enum":["phone","email","doc","name_dob","iban","id_card","passport","license","residence_permit","ico"],"description":"Druh identifikátora."},"identifikator":{"type":"string","description":"Hodnota. Normalizuje sa na našej strane – posielajte ju tak, ako ju má zákazník."},"datum_narodenia":{"type":"string","format":"date","description":"Povinné len pri type `name_dob`."}}},"examples":{"telefon":{"summary":"Telefón","value":{"typ":"phone","identifikator":"+421901234567"}},"pieskovisko":{"summary":"Pieskovisko – vysoké riziko","value":{"typ":"phone","identifikator":"+421900000004"}}}}}},"responses":{"200":{"description":"Overené.","content":{"application/json":{"schema":{"type":"object","required":["riziko","zaznamy","posledny_incident","kategorie"],"properties":{"riziko":{"type":"string","enum":["green","positive_only","low","medium","high","neznamy"],"description":"Stupeň rizika. Zoznam sa môže ROZŠÍRIŤ – klient musí mať vetvu pre neznámu hodnotu a nesmie na nej spadnúť. `green` = bez záznamu, `positive_only` = len kladné hodnotenia."},"zaznamy":{"type":"object","required":["negativne","pozitivne","nahlasujucich_firiem"],"properties":{"negativne":{"type":"integer","description":"Počet negatívnych incidentov."},"pozitivne":{"type":"integer","description":"Počet kladných záznamov."},"nahlasujucich_firiem":{"type":"integer","description":"Koľko RÔZNYCH firiem záznamy nahlásilo. Ktoré, sa nevracia nikdy – zdieľaná sieť stojí na tom, že nahlásenie neprezradí nahlasovateľa konkurencii."},"potvrdene":{"type":"integer","description":"Z negatívnych: potvrdené záznamy."},"podozrenie":{"type":"integer","description":"Z negatívnych: podozrenie, ešte nepotvrdené."},"sporne":{"type":"integer","description":"Z negatívnych: zákazník ich rozporoval, čakajú na posúdenie."},"obet":{"type":"integer","description":"Z negatívnych: ochranné záznamy OBETE zneužitia identity. Nie sú dôvodom odmietnuť zákazníka – naopak, znamenajú, že niekto jeho údaje zneužil."}}},"subezne_prenajmy":{"type":["object","null"],"description":"Koľko INÝCH firiem má s tým človekom práve teraz nevrátený prenájom, delené na rovnaký a iný segment podnikania.\n\n**NIE JE to súčasť rizika a nesmie sa tak používať.** `riziko` hovorí o nahlásených záznamoch, za ktorými stojí uvedený dôkaz. Súbežný prenájom nie je udalosť, je to stav a má bežné vysvetlenia: rodina, firma prenajímajúca pre zamestnancov, sťahovanie, náhrada za pokazenú vec.\n\nNikde sa to neukladá – počíta sa v okamihu overenia. Ktorá firma to je, čo je prenajaté ani dokedy, sa nevracia nikdy.\n\n`null` znamená **nevieme**, nie nula. Kto to zamení, spraví z nevedomosti tvrdenie o konkrétnom človeku.","properties":{"rovnaky_segment":{"type":"integer","description":"Iné firmy v tom istom segmente."},"ine_segmenty":{"type":"integer","description":"Iné firmy v inom segmente. Auto a lyže v jednom týždni je dovolenka, nie vzorec."}}},"posledny_incident":{"type":["string","null"],"format":"date","description":"Dátum posledného negatívneho záznamu."},"kategorie":{"type":"array","items":{"type":"string"},"description":"Kategórie negatívnych záznamov."},"testovaci_rezim":{"type":"boolean","description":"Bola odpoveď z pieskoviska?"},"upozornenie":{"type":"string","description":"Povinné upozornenie podľa čl. 22 GDPR."},"id_poziadavky":{"type":"string","format":"uuid","description":"Uveďte ho pri hlásení problému."}}}}}},"400":{"description":"Chyba vo vstupe.","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}},"401":{"description":"Kľúč chýba, je neplatný alebo zrušený.","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}},"403":{"description":"Firma nie je činná, alebo volanie prišlo z nepovolenej adresy.","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}},"429":{"description":"Prekročený limit.","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}},"503":{"description":"Overenie sa nepodarilo vykonať. NEPOVAŽUJTE to za výsledok „bez záznamu“ – to je práve tá zámena, ktorá tu raz zostala 116 dní neviditeľná.","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}}}}},"/api/v1/verify/batch":{"post":{"tags":["overenie"],"operationId":"overDavku","summary":"Overí až 50 zákazníkov naraz","description":"Odpoveď je VŽDY 200, aj keď časť položiek zlyhá – pri každej je buď výsledok, alebo chyba. Pole `vysledky` má rovnakú dĺžku a poradie ako vstupné `polozky`. Výnimkou je 503: keď zlyhá samotné overovanie, padá celá dávka, aby sa prázdny výsledok nedal zameniť za „bez záznamu“.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["polozky"],"properties":{"polozky":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","required":["typ","identifikator"],"properties":{"typ":{"type":"string","enum":["phone","email","doc","name_dob","iban","id_card","passport","license","residence_permit","ico"]},"identifikator":{"type":"string"},"datum_narodenia":{"type":"string","format":"date"},"referencia":{"type":"string","description":"Vaše ID. Vráti sa nedotknuté, aby ste nemuseli párovať podľa poradia."}}}}}}}}},"responses":{"200":{"description":"Spracované (aj pri čiastočnom zlyhaní).","content":{"application/json":{"schema":{"type":"object","properties":{"vysledky":{"type":"array","items":{"oneOf":[{"type":"object","required":["riziko","zaznamy","posledny_incident","kategorie"],"properties":{"riziko":{"type":"string","enum":["green","positive_only","low","medium","high","neznamy"],"description":"Stupeň rizika. Zoznam sa môže ROZŠÍRIŤ – klient musí mať vetvu pre neznámu hodnotu a nesmie na nej spadnúť. `green` = bez záznamu, `positive_only` = len kladné hodnotenia."},"zaznamy":{"type":"object","required":["negativne","pozitivne","nahlasujucich_firiem"],"properties":{"negativne":{"type":"integer","description":"Počet negatívnych incidentov."},"pozitivne":{"type":"integer","description":"Počet kladných záznamov."},"nahlasujucich_firiem":{"type":"integer","description":"Koľko RÔZNYCH firiem záznamy nahlásilo. Ktoré, sa nevracia nikdy – zdieľaná sieť stojí na tom, že nahlásenie neprezradí nahlasovateľa konkurencii."},"potvrdene":{"type":"integer","description":"Z negatívnych: potvrdené záznamy."},"podozrenie":{"type":"integer","description":"Z negatívnych: podozrenie, ešte nepotvrdené."},"sporne":{"type":"integer","description":"Z negatívnych: zákazník ich rozporoval, čakajú na posúdenie."},"obet":{"type":"integer","description":"Z negatívnych: ochranné záznamy OBETE zneužitia identity. Nie sú dôvodom odmietnuť zákazníka – naopak, znamenajú, že niekto jeho údaje zneužil."}}},"subezne_prenajmy":{"type":["object","null"],"description":"Koľko INÝCH firiem má s tým človekom práve teraz nevrátený prenájom, delené na rovnaký a iný segment podnikania.\n\n**NIE JE to súčasť rizika a nesmie sa tak používať.** `riziko` hovorí o nahlásených záznamoch, za ktorými stojí uvedený dôkaz. Súbežný prenájom nie je udalosť, je to stav a má bežné vysvetlenia: rodina, firma prenajímajúca pre zamestnancov, sťahovanie, náhrada za pokazenú vec.\n\nNikde sa to neukladá – počíta sa v okamihu overenia. Ktorá firma to je, čo je prenajaté ani dokedy, sa nevracia nikdy.\n\n`null` znamená **nevieme**, nie nula. Kto to zamení, spraví z nevedomosti tvrdenie o konkrétnom človeku.","properties":{"rovnaky_segment":{"type":"integer","description":"Iné firmy v tom istom segmente."},"ine_segmenty":{"type":"integer","description":"Iné firmy v inom segmente. Auto a lyže v jednom týždni je dovolenka, nie vzorec."}}},"posledny_incident":{"type":["string","null"],"format":"date","description":"Dátum posledného negatívneho záznamu."},"kategorie":{"type":"array","items":{"type":"string"},"description":"Kategórie negatívnych záznamov."},"testovaci_rezim":{"type":"boolean","description":"Bola odpoveď z pieskoviska?"},"upozornenie":{"type":"string","description":"Povinné upozornenie podľa čl. 22 GDPR."},"id_poziadavky":{"type":"string","format":"uuid","description":"Uveďte ho pri hlásení problému."}}},{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}]}},"spolu":{"type":"integer"},"overenych":{"type":"integer"},"id_poziadavky":{"type":"string","format":"uuid"}}}}}},"400":{"description":"Chyba vo vstupe alebo priveľká dávka.","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}},"401":{"description":"Kľúč chýba, je neplatný alebo zrušený."},"429":{"description":"Prekročený limit."},"503":{"description":"Overovanie zlyhalo – celá dávka."}}}},"/api/v1/incidents":{"get":{"tags":["nahlasovanie"],"operationId":"zoznamIncidentov","summary":"Stiahne vlastné záznamy","description":"Vráti záznamy VAŠEJ firmy, najnovšie prvé.\n\n**Vyžaduje oprávnenie `incidenty:citanie`** – nie `incidenty:zapis`. Sú to dve rôzne veci a dve rôzne škody pri únikoch kľúča: kľúč so zápisom vie o človeku niečo tvrdiť, kľúč s čítaním vie stiahnuť celú históriu záznamov firmy. Integrácia, ktorá len posiela škody, nemá dôvod vedieť čítať.\n\n**Odtlačok zákazníka sa nevracia** ani vlastnej firme. Na spárovanie s vlastnou evidenciou je `interny_odkaz` – pole, ktoré ste sami vyplnili. Slepý index je pseudonymizovaný osobný údaj a jediné, na čo by sa mimo Verifenta dal použiť, je postaviť z neho vlastný register ľudí.\n\n**Stránkuje sa kurzorom, nie číslom stránky.** Vráťte hodnotu `dalsi_kurzor` v parametri `po`. `null` znamená, že to bola posledná stránka – neodhadujte koniec z počtu záznamov, posledná stránka môže byť plná. `OFFSET` by pri novom incidente medzi dvoma stránkami zobrazil jeden záznam dvakrát a iný vôbec.\n\nNeaktívne záznamy (expirované alebo zmrazené pre podanú GDPR námietku) sa nevracajú. V pieskovisku je zoznam vždy prázdny.","parameters":[{"name":"na_stranu","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"po","in":"query","schema":{"type":"string"},"description":"Hodnota `dalsi_kurzor` z predchádzajúcej odpovede."},{"name":"od","in":"query","schema":{"type":"string","format":"date"},"description":"Dátum udalosti od (vrátane)."},{"name":"do","in":"query","schema":{"type":"string","format":"date"},"description":"Dátum udalosti do (vrátane)."},{"name":"kladne","in":"query","schema":{"type":"boolean"},"description":"Len kladné (`true`) alebo len negatívne (`false`)."},{"name":"kategoria","in":"query","schema":{"type":"string"}},{"name":"zavaznost","in":"query","schema":{"type":"string","enum":["low","medium","high"]}}],"responses":{"200":{"description":"Zoznam záznamov.","content":{"application/json":{"schema":{"type":"object","properties":{"zaznamy":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"datum":{"type":"string","format":"date","description":"Dátum udalosti."},"kategoria":{"type":"string"},"zavaznost":{"type":"string","enum":["low","medium","high"]},"kladny":{"type":"boolean"},"popis":{"type":["string","null"]},"interny_odkaz":{"type":["string","null"],"description":"Vaša väzba na vlastnú evidenciu."},"dokazy":{"type":"array","items":{"type":"string"}},"vytvorene":{"type":"string","format":"date-time"},"expiruje":{"type":["string","null"],"format":"date-time","description":"Kedy záznam prestane byť viditeľný v sieti."},"cez_api":{"type":"boolean","description":"Vznikol cez API, alebo v paneli?"}}}},"dalsi_kurzor":{"type":["string","null"],"description":"`null` = posledná stránka."},"testovaci_rezim":{"type":"boolean"},"id_poziadavky":{"type":"string","format":"uuid"}}}}}},"400":{"description":"Neplatný parameter. Neznámy parameter sa ignoruje, ale neplatná HODNOTA známeho je chyba – inak by filter mlčky neplatil a dostali by ste viac, než ste si vyžiadali.","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}},"401":{"description":"Kľúč chýba, je neplatný alebo zrušený.","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}},"403":{"description":"Kľúč nemá oprávnenie `incidenty:citanie`.","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}},"429":{"description":"Prekročený limit (300 požiadaviek za hodinu).","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}},"503":{"description":"Záznamy sa nepodarilo načítať.","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}}}},"post":{"tags":["nahlasovanie"],"operationId":"nahlasIncident","summary":"Nahlási incident zo svojho systému","description":"Založí záznam o zákazníkovi v zdieľanej sieti.\n\n**Kľúč musí mať oprávnenie `incidenty:zapis`.** Nové kľúče ho nemajú – zapína sa v paneli, v sekcii API kľúče. Je to zámer: kľúč, ktorý sa smie pýtať, sa ešte nesmie vyjadrovať.\n\n**Hlavička `Idempotency-Key` je POVINNÁ.** Posielajte pri každom nahlásení nový jedinečný reťazec (napríklad UUID) a pri opakovaní po chybe spojenia ten istý. Bez toho by zo strateného spojenia vznikli dva záznamy o tom istom človeku – a semafor počíta záznamy aj nahlasujúce firmy, takže by ten človek vyzeral horšie, než aký je.\n\n**Negatívny záznam vyžaduje aspoň jeden typ dôkazu.** Zoznam je v `/pre-vyvojarov`.\n\nPri kľúči s predponou `vf_test_` prebehnú všetky kontroly a nezapíše sa nič (`zapisane: false`, `id: null`).","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Jedinečný reťazec operácie. Platí 24 hodín; to isté telo vráti uloženú odpoveď, iné telo vráti 422."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["typ","identifikator","kategoria","zavaznost","datum","dokazy"],"properties":{"typ":{"type":"string","enum":["phone","email","doc","name_dob","iban","id_card","passport","license","residence_permit","ico"],"description":"Druh identifikátora."},"identifikator":{"type":"string","description":"Hodnota. Normalizuje sa na našej strane."},"datum_narodenia":{"type":"string","format":"date","description":"Povinné len pri type `name_dob`."},"kategoria":{"type":"string","description":"Kategória incidentu. Zoznam je v `/pre-vyvojarov`."},"zavaznost":{"type":"string","enum":["low","medium","high"],"description":"Iná hodnota sa odmietne – `critical` ani `minor` nie sú platné."},"popis":{"type":"string","maxLength":5000},"datum":{"type":"string","format":"date","description":"Dátum udalosti. Nesmie byť v budúcnosti."},"interny_odkaz":{"type":"string","maxLength":200,"description":"Väzba na vašu evidenciu – číslo zmluvy, objednávky, prípadu."},"dokazy":{"type":"array","minItems":1,"items":{"type":"string"},"description":"Typy dokladov, ktoré o udalosti máte. Pri negatívnom zázname povinné."},"kladny":{"type":"boolean","default":false,"description":"Kladný záznam. Ukladá sa ako other/low a dôkaz nepotrebuje."}}},"examples":{"neuhradene":{"summary":"Neuhradená faktúra","value":{"typ":"phone","identifikator":"+421901234567","kategoria":"non_payment","zavaznost":"high","popis":"Neuhradená faktúra po dvoch výzvach.","datum":"2026-09-08","interny_odkaz":"FA-2026-118","dokazy":["invoice_unpaid","contract_ref"]}},"kladny":{"summary":"Kladný záznam","value":{"typ":"phone","identifikator":"+421901234567","kladny":true,"datum":"2026-09-08","kategoria":"other","zavaznost":"low","dokazy":[]}}}}}},"responses":{"201":{"description":"Zapísané. Pri opakovaní s tým istým kľúčom sa vráti táto istá odpoveď a hlavička `Idempotency-Replayed: true`.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":["string","null"],"format":"uuid","description":"ID záznamu. V pieskovisku `null`."},"zapisane":{"type":"boolean"},"testovaci_rezim":{"type":"boolean"},"upozornenie":{"type":"string"},"id_poziadavky":{"type":"string","format":"uuid"}}}}}},"400":{"description":"Chyba vo vstupe, chýbajúca alebo krátka hlavička Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}},"401":{"description":"Kľúč chýba, je neplatný alebo zrušený.","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}},"403":{"description":"Kľúč nemá oprávnenie `incidenty:zapis`, firma nie je činná, alebo volanie prišlo z nepovolenej adresy.","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}},"409":{"description":"Požiadavka s týmto Idempotency-Key sa práve spracúva. Skúste o chvíľu – výsledok bude ten istý.","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}},"422":{"description":"Ten istý Idempotency-Key už bol použitý s INÝM obsahom. Použite pri každej operácii nový.","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}},"429":{"description":"Prekročený limit (60 zápisov za hodinu).","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}},"503":{"description":"Zápis sa nepodaril. Zopakujte s TÝM ISTÝM Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}}}}},"/api/v1/incidents/{id}":{"patch":{"tags":["nahlasovanie"],"operationId":"opravIncident","summary":"Opraví vlastný záznam","description":"Upraví popis, kategóriu, závažnosť alebo kladnosť záznamu, ktorý patrí vašej firme (bez ohľadu na to, či vznikol cez API alebo v paneli).\n\n**Vyžaduje to isté oprávnenie ako zápis** (`incidenty:zapis`). Kto smie tvrdiť, musí vedieť aj odvolať – samostatné oprávnenie by dovolilo vydať kľúč, ktorý zakladá záznamy a nevie ich opraviť.\n\n**`Idempotency-Key` sa tu NEPOSIELA.** Oprava nesie absolútne hodnoty, takže dvakrát vykonaná dá ten istý výsledok; opakovanie po stratenej odpovedi nemá čo poškodiť.\n\n**Pole `dovod` je povinné** a ide do auditu – oprava záznamu o človeku musí byť vysvetliteľná aj o rok.\n\nPreklopenie na kladný záznam (`kladny: true`) zároveň zrovná kategóriu na `other` a závažnosť na `low`; lehota uchovávania sa prepočíta.\n\nCudzí a neexistujúci záznam vracajú rovnaké 404 – inak by z toho bol nástroj na zisťovanie, či dané ID v sieti existuje. Mazať záznam cez API nejde: poctivé stiahnutie je preklopenie na kladný, po ktorom zostane história v audite.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"ID záznamu z odpovede na zápis."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["dovod"],"properties":{"popis":{"type":"string","maxLength":5000},"kategoria":{"type":"string"},"zavaznost":{"type":"string","enum":["low","medium","high"]},"kladny":{"type":"boolean","description":"Preklopenie na kladný záznam – poctivé stiahnutie tvrdenia."},"dovod":{"type":"string","minLength":3,"maxLength":500,"description":"Prečo sa mení. Ide do auditu."}}},"examples":{"znizenie":{"summary":"Znížená závažnosť","value":{"zavaznost":"low","dovod":"Škoda bola nižšia, než sa pri prevzatí zdalo."}},"stiahnutie":{"summary":"Stiahnutie záznamu","value":{"kladny":true,"dovod":"Zákazník všetko uhradil."}}}}}},"responses":{"200":{"description":"Spracované. `zmenene` je zoznam polí, ktoré sa naozaj zmenili – prázdne pole znamená, že poslané hodnoty už v zázname boli.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"zmenene":{"type":"array","items":{"type":"string"}},"testovaci_rezim":{"type":"boolean"},"upozornenie":{"type":"string"},"id_poziadavky":{"type":"string","format":"uuid"}}}}}},"400":{"description":"Chyba vo vstupe, chýbajúci `dovod` alebo neplatné ID.","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}},"401":{"description":"Kľúč chýba, je neplatný alebo zrušený.","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}},"403":{"description":"Kľúč nemá oprávnenie `incidenty:zapis`.","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}},"404":{"description":"Záznam sa nenašiel alebo nepatrí vašej firme.","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}},"429":{"description":"Prekročený limit.","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}},"503":{"description":"Oprava sa nepodarila. Zopakujte.","content":{"application/json":{"schema":{"type":"object","required":["chyba","sprava"],"properties":{"chyba":{"type":"string","description":"Strojový kód. NEMENNÝ – naviažte naň vetvenie."},"sprava":{"type":"string","description":"Text pre človeka. Mení sa bez ohlásenia."},"id_poziadavky":{"type":["string","null"],"format":"uuid"}}}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Kľúč sa posiela ako `Authorization: Bearer vf_live_…`. Predpona `vf_test_` znamená pieskovisko: do databázy sa nesiahne a vracajú sa pevné odpovede.\n\nKľúč sa dá rotovať s prekryvom (1–30 dní) – starý platí ďalej, kým prekryv beží, a každá odpoveď vtedy nesie hlavičku `Verifento-Key-Expires` s termínom. Po termíne vracia starý kľúč 401 `zruseny_kluc`."}}},"x-pieskovisko":{"popis":"Vyhradené identifikátory pre testovací kľúč. Predvoľba 900 je nepridelená, takže test nemôže trafiť skutočného človeka.","identifikatory":{"+421900000000":{"riziko":"green","popis":"Zákazník bez akéhokoľvek záznamu."},"+421900000001":{"riziko":"positive_only","popis":"Len kladné hodnotenia od troch firiem, žiadny problém."},"+421900000002":{"riziko":"low","popis":"Jedno neskoré vrátenie, inak v poriadku."},"+421900000003":{"riziko":"medium","popis":"Opakované poškodenie a porušenie podmienok."},"+421900000004":{"riziko":"high","popis":"Vážne záznamy od piatich firiem vrátane neuhradenia a krádeže."}}},"webhooks":{"incident.vytvoreny":{"post":{"summary":"Na zákazníka s vaším prebiehajúcim prenájmom pribudol incident","description":"Posiela sa LEN firmám, ktoré majú s daným subjektom prebiehajúci alebo nedávny (do 30 dní) prenájom – na tom stojí oprávnený záujem podľa čl. 6 ods. 1 písm. f GDPR. Overte podpis v hlavičke `Verifento-Signature` (HMAC-SHA256 nad `čas.telo`); bez toho vám môže ktokoľvek, kto uhádne vašu adresu, podstrčiť falošný incident.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"udalost":{"type":"string","enum":["incident.vytvoreny"]},"verzia":{"type":"integer","enum":[1]},"vytvorene":{"type":"string","format":"date-time"},"zakaznik":{"type":"object","properties":{"odtlacok":{"type":"string","description":"Slepý index. NIE telefón – ten istý odtlačok si viete dopočítať z vlastných údajov."},"typ":{"type":"string","enum":["phone","email","doc","name_dob","iban","id_card","passport","license","residence_permit","ico"]}}},"incident":{"type":"object","properties":{"zavaznost":{"type":"string"},"kategoria":{"type":"string"},"datum":{"type":"string","format":"date"}}},"riziko":{"type":"string","enum":["green","positive_only","low","medium","high"],"description":"Stav zákazníka po pripočítaní tohto incidentu."},"upozornenie":{"type":"string"}}}}}},"responses":{"2xx":{"description":"Prijaté. Obsah tela nás nezaujíma."},"default":{"description":"Skúsime znova – päťkrát s narastajúcim odstupom. Po 20 neúspechoch sa webhook vypne."}}}}},"x-limity":{"overenie":"600 za hodinu na firmu, 1200 za hodinu na IP","davka":"120 požiadaviek za hodinu na firmu (až 50 overení v každej)","hlavicky":["X-RateLimit-Limit","X-RateLimit-Remaining","X-RateLimit-Reset"]}}