{"openapi":"3.1.0","info":{"title":"Renly Financie API","version":"1.0","summary":"Vystavujte faktúry, zapisujte úhrady a spravujte partnerov z vlastného systému.","description":"API Financií je pre e-shopy, pokladne, rezervačné systémy a ďalšie aplikácie, ktoré chcú vystavovať doklady\ncez Renly Financie. Financie dokladu pridelia číslo z radu, vytvoria PDF so vzhľadom vašej firmy, pošlú ho\nodberateľovi e-mailom, evidujú úhrady, upomínajú po splatnosti a doklad odovzdajú účtovníkovi rovnako ako doklad\nvystavený ručne.\n","contact":{"name":"Podpora Renly","email":"support@renly.sk","url":"https://renly.sk/kontakt"}},"servers":[{"url":"https://api.renly.sk/api/v1/finance/external","description":"Produkcia"}],"security":[{"apiKey":[]}],"tags":[{"name":"Kľúč","description":"Overenie kľúča a spoločnosti, ku ktorej patrí."},{"name":"Doklady","description":"Faktúry, zálohové faktúry, dobropisy a ich PDF."},{"name":"Úhrady a odoslanie","description":"Zápis úhrady a odoslanie dokladu e-mailom."},{"name":"Partneri","description":"Adresár odberateľov a dodávateľov."},{"name":"Cenník a nastavenia","description":"Položky cenníka, číselné rady a bankové účty pre vystavenie dokladu."},{"name":"Webhooky","description":"Správy o zmenách dokladov, ktoré sa stali vo Financiách."},{"name":"Verejné PDF","description":"Odkaz na PDF dokladu bez prihlásenia, ktorý môžete dať zákazníkovi."}],"x-renly-guides":[{"id":"rychly-start","title":"Rýchly štart","body":"Za päť minút vystavíte prvú faktúru. Potrebujete prístup do Renly Financií s oprávnením upravovať nastavenie\na **dokončený úvodný sprievodca Financií** (údaje firmy, ktoré budú na dokladoch — obchodné meno, adresa, IČO,\npostavenie voči DPH). Bez neho API vystavenie odmietne chybou `409 finance.profile_incomplete`.\n\n### 1. Vytvorte kľúč\n\n1. Vo Financiách otvorte **Nastavenie → API a e-shopy**\n   ([finance.renly.sk/nastavenie/api](https://finance.renly.sk/nastavenie/api)).\n2. Kliknite na **Nový API kľúč**, zadajte názov systému (napr. „E-shop mojafirma.sk“) a nechajte oprávnenia\n   **Čítanie dokladov** a **Vystavovanie dokladov**.\n3. Kľúč `rfk_…` sa ukáže **iba raz**. Uložte ho do tajných nastavení svojho systému.\n\nĎalej v príkladoch je kľúč v premennej prostredia:\n\n```bash\nexport RENLY_FINANCE_KEY='rfk_…'\n```\n\n### 2. Overte kľúč\n\n```bash\ncurl -s https://api.renly.sk/api/v1/finance/external/me \\\n  -H \"Authorization: Bearer $RENLY_FINANCE_KEY\"\n```\n\nOdpoveď ukáže názov kľúča, jeho oprávnenia a spoločnosť, za ktorú bude systém vystavovať doklady.\n\n### 3. Vystavte faktúru\n\n```bash\ncurl -s https://api.renly.sk/api/v1/finance/external/documents \\\n  -H \"Authorization: Bearer $RENLY_FINANCE_KEY\" \\\n  -H \"Idempotency-Key: mojsystem:objednavka-1001:invoice\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"type\": \"invoice\",\n    \"externalSource\": \"mojsystem\",\n    \"externalId\": \"objednavka-1001\",\n    \"buyer\": { \"name\": \"Jana Nováková\", \"street\": \"Hlavná 1\", \"city\": \"Trenčín\",\n               \"postalCode\": \"91101\", \"countryCode\": \"SK\", \"email\": \"jana@example.sk\" },\n    \"lines\": [ { \"description\": \"Konzultácia\", \"quantity\": \"2\", \"unit\": \"h\", \"unitPrice\": \"50\", \"vatRate\": 23 } ],\n    \"send\": false\n  }'\n```\n\nOdpoveď `201` obsahuje vystavený doklad: `number` (číslo z vášho radu), sumy, `paymentStatus` a\n`publicPdfUrl` — odkaz na PDF, ktorý môžete poslať zákazníkovi. Doklad hneď uvidíte aj vo Financiách\nv zozname **Doklady**.\n\n### 4. Ďalej\n\n- Faktúru pošlite zákazníkovi e-mailom: `\"send\": true` pri vystavení alebo\n  [`POST /documents/{id}/send`](#operation/sendDocument).\n- Keď zákazník zaplatí, zapíšte úhradu: [`POST /documents/{id}/payments`](#operation/recordDocumentPayment).\n- O úhradách zapísaných vo Financiách (napríklad z bankového výpisu) sa dozviete cez [webhooky](#guide/webhooky).\n"},{"id":"prihlasenie","title":"Prihlásenie a oprávnenia","body":"Každá požiadavka posiela kľúč v hlavičke `Authorization`:\n\n```http\nAuthorization: Bearer rfk_AbC123def456…\n```\n\n- Kľúč patrí **jednej spoločnosti** vo Financiách. Všetky doklady, partneri aj cenník sú tej spoločnosti.\n  Keď máte vo Financiách viac spoločností, každá potrebuje vlastný kľúč.\n- Kľúč je **ostrý** (`rfk_…`) alebo **testovací** (`rfk_test_…`), pozri [testovanie](#guide/testovanie).\n- Kľúč platí iba pre cesty `/api/v1/finance/external/…`. Prihlásenie do appky ním nefunguje a naopak.\n- Neplatný, zrušený alebo chýbajúci kľúč vráti vždy `401 finance.api_key_unauthorized`.\n\n**Oprávnenia kľúča** vyberiete pri jeho vytvorení. Dajte kľúču iba tie, ktoré systém naozaj potrebuje.\n\n| oprávnenie | čo dovolí |\n|---|---|\n| `documents:read` | čítať doklady a ich PDF, číselné rady a bankové účty |\n| `documents:write` | vystaviť faktúru a zálohovú faktúru, dobropis, vyúčtovanie zálohy, storno a odoslanie e-mailom |\n| `payments:write` | zapísať úhradu dokladu |\n| `partners:read` | čítať adresár partnerov |\n| `partners:write` | založiť a upraviť partnera |\n| `catalog:read` | čítať cenník položiek |\n| `webhooks:write` | registrovať a spravovať webhooky |\n\nKeď kľúču oprávnenie chýba, API vráti `403 finance.api_key_scope_missing` a v `error.details.scope` uvedie\nchýbajúce oprávnenie. Oprávnenia existujúceho kľúča sa meniť nedajú — vytvorte nový kľúč a starý zrušte.\n\n**Spoločnosť a balíček.** API funguje, kým má firma Financie v balíčku. Keď je spoločnosť nad limitom\nbalíčka (neaktívna), API z nej iba číta a zápis vráti `409 finance.company_inactive`.\n\n**AI agenti.** Ak chcete Financie ovládať z AI asistenta (Claude, ChatGPT), nepoužívajte API kľúč — pripojte\nasistenta cez MCP server Renly. Návod je v Pomocníkovi v appke („AI asistent cez MCP“).\n"},{"id":"testovanie","title":"Testovanie","body":"Na vývoj a skúšanie si vytvorte **testovací kľúč**: vo Financiách **Nastavenie → API a e-shopy → Nový kľúč**,\nrežim **Testovací**. Kľúč začína `rfk_test_` a funguje vo všetkých balíčkoch s Financiami, aj v bezplatnom.\n\nTestovací kľúč volá tie isté cesty a dostane tie isté odpovede ako ostrý, ale **nič ostré nevznikne**:\n\n- Doklady dostanú číslo `TEST-000001`, `TEST-000002`… mimo číselného radu. Vlastné `number` dostane predponu\n  (`TEST-2027000123`). Číslovanie vašich skutočných dokladov sa nezmení.\n- Testovacie doklady nejdú do exportu pre účtovníka, prehľadov ani párovania s bankou a nerátajú sa do počtu\n  dokladov balíčka.\n- **E-mail neodíde.** `send` a [`POST /documents/{id}/send`](#operation/sendDocument) odoslanie iba\n  zaznamenajú (`sentAt`, história, webhook `document.sent`). E-faktúra z testovacieho dokladu nevznikne.\n- PDF má vodoznak „TESTOVACÍ – NEPLATNÝ“ a nemá QR kód na platbu. Verejný odkaz `publicPdfUrl` funguje.\n- Odpoveď má hlavičku `X-Renly-Test-Mode: true` a doklad, partner aj webhook pole `test: true`.\n  [`GET /me`](#operation/getApiKey) vráti `key.mode: \"test\"`.\n\n**Oddelenie od ostrej prevádzky.** Testovací kľúč vidí a mení iba testovacie doklady, ostrý kľúč iba ostré\n(cudzí doklad vráti `404`). `Idempotency-Key` sú oddelené: ten istý kľúč po prechode na ostrý kľúč vystaví\nnový ostrý doklad. Cenník, číselné rady, bankové účty a partneri sú spoločné, takže `seriesId`,\n`bankAccountId` aj `partnerId` platia v oboch režimoch — **na ostrú prevádzku stačí vymeniť kľúč**.\n\n- Partner založený testovacím kľúčom je testovací: vidí ho iba testovací kľúč. Ostrého partnera testovací\n  kľúč iba číta (`PATCH` vráti `403 finance.api_test_mode_forbidden`).\n- Webhook zaregistrovaný testovacím kľúčom dostáva iba udalosti testovacích dokladov a telo udalosti má\n  `\"test\": true`. Ostré webhooky testovacie udalosti nedostanú.\n\n**Zmazanie.** Testovacie doklady a partnerov zmažete vo Financiách v **Nastavenie → API a e-shopy →\nTestovacie dáta** alebo jednotlivo z detailu dokladu. Testovacie dáta staršie ako 30 dní sa mažú samy.\nSpoločnosť môže mať naraz najviac 1 000 testovacích dokladov (`409 finance.api_test_limit`).\n\nNa čítanie skutočných dokladov použite ostrý kľúč s oprávneniami iba na čítanie.\n"},{"id":"format-udajov","title":"Formát údajov","body":"- Telo požiadavky aj odpovede je JSON v UTF-8 (`Content-Type: application/json`).\n- **Sumy, ceny a množstvá sú reťazce** s desatinnou bodkou: `\"19.90\"`, `\"2\"`, `\"-1\"`. Celé číslo JSON\n  sa prijme tiež, číslo s desatinnou čiarkou alebo float nie. Sumy v odpovedi majú vždy dve desatinné miesta\n  (`\"46.70\"`), ceny a množstvá najkratší zápis (`\"19.9\"`).\n- Množstvo najviac 3 desatinné miesta, cena najviac 4, zľava v percentách 0–100 s najviac 2 miestami.\n- Dátumy sú `YYYY-MM-DD` (slovenský kalendárny deň), časy ISO 8601 s časovou zónou\n  (`2027-01-04T10:15:00+01:00`).\n- ID sú UUID v textovom tvare.\n- Prázdne textové polia sú v odpovedi `\"\"`, nie `null`. `null` znamená, že údaj neexistuje (napríklad\n  `sentAt` neodoslaného dokladu).\n- Úspešná odpoveď má tvar `{ \"data\": …, \"meta\": { … } }`, chyba `{ \"error\": { \"code\", \"message\", \"details\" } }`.\n\n**DPH.** Ceny položiek sú bez DPH. Keď váš systém počíta ceny s DPH (bežné v B2C), pošlite\n`\"pricesIncludeVat\": true` a Financie DPH dopočítajú. Sadzby sú `23`, `19` a `5`. Režimy DPH (`vatMode`):\n\n| `vatMode` | kedy |\n|---|---|\n| `standard` | bežný doklad platiteľa DPH (predvolené) |\n| `reverse_charge` | prenesenie daňovej povinnosti, napr. firma z inej krajiny EÚ s IČ DPH — sadzby sa vynulujú |\n| `exempt` | oslobodené plnenie, napr. zákazník mimo EÚ — povinný `vatExemptionReason` |\n| `non_payer` | dodávateľ nie je platiteľ DPH (nastaví sa sám podľa profilu spoločnosti) |\n| `oss` | spotrebiteľ v inom štáte EÚ, DPH štátu spotreby — iba spoločnosť registrovaná v OSS |\n\n**OSS.** Pri `\"vatMode\": \"oss\"` pošlite `vatCountry` (štát spotreby, predvolene štát odberateľa) a sadzby toho\nštátu: `AT` 20/13/10, `CZ` 21/12, `DE` 19/7, `HU` 27/18/5, `PL` 23/8/5. Odberateľ nesmie mať IČ DPH. Ďalšie\nštáty Financie zatiaľ nepoznajú — takú objednávku vystavte ručne.\n\n**Mena a jazyk.** `currency` je `EUR` alebo `CZK`, `USD`, `GBP`, `PLN`, `HUF`, `CHF`, `SEK`, `NOK`, `DKK`,\n`RON` (kurz doplní Financie z ECB, alebo pošlite `exchangeRate`). `language` dokladu je kód ISO 639-1:\n`sk`, `cs`, `en`, `de`, `hu`, `pl`, `hr`, `sl`, `ro`, `ru`, `uk`, `es`, `it`, `nl`.\n"},{"id":"strankovanie","title":"Stránkovanie","body":"Zoznamy (doklady, partneri, cenník) vracajú najviac `limit` záznamov (predvolene 50, najviac 100) a v\n`meta.nextCursor` reťazec ďalšej stránky. Ďalšiu stránku získate rovnakou požiadavkou s parametrom `cursor`:\n\n```bash\ncurl -s \"https://api.renly.sk/api/v1/finance/external/documents?from=2027-01-01&limit=100&cursor=$CURSOR\" \\\n  -H \"Authorization: Bearer $RENLY_FINANCE_KEY\"\n```\n\nKeď je `meta.nextCursor` `null`, ďalšia stránka nie je. Kurzor je nepriehľadný — neskladajte ho ani\nneupravujte a pri zmene filtrov začnite bez neho.\n"},{"id":"idempotencia","title":"Idempotencia","body":"Sieť vypadne, webhook e-shopu príde dvakrát, proces spadne po odoslaní požiadavky. Aby zákazník nedostal dve\nfaktúry, **každý `POST` na doklady, úhrady a partnerov vyžaduje hlavičku `Idempotency-Key`**.\n\n```http\nIdempotency-Key: mojsystem:objednavka-1001:invoice\n```\n\n- Kľúč je 1–255 viditeľných znakov ASCII bez medzier a je jedinečný v rámci spoločnosti. Odporúčaný tvar je\n  `<systém>:<objednávka>:<akcia>` — jednoznačne určuje, *čo* chcete urobiť.\n- Prvá úspešná požiadavka si kľúč zapamätá. Rovnaký kľúč s **rovnakým telom** vráti ten istý doklad (aktuálny\n  stav), pôvodný HTTP stav a hlavičku `Idempotent-Replayed: true` — nič sa nevystaví ani nepošle druhýkrát.\n- Rovnaký kľúč s **iným telom** alebo pre inú akciu vráti `409 finance.idempotency_key_reused`. Kľúč nikdy\n  nepoužívajte pre inú objednávku.\n- Chybná požiadavka (4xx, 5xx) sa nezapamätá. Po oprave pošlite požiadavku znova s tým istým kľúčom.\n- Pri výpadku siete alebo odpovedi `5xx` požiadavku **zopakujte s tým istým kľúčom** (napr. o 1, 5 a 30 minút).\n- Zapamätané kľúče sa nemažú, takže opakovanie funguje aj po dňoch.\n\n`PATCH` partnera a registrácia webhooku hlavičku nepotrebujú — opakovaná úprava dá ten istý výsledok a tá istá\nadresa webhooku sa druhýkrát nezaregistruje (`409 finance.webhook_duplicate`).\n"},{"id":"chyby","title":"Chyby","body":"Chyba má HTTP stav a stabilný kód v `error.code`. Podľa kódu sa rozhodujte vo svojom systéme; `message` je\ntext pre človeka a môže sa zmeniť.\n\n```json\n{ \"error\": { \"code\": \"finance.document_incomplete\", \"message\": \"Doklad sa nedá vystaviť — doplňte chýbajúce údaje.\",\n             \"details\": { \"field\": \"buyer.city\", \"fields\": { \"buyer.city\": \"required\" } } } }\n```\n\nPri chybe tvaru je v `details.fields` mapa `pole → dôvod` (`required`, `invalid`, `out_of_range`, `taken`).\nPole položky má tvar `lines.0.unitPrice`.\n\n| stav | kód | čo spraviť |\n|---|---|---|\n| 400 | `admin.invalid_json` | telo nie je platný JSON objekt |\n| 400 | `finance.document_invalid`, `finance.partner_invalid`, `finance.webhook_invalid` | opravte polia z `details.fields` a pošlite znova s tým istým `Idempotency-Key` |\n| 400 | `finance.document_incomplete` | doklad nemá všetko na vystavenie (`details.fields`); nevznikne ani ako koncept |\n| 400 | `finance.idempotency_key_required`, `finance.idempotency_key_invalid` | doplňte alebo opravte hlavičku `Idempotency-Key` |\n| 401 | `finance.api_key_unauthorized` | kľúč chýba, je neúplný alebo zrušený — neopakujte |\n| 403 | `finance.api_key_scope_missing` | kľúču chýba oprávnenie z `details.scope` |\n| 403 | `finance.api_not_available` | firma nemá Financie v balíčku alebo je vypnutá |\n| 403 | `finance.api_test_mode_forbidden` | testovací kľúč mení iba testovacích partnerov ([testovanie](#guide/testovanie)) |\n| 404 | `finance.document_not_found`, `finance.partner_not_found`, `finance.price_list_item_not_found`, `finance.webhook_not_found` | záznam neexistuje alebo patrí inej spoločnosti |\n| 409 | `finance.document_not_editable` | akcia sa na doklad v jeho stave nedá urobiť (napr. storno uhradenej zálohy) |\n| 409 | `finance.payment_exceeds_total` | úhrada je vyššia ako zostatok (`details.remainingAmount`) |\n| 409 | `finance.document_issue_quota` | firma vyčerpala počet dokladov balíčka |\n| 409 | `finance.api_test_limit` | spoločnosť má 1 000 testovacích dokladov — zmažte ich vo Financiách (`details.limit`) |\n| 409 | `finance.document_number_conflict` | vlastné číslo `number` už má iný doklad |\n| 409 | `finance.partner_duplicate` | partner s rovnakým IČO už existuje (`details.existingId`) |\n| 409 | `finance.idempotency_key_reused` | ten istý `Idempotency-Key` s iným telom |\n| 409 | `finance.company_inactive` | spoločnosť je nad limitom balíčka, iba čítanie |\n| 409 | `finance.profile_incomplete` | spoločnosť nemá vo Financiách vyplnené údaje firmy (`details.fields`) — dokončite sprievodcu alebo **Nastavenie → Firma** |\n| 429 | `finance.api_rate_limited` | počkajte počet sekúnd z hlavičky `Retry-After` |\n| 5xx | — | zopakujte s tým istým `Idempotency-Key` |\n\nDoklad, ktorý vznikol, ale e-mail sa nepodarilo odoslať, vráti úspech (`201`) s `meta.sendError` (kód\nchyby). E-mail pošlete znova cez `POST /documents/{id}/send` s novým `Idempotency-Key`.\n"},{"id":"limity","title":"Limity","body":"| čo | limit |\n|---|---|\n| požiadavky | 120 za minútu na kľúč, potom `429` s hlavičkou `Retry-After` (sekundy) |\n| aktívne kľúče | 10 na spoločnosť |\n| webhooky | 5 adries na spoločnosť |\n| stránka zoznamu | najviac 100 záznamov (`limit`), doklady jednej objednávky najviac 50 |\n| verejné PDF | 120 stiahnutí za 10 minút na odkaz a IP adresu |\n| doklady | podľa balíčka Financií (`409 finance.document_issue_quota`) |\n\nPri synchronizácii veľkého množstva údajov posielajte požiadavky postupne a reagujte na `Retry-After`.\nO zmenách sa radšej nechajte informovať webhookmi, než by ste zoznamy čítali stále dokola.\n"},{"id":"verzovanie","title":"Verzovanie a zmeny","body":"Verzia API je v adrese (`/api/v1/…`). V rámci verzie 1 sa zmeny robia iba **spätne kompatibilne**:\n\n- pribúdajú nové endpointy, nepovinné parametre a polia v odpovedi,\n- pribúdajú nové hodnoty zoznamov (napr. nový druh dokladu, nová udalosť webhooku) a nové chybové kódy.\n\nVáš systém preto má **ignorovať neznáme polia** a s neznámou hodnotou zaobchádzať rozumne (napr. neznámy druh\ndokladu preskočiť). Zmenu, ktorá by existujúcu integráciu rozbila, by sme vydali ako novú verziu v adrese a\nvopred oznámili e-mailom správcom spoločností, ktoré API používajú.\n\nStrojovo čitateľná špecifikácia OpenAPI 3.1 je na\n[api.renly.sk/api/v1/public/finance/api/openapi.json](https://api.renly.sk/api/v1/public/finance/api/openapi.json)\n— importujete ju do Postmana, Insomnie alebo generátora klienta.\n"},{"id":"bezpecnost","title":"Bezpečnosť kľúča","body":"Kľúč má rovnakú moc ako človek, ktorý vo Financiách vystavuje doklady. Narábajte s ním ako s heslom.\n\n- Kľúč patrí iba na server — do tajných nastavení, trezoru alebo premennej prostredia. **Nikdy nie do\n  prehliadača, mobilnej aplikácie, zdrojového kódu v repozitári ani do logov.**\n- Každý systém má mať vlastný kľúč s pomenovaním, z ktorého je jasné, kto ho používa. V histórii dokladu potom\n  uvidíte „API: <názov kľúča>“ a pri kľúči čas posledného použitia.\n- Dajte kľúču iba potrebné oprávnenia. E-shop, ktorý iba vystavuje faktúry, nepotrebuje meniť partnerov.\n- Pri podozrení na únik kľúč vo Financiách okamžite **zrušte** (Nastavenie → API a e-shopy → Zrušiť kľúč) a\n  vytvorte nový. Zrušenie platí hneď a nedá sa vrátiť.\n- Webhook prijímajte iba cez HTTPS a vždy overte podpis (kapitola [Webhooky](#guide/webhooky)).\n"},{"id":"scenar-faktura","title":"Scenár: faktúra k zaplatenej objednávke","body":"Zákazník zaplatil kartou alebo v hotovosti. Vystavte faktúru rovno s úhradou a pošlite ju e-mailom:\n\n```bash\ncurl -s https://api.renly.sk/api/v1/finance/external/documents \\\n  -H \"Authorization: Bearer $RENLY_FINANCE_KEY\" \\\n  -H \"Idempotency-Key: mojeshop:2027000123:invoice\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"type\": \"invoice\",\n    \"externalSource\": \"mojeshop\",\n    \"externalId\": \"2027000123\",\n    \"orderNumber\": \"2027000123\",\n    \"paymentMethod\": \"card\",\n    \"pricesIncludeVat\": true,\n    \"buyer\": { \"name\": \"Jana Nováková\", \"street\": \"Hlavná 1\", \"city\": \"Bánovce nad Bebravou\",\n               \"postalCode\": \"95701\", \"countryCode\": \"SK\", \"email\": \"jana@example.sk\" },\n    \"lines\": [\n      { \"description\": \"Pracovný zošit\", \"quantity\": \"2\", \"unit\": \"ks\", \"unitPrice\": \"19.90\", \"vatRate\": 23 },\n      { \"description\": \"Doprava\", \"quantity\": \"1\", \"unit\": \"ks\", \"unitPrice\": \"6.90\", \"vatRate\": 23 }\n    ],\n    \"payment\": { \"paidOn\": \"2027-01-04\", \"method\": \"card\" },\n    \"send\": true\n  }'\n```\n\n- `externalSource` a `externalId` spoja doklad s objednávkou — podľa nich neskôr nájdete všetky jej doklady.\n- Firma: doplňte do `buyer` aj `ico`, `dic` a `icDph`. Firme z EÚ s IČ DPH pošlite\n  `\"vatMode\": \"reverse_charge\"`.\n- Zľava: `discountPercent` pri položke, alebo samostatná položka so záporným množstvom.\n- Bez `payment` je faktúra neuhradená a splatnosť dostane podľa nastavenia spoločnosti alebo partnera.\n"},{"id":"scenar-zaloha","title":"Scenár: platba prevodom so zálohovou faktúrou","body":"1. Pri objednávke vystavte zálohovú faktúru: `\"type\": \"proforma\"`, `\"paymentMethod\": \"bank_transfer\"`.\n   PDF má QR kód na platbu (PAY by square) a variabilný symbol.\n2. Keď peniaze prídu, zapíšte úhradu: `POST /documents/{id}/payments` s\n   `{ \"paidOn\": \"2027-01-06\", \"method\": \"bank_transfer\" }`. Ak úhradu zapíše účtovník z bankového výpisu,\n   dozviete sa to webhookom `document.paid`.\n3. Vystavte faktúru, ktorá zálohu vyúčtuje: `POST /documents/{id}/final-invoice` s `{ \"send\": true }`.\n\nNezaplatenú zálohovú faktúru zrušíte cez `POST /documents/{id}/cancel` s `{ \"reason\": \"Objednávka zrušená\" }`.\n"},{"id":"scenar-email","title":"Scenár: poslať doklad e-mailom","body":"Pri vystavení stačí `\"send\": true` — Financie pošlú e-mail s PDF na `buyer.email` (alebo kontaktné osoby\npartnera) s predmetom a textom v jazyku dokladu, rovnako ako tlačidlo **Odoslať** v appke. Vlastných\npríjemcov a text pošlete objektom:\n\n```json\n\"send\": { \"to\": [\"uctaren@firma.sk\"], \"cc\": [\"nakup@firma.sk\"],\n          \"subject\": \"Faktúra k objednávke 1001\", \"message\": \"Dobrý deň, posielame faktúru…\" }\n```\n\nUž vystavený doklad pošlete (aj znova) cez `POST /documents/{id}/send`. Každé odoslanie potrebuje nový\n`Idempotency-Key`, napr. `mojsystem:objednavka-1001:invoice:send-2`. Čas posledného odoslania je v `sentAt`.\n"},{"id":"scenar-uhrada","title":"Scenár: zistiť, či je doklad uhradený","body":"Stav úhrady je v poli `paymentStatus`: `unpaid`, `partially_paid`, `paid` alebo `overdue` (po splatnosti).\nZostatok je v `remainingAmount`, jednotlivé úhrady v `payments`.\n\n- **Odporúčané:** zaregistrujte webhook s udalosťou `document.paid` — Financie vám dajú vedieť hneď, ako je\n  doklad uhradený, aj keď úhradu spároval účtovník z bankového výpisu.\n- **Bez webhooku:** raz za čas si prečítajte neuhradené doklady:\n\n```bash\ncurl -s \"https://api.renly.sk/api/v1/finance/external/documents?type=invoice,proforma&paymentStatus=unpaid,partially_paid,overdue\" \\\n  -H \"Authorization: Bearer $RENLY_FINANCE_KEY\"\n```\n\nDoklady jednej objednávky nájdete podľa `externalSource` a `externalId`:\n`GET /documents?externalSource=mojeshop&externalId=2027000123`.\n"},{"id":"scenar-partneri","title":"Scenár: partneri","body":"Stáli odberatelia (firmy) môžu byť v adresári Financií. Doklad pre partnera potom stačí vystaviť s\n`partnerId` — Financie doplnia odberateľa, splatnosť partnera, jazyk dokladu aj príjemcov e-mailu z\nkontaktných osôb.\n\n1. Nájdite partnera podľa IČO alebo názvu: `GET /partners?q=36512345`.\n2. Ak neexistuje, založte ho: `POST /partners` s `Idempotency-Key`, napr. `mojsystem:zakaznik-77:partner`.\n   Partner s IČO, ktoré už v adresári je, vráti `409 finance.partner_duplicate` s `details.existingId`.\n3. Vystavte doklad s `\"partnerId\": \"…\"` (bez `buyer`). Ak pošlete aj `buyer`, má prednosť pred adresárom.\n4. Zmenu adresy zapíšte `PATCH /partners/{id}` — pošlite iba menené polia. Zmena sa prejaví na nových\n   dokladoch; vystavené doklady majú odberateľa uloženého v čase vystavenia.\n\nPartnera cez API nezmažete — archivovať ho môže iba človek v appke.\n"},{"id":"scenar-cennik","title":"Scenár: cenník","body":"Ak vediete položky (služby, tovar) v cenníku Financií, váš systém si ich môže načítať\n(`GET /price-list-items`, oprávnenie `catalog:read`) a použiť ich názov, jednotku, cenu a sadzbu DPH v\npoložkách dokladu. Hľadanie: `?q=konzultácia`.\n\nPoložka cenníka má `unitPrice` buď bez DPH, alebo s DPH podľa `pricesIncludeVat`. Na doklade musia byť všetky\npoložky rovnako — keď kombinujete položky s cenou s DPH a bez nej, prepočítajte ich alebo vystavte\n`\"pricesIncludeVat\"` podľa väčšiny a cenu druhých upravte. Cenník mení iba človek v appke.\n"},{"id":"scenar-vratenie","title":"Scenár: vrátenie tovaru","body":"`POST /documents/{id}/credit-note` s `{ \"reason\": \"Vrátenie tovaru\", \"send\": true }` vystaví dobropis celej\nfaktúry. Dobropis má v `relatedDocument` pôvodnú faktúru a prevezme jej `externalSource` a `externalId`.\n\n**Čiastočné vrátenie** (jeden kus, zľava pri reklamácii, poštovné):\n\n- vybrané položky — `{ \"reason\": \"Vrátený tovar\", \"lines\": [ { \"lineId\": \"…\", \"quantity\": \"1\" } ] }`; `lineId` je\n  `lines[].id` faktúry, množstvo kladné a najviac to, čo z položky ešte nevrátili predošlé dobropisy,\n- suma s DPH — `{ \"reason\": \"Reklamácia 2027000123-R1\", \"amount\": \"10.00\", \"description\": \"Zľava – reklamácia\" }`;\n  Financie ju rozdelia po sadzbách DPH faktúry.\n\nDobropisov k jednej faktúre môže byť viac; spolu ani v žiadnej sadzbe DPH nesmú prekročiť faktúru\n(`409 finance.credit_note_exceeds_invoice` s `remainingAmount`, pri položke `finance.credit_note_exceeds_line`).\nFaktúra má v `creditedAmount` súčet dobropisov a `remainingAmount` je po ich odpočte. Pre opakovanie použite\nvlastný `Idempotency-Key` každého vrátenia (napr. `mojeshop:2027000123-R1:credit-note`).\n\n**Faktúra zo starého programu:** dobropis k faktúre, ktorá vo Financiách nie je, vystavíte cez `POST /documents`\ns `\"type\": \"credit_note\"`, `correctionReason`, `originalDocument` (`number` a `issueDate` pôvodnej faktúry) a\npoložkami so záporným množstvom.\n"},{"id":"webhooky","title":"Webhooky","body":"Webhook je HTTPS adresa vášho systému, na ktorú Financie pošlú `POST` pri každej zmene dokladu — aj pri\nzmene urobenej v appke, z bankového výpisu alebo automaticky (upomienka). Registrujete ho\ncez [`POST /webhooks`](#operation/createWebhook) (oprávnenie `webhooks:write`); odpoveď obsahuje `secret`\nna overenie podpisu — **iba raz**.\n\n| udalosť | kedy |\n|---|---|\n| `document.issued` | vystavený doklad, aj dobropis a vyúčtovanie zálohy |\n| `document.payment_recorded` | zapísaná úhrada (aj čiastočná) |\n| `document.paid` | doklad je po úhrade celý uhradený |\n| `document.payment_deleted` | úhrada bola zmazaná |\n| `document.cancelled` | stornovaná zálohová faktúra |\n| `document.sent` | doklad alebo upomienka odoslaná e-mailom |\n\nHlavičky požiadavky:\n\n| hlavička | hodnota |\n|---|---|\n| `X-Renly-Event` | udalosť, napr. `document.paid` |\n| `X-Renly-Delivery` | ID doručenia — rovnaké pri každom pokuse |\n| `X-Renly-Timestamp` | čas pokusu (Unix sekundy) |\n| `X-Renly-Signature` | `sha256=` + hex HMAC-SHA256 tajomstva nad `\"<X-Renly-Timestamp>.<telo>\"` |\n\n```json\n{ \"id\": \"019a…\", \"type\": \"document.paid\", \"createdAt\": \"2027-01-04T10:15:00+01:00\", \"companyId\": \"019a…\",\n  \"test\": false,\n  \"data\": {\n    \"document\": { \"id\": \"019a…\", \"type\": \"invoice\", \"status\": \"issued\", \"paymentStatus\": \"paid\",\n                  \"number\": \"2027001\", \"variableSymbol\": \"2027001\", \"externalSource\": \"mojeshop\",\n                  \"externalId\": \"2027000123\", \"currency\": \"EUR\", \"totalWithVat\": \"46.70\",\n                  \"paidAmount\": \"46.70\", \"remainingAmount\": \"0.00\", \"relatedDocumentId\": null },\n    \"payment\": { \"id\": \"019a…\", \"amount\": \"46.70\" } } }\n```\n\n**Overenie podpisu** (PHP):\n\n```php\n$body = file_get_contents('php://input');\n$timestamp = $_SERVER['HTTP_X_RENLY_TIMESTAMP'] ?? '';\n$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);\nif (!hash_equals($expected, $_SERVER['HTTP_X_RENLY_SIGNATURE'] ?? '') || abs(time() - (int) $timestamp) > 300) {\n    http_response_code(401);\n    exit;\n}\n```\n\nNode.js:\n\n```js\nimport { createHmac, timingSafeEqual } from 'node:crypto';\n\nconst verify = (rawBody, headers, secret) => {\n  const timestamp = headers['x-renly-timestamp'] ?? '';\n  const expected = 'sha256=' + createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');\n  const received = headers['x-renly-signature'] ?? '';\n  return expected.length === received.length\n    && timingSafeEqual(Buffer.from(expected), Buffer.from(received))\n    && Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;\n};\n```\n\nPravidlá:\n\n- Odpovedzte `2xx` do 10 sekúnd a prácu urobte až potom (fronta). Presmerovanie sa nesleduje.\n- Neúspešné doručenie Financie zopakujú o 1 min, 5 min, 30 min, 2 h a 12 h (spolu 6 pokusov).\n  Históriu nájdete cez `GET /webhooks/{id}/deliveries`.\n- Ten istý webhook môže prísť viackrát (rovnaké `X-Renly-Delivery`) — spracujte ho iba raz.\n- Poradie doručení nie je zaručené. `data.document` je stav v čase udalosti; aktuálny stav si načítajte cez\n  `GET /documents/{id}`.\n"}],"paths":{"/me":{"get":{"operationId":"getApiKey","tags":["Kľúč"],"summary":"Kľúč a spoločnosť","description":"Overí kľúč a vráti jeho oprávnenia a spoločnosť, za ktorú systém pracuje. Nepotrebuje oprávnenie.","x-renly-scope":null,"responses":{"200":{"description":"Kľúč je platný.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Me"}}},"example":{"data":{"key":{"id":"019a5f6e-0c1d-7a2b-8c3d-4e5f6a7b8c9d","name":"E-shop mojeshop.sk","keyPrefix":"rfk_AbC123def456","mode":"live","scopes":["documents:read","documents:write","payments:write"],"createdByName":"Jana Admin","createdAt":"2027-01-02T09:00:00+01:00","lastUsedAt":"2027-01-04T10:14:00+01:00","revokedAt":null,"active":true},"company":{"id":"019a5f6e-1111-7a2b-8c3d-4e5f6a7b8c9d","tenantId":"019a5f6e-2222-7a2b-8c3d-4e5f6a7b8c9d","name":"Moja firma s. r. o.","active":true}},"meta":[]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/documents":{"get":{"operationId":"listDocuments","tags":["Doklady"],"summary":"Zoznam dokladov","description":"Dva spôsoby hľadania:\n\n- **Doklady objednávky** — s `externalSource` a `externalId` vráti všetky doklady jednej objednávky\n  (zálohová faktúra, faktúra, dobropisy) od najstaršieho, najviac 50, bez stránkovania.\n- **Všetky doklady** — bez nich vráti vystavené a stornované účtovné doklady spoločnosti od najnovšieho\n  (podľa dátumu vystavenia a čísla) s filtrami a [stránkovaním](#guide/strankovanie). Aj doklady vystavené\n  v appke alebo iným systémom.\n\nKoncepty (rozpísané doklady v appke), cenové ponuky, objednávky a dodacie listy API nevracia.\n","x-renly-scope":"documents:read","parameters":[{"name":"externalSource","in":"query","schema":{"type":"string"},"description":"Systém objednávky, ako pri vystavení. Iba spolu s `externalId`."},{"name":"externalId","in":"query","schema":{"type":"string"},"description":"ID objednávky v systéme. Iba spolu s `externalSource`."},{"name":"type","in":"query","description":"Druhy dokladu oddelené čiarkou.","schema":{"type":"string","example":"invoice,proforma"}},{"name":"status","in":"query","description":"`issued` (vystavený) alebo `cancelled` (stornovaný), oddelené čiarkou. Predvolene oba.","schema":{"type":"string","example":"issued"}},{"name":"paymentStatus","in":"query","description":"`unpaid`, `partially_paid`, `paid`, `overdue`, oddelené čiarkou.","schema":{"type":"string","example":"unpaid,overdue"}},{"name":"partnerId","in":"query","schema":{"type":"string","format":"uuid"},"description":"Iba doklady partnera z adresára."},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"Dátum vystavenia od (vrátane)."},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Dátum vystavenia do (vrátane)."},{"name":"q","in":"query","schema":{"type":"string","maxLength":100},"description":"Hľadanie v čísle dokladu, mene a IČO odberateľa."},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Doklady.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"meta":{"$ref":"#/components/schemas/ListMeta"}}}}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"createDocument","tags":["Doklady"],"summary":"Vystaviť faktúru alebo zálohovú faktúru","description":"Vystaví doklad hneď — dostane číslo z radu, PDF a odkaz `publicPdfUrl`. Obsah je rovnaký ako formulár\ndokladu v appke. Neposlané polia dostanú hodnotu nového dokladu v appke: rad pre druh dokladu, vystavenie\ndnes, dodanie v deň vystavenia (zálohová faktúra bez dodania), splatnosť podľa partnera alebo nastavenia\nspoločnosti, predvolený bankový účet a texty vzhľadu dokladu.\n\nPovinné sú `type`, `lines` a odberateľ — `buyer` (meno, ulica, mesto) alebo `partnerId`. Neúplný doklad je\n`400 finance.document_incomplete` a nevznikne ani ako koncept.\n","x-renly-scope":"documents:write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDocument"},"example":{"type":"invoice","externalSource":"mojeshop","externalId":"2027000123","orderNumber":"2027000123","paymentMethod":"card","pricesIncludeVat":true,"buyer":{"name":"Jana Nováková","street":"Hlavná 1","city":"Bánovce nad Bebravou","postalCode":"95701","countryCode":"SK","email":"jana@example.sk"},"lines":[{"description":"Pracovný zošit","quantity":"2","unit":"ks","unitPrice":"19.90","vatRate":23},{"description":"Doprava","quantity":"1","unit":"ks","unitPrice":"6.90","vatRate":23}],"payment":{"paidOn":"2027-01-04","method":"card"},"send":true}}}},"responses":{"201":{"$ref":"#/components/responses/DocumentCreated"},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/documents/{documentId}":{"get":{"operationId":"getDocument","tags":["Doklady"],"summary":"Detail dokladu","x-renly-scope":"documents:read","parameters":[{"$ref":"#/components/parameters/DocumentId"}],"responses":{"200":{"$ref":"#/components/responses/DocumentOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/documents/{documentId}/pdf":{"get":{"operationId":"getDocumentPdf","tags":["Doklady"],"summary":"PDF dokladu","description":"PDF so vzhľadom dokladu spoločnosti. S `download=1` ako príloha na stiahnutie.","x-renly-scope":"documents:read","parameters":[{"$ref":"#/components/parameters/DocumentId"},{"name":"download","in":"query","schema":{"type":"string","enum":["1"]},"description":"`1` = hlavička na stiahnutie súboru."}],"responses":{"200":{"description":"PDF.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/documents/{documentId}/payments":{"post":{"operationId":"recordDocumentPayment","tags":["Úhrady a odoslanie"],"summary":"Zapísať úhradu","description":"Zapíše úhradu faktúry alebo zálohovej faktúry. Bez `amount` uhradí celý zostatok. Úplná úhrada pošle\nzákazníkovi poďakovanie, ak ho má spoločnosť zapnuté, a webhook `document.paid`.\n","x-renly-scope":"payments:write","parameters":[{"$ref":"#/components/parameters/DocumentId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentInput"},"example":{"paidOn":"2027-01-06","method":"bank_transfer"}}}},"responses":{"200":{"$ref":"#/components/responses/DocumentOk"},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/documents/{documentId}/send":{"post":{"operationId":"sendDocument","tags":["Úhrady a odoslanie"],"summary":"Poslať doklad e-mailom","description":"Pošle vystavený doklad s PDF e-mailom. Bez tela (`{}`) ide na predvolených príjemcov s predvoleným\npredmetom a textom v jazyku dokladu. Každé odoslanie potrebuje nový `Idempotency-Key`.\n","x-renly-scope":"documents:write","parameters":[{"$ref":"#/components/parameters/DocumentId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendInput"},"example":{"to":["uctaren@firma.sk"],"subject":"Faktúra 2027001","message":"Dobrý deň, v prílohe posielame faktúru."}}}},"responses":{"200":{"$ref":"#/components/responses/DocumentOk"},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/documents/{documentId}/final-invoice":{"post":{"operationId":"createFinalInvoice","tags":["Doklady"],"summary":"Vyúčtovať zálohovú faktúru","description":"Vystaví faktúru, ktorá vyúčtuje uhradenú zálohovú faktúru (odpočíta zálohu).","x-renly-scope":"documents:write","parameters":[{"$ref":"#/components/parameters/DocumentId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"send":{"$ref":"#/components/schemas/SendOption"}}},"example":{"send":true}}}},"responses":{"201":{"$ref":"#/components/responses/DocumentCreated"},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/documents/{documentId}/credit-note":{"post":{"operationId":"createCreditNote","tags":["Doklady"],"summary":"Dobropis faktúry (celej alebo čiastočný)","description":"Vystaví dobropis k faktúre: bez `lines` a `amount` celej faktúry, s `lines` vybraných položiek a vráteného\nmnožstva, s `amount` sumy s DPH rozdelenej po sadzbách. Najviac jedno z `lines` a `amount`. Súčet dobropisov\nnesmie prekročiť faktúru spolu, v sadzbe DPH ani v množstve položky (`409`).\n","x-renly-scope":"documents:write","parameters":[{"$ref":"#/components/parameters/DocumentId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["reason"],"properties":{"reason":{"type":"string","maxLength":300,"description":"Dôvod opravy, je na PDF dobropisu."},"lines":{"type":"array","minItems":1,"description":"Vybrané položky faktúry a vrátené množstvo (kladné, najviac zostatok položky).","items":{"type":"object","additionalProperties":false,"required":["lineId","quantity"],"properties":{"lineId":{"type":"string","format":"uuid","description":"`lines[].id` faktúry."},"quantity":{"$ref":"#/components/schemas/Decimal"}}}},"amount":{"$ref":"#/components/schemas/Money","description":"Suma dobropisu s DPH namiesto položiek."},"description":{"type":"string","maxLength":500,"description":"Názov položky pri `amount`; predvolene „Zľava k faktúre …“."},"send":{"$ref":"#/components/schemas/SendOption"}}},"example":{"reason":"Reklamácia 2027000123-R1","amount":"10.00","description":"Zľava – reklamácia","send":true}}}},"responses":{"201":{"$ref":"#/components/responses/DocumentCreated"},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/documents/{documentId}/cancel":{"post":{"operationId":"cancelDocument","tags":["Doklady"],"summary":"Stornovať zálohovú faktúru","description":"Stornuje zálohovú faktúru bez úhrad. Faktúra sa nestornuje — opravuje sa dobropisom.","x-renly-scope":"documents:write","parameters":[{"$ref":"#/components/parameters/DocumentId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["reason"],"properties":{"reason":{"type":"string","maxLength":300}}},"example":{"reason":"Objednávka zrušená zákazníkom"}}}},"responses":{"200":{"$ref":"#/components/responses/DocumentOk"},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/partners":{"get":{"operationId":"listPartners","tags":["Partneri"],"summary":"Zoznam partnerov","description":"Partneri z adresára spoločnosti podľa názvu (abecedne), bez archivovaných.","x-renly-scope":"partners:read","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":100},"description":"Hľadanie v názve, IČO a kontaktných osobách."},{"name":"role","in":"query","schema":{"type":"string","enum":["customer","supplier"]},"description":"Iba odberatelia alebo iba dodávatelia."},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Partneri.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Partner"}},"meta":{"$ref":"#/components/schemas/ListMeta"}}}}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"createPartner","tags":["Partneri"],"summary":"Založiť partnera","description":"Založí partnera v adresári. IČO je v spoločnosti jedinečné — partner s existujúcim IČO je\n`409 finance.partner_duplicate` s `details.existingId`. IČ DPH sa overí v systéme VIES (`vatVerifiedAt`).\n","x-renly-scope":"partners:write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerInput"},"example":{"name":"Hotel Tatra s. r. o.","ico":"36512345","dic":"2020123456","icDph":"SK2020123456","street":"Hlavná 1","city":"Poprad","postalCode":"05801","countryCode":"SK","email":"faktury@hoteltatra.sk","isCustomer":true,"defaultDueDays":30,"contacts":[{"name":"Eva Kováčová","email":"uctaren@hoteltatra.sk","roles":["invoices","reminders"],"isPrimary":true}]}}}},"responses":{"201":{"$ref":"#/components/responses/PartnerCreated"},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/partners/{partnerId}":{"get":{"operationId":"getPartner","tags":["Partneri"],"summary":"Detail partnera","x-renly-scope":"partners:read","parameters":[{"$ref":"#/components/parameters/PartnerId"}],"responses":{"200":{"$ref":"#/components/responses/PartnerOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"updatePartner","tags":["Partneri"],"summary":"Upraviť partnera","description":"Zmení iba poslané polia. `contacts` nahradí celý zoznam kontaktných osôb — existujúcu osobu ponecháte\nposlaním jej `id`. Vystavené doklady sa nemenia.\n","x-renly-scope":"partners:write","parameters":[{"$ref":"#/components/parameters/PartnerId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerInput"},"example":{"street":"Nová 5","city":"Poprad","postalCode":"05801"}}}},"responses":{"200":{"$ref":"#/components/responses/PartnerOk"},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/price-list-items":{"get":{"operationId":"listPriceListItems","tags":["Cenník a nastavenia"],"summary":"Cenník položiek","description":"Položky cenníka spoločnosti podľa názvu (abecedne), bez archivovaných.","x-renly-scope":"catalog:read","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":100},"description":"Hľadanie v názve a kóde položky."},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Položky cenníka.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceListItem"}},"meta":{"$ref":"#/components/schemas/ListMeta"}}},"example":{"data":[{"id":"019a5f6e-3333-7a2b-8c3d-4e5f6a7b8c9d","name":"Konzultácia","detail":"","code":"KONZ","unit":"h","unitPrice":"50","pricesIncludeVat":false,"vatRate":23,"updatedAt":"2027-01-02T09:00:00+01:00"}],"meta":{"limit":50,"nextCursor":null}}}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/price-list-items/{itemId}":{"get":{"operationId":"getPriceListItem","tags":["Cenník a nastavenia"],"summary":"Položka cenníka","x-renly-scope":"catalog:read","parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Položka.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PriceListItem"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/number-series":{"get":{"operationId":"listNumberSeries","tags":["Cenník a nastavenia"],"summary":"Číselné rady","description":"Rady účtovných dokladov. `id` radu pošlite ako `seriesId` pri vystavení, ak nechcete predvolený rad.","x-renly-scope":"documents:read","responses":{"200":{"description":"Rady.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NumberSeries"}}}},"example":{"data":[{"id":"019a5f6e-4444-7a2b-8c3d-4e5f6a7b8c9d","documentType":"invoice","name":"Faktúry","isDefault":true,"nextNumberPreview":"2027002"},{"id":"019a5f6e-5555-7a2b-8c3d-4e5f6a7b8c9d","documentType":"proforma","name":"Zálohové faktúry","isDefault":true,"nextNumberPreview":"ZF2027001"}],"meta":[]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/bank-accounts":{"get":{"operationId":"listBankAccounts","tags":["Cenník a nastavenia"],"summary":"Bankové účty","description":"Účty spoločnosti pre platbu prevodom. `id` účtu pošlite ako `bankAccountId`, ak nechcete predvolený.","x-renly-scope":"documents:read","responses":{"200":{"description":"Účty.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BankAccount"}}}},"example":{"data":[{"id":"019a5f6e-6666-7a2b-8c3d-4e5f6a7b8c9d","bankName":"Slovenská sporiteľňa","iban":"SK3109000000000123456789","bic":"GIBASKBX","currency":"EUR","isDefault":true}],"meta":[]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/webhooks":{"get":{"operationId":"listWebhooks","tags":["Webhooky"],"summary":"Zoznam webhookov","x-renly-scope":"webhooks:write","responses":{"200":{"description":"Aktívne adresy (bez tajomstva).","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"meta":{"type":"object","properties":{"limit":{"type":"integer"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"createWebhook","tags":["Webhooky"],"summary":"Zaregistrovať webhook","description":"Zaregistruje HTTPS adresu a udalosti. Odpoveď obsahuje `secret` na overenie podpisu — **iba raz**, uložte ho.\nNajviac 5 adries, tá istá adresa dvakrát je `409 finance.webhook_duplicate`.\n","x-renly-scope":"webhooks:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["url","events"],"properties":{"url":{"type":"string","format":"uri","maxLength":500,"description":"HTTPS adresa bez mena a hesla."},"events":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/WebhookEvent"}}}},"example":{"url":"https://mojeshop.sk/renly-webhook","events":["document.paid","document.issued"]}}}},"responses":{"201":{"description":"Webhook so `secret`.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"object","required":["secret"],"properties":{"secret":{"type":"string","description":"Tajomstvo podpisu `rfw_…`, iba v tejto odpovedi."}}}]}}}}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/webhooks/{webhookId}":{"delete":{"operationId":"deleteWebhook","tags":["Webhooky"],"summary":"Zmazať webhook","description":"Adresa sa vypne a čakajúce doručenia sa už nepošlú.","x-renly-scope":"webhooks:write","parameters":[{"$ref":"#/components/parameters/WebhookId"}],"responses":{"204":{"description":"Zmazané."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/webhooks/{webhookId}/deliveries":{"get":{"operationId":"listWebhookDeliveries","tags":["Webhooky"],"summary":"História doručení","description":"Posledných 50 doručení od najnovšieho — na hľadanie, prečo webhook neprišiel.","x-renly-scope":"webhooks:write","parameters":[{"$ref":"#/components/parameters/WebhookId"}],"responses":{"200":{"description":"Doručenia.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/public/finance/documents/{token}/pdf":{"servers":[{"url":"https://api.renly.sk/api/v1"}],"get":{"operationId":"getPublicDocumentPdf","tags":["Verejné PDF"],"summary":"PDF dokladu bez prihlásenia","description":"Adresa je v poli `publicPdfUrl` dokladu — nemusíte ju skladať. Platí, kým je doklad vystavený (storno\nzálohovej faktúry ju zruší). Limit 120 stiahnutí za 10 minút na odkaz a IP adresu.\n","security":[],"x-renly-scope":null,"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}},{"name":"download","in":"query","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"PDF.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Priveľa stiahnutí, počkajte podľa `Retry-After`."}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"rfk_…","description":"API kľúč spoločnosti z Financií (Nastavenie → API a e-shopy).","x-renly-scopes":{"documents:read":"Čítanie dokladov a ich PDF, číselných radov a bankových účtov.","documents:write":"Vystavenie faktúry a zálohovej faktúry, dobropis, vyúčtovanie zálohy, storno a odoslanie e-mailom.","payments:write":"Zápis úhrady dokladu.","partners:read":"Čítanie adresára partnerov.","partners:write":"Založenie a úprava partnera.","catalog:read":"Čítanie cenníka položiek.","webhooks:write":"Registrácia a správa webhookov."}}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"Jedinečný kľúč zápisu v spoločnosti, 1–255 viditeľných znakov ASCII. Pozri [Idempotencia](#guide/idempotencia).","schema":{"type":"string","maxLength":255,"example":"mojeshop:2027000123:invoice"}},"DocumentId":{"name":"documentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"PartnerId":{"name":"partnerId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"WebhookId":{"name":"webhookId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"Cursor":{"name":"cursor","in":"query","description":"`meta.nextCursor` predchádzajúcej stránky.","schema":{"type":"string"}},"Limit":{"name":"limit","in":"query","description":"Počet záznamov na stránku.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}},"headers":{"RetryAfter":{"description":"Počet sekúnd, po ktorých môžete poslať ďalšiu požiadavku.","schema":{"type":"integer"}},"IdempotentReplayed":{"description":"`true`, keď ide o opakovanú požiadavku s tým istým `Idempotency-Key` — nič nové nevzniklo.","schema":{"type":"string","enum":["true"]}}},"responses":{"DocumentOk":{"description":"Doklad.","headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Document"},"meta":{"$ref":"#/components/schemas/WriteMeta"}}}}}},"DocumentCreated":{"description":"Vystavený doklad.","headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Document"},"meta":{"$ref":"#/components/schemas/WriteMeta"}}},"example":{"data":{"id":"019a5f6e-7777-7a2b-8c3d-4e5f6a7b8c9d","type":"invoice","status":"issued","paymentStatus":"paid","number":"2027001","variableSymbol":"2027001","orderNumber":"2027000123","externalSource":"mojeshop","externalId":"2027000123","test":false,"issueDate":"2027-01-04","deliveryDate":"2027-01-04","dueDate":"2027-01-18","currency":"EUR","language":"sk","paymentMethod":"card","vatMode":"standard","pricesIncludeVat":true,"buyer":{"name":"Jana Nováková","ico":"","dic":"","icDph":"","street":"Hlavná 1","city":"Bánovce nad Bebravou","postalCode":"95701","countryCode":"SK","email":"jana@example.sk"},"lines":[{"id":"019a5f6e-9999-7a2b-8c3d-4e5f6a7b8c9d","kind":"item","description":"Pracovný zošit","detail":"","quantity":"2","unit":"ks","unitPrice":"19.9","discountPercent":"0","vatRate":23,"totalWithoutVat":"32.36","vat":"7.44","totalWithVat":"39.80"},{"id":"019a5f6e-aaaa-7a2b-8c3d-4e5f6a7b8c9d","kind":"item","description":"Doprava","detail":"","quantity":"1","unit":"ks","unitPrice":"6.9","discountPercent":"0","vatRate":23,"totalWithoutVat":"5.61","vat":"1.29","totalWithVat":"6.90"}],"vatRecap":[{"rate":23,"base":"37.97","vat":"8.73","total":"46.70"}],"totalWithoutVat":"37.97","totalVat":"8.73","totalWithVat":"46.70","paidAmount":"46.70","remainingAmount":"0.00","creditedAmount":"0.00","payments":[{"id":"019a5f6e-8888-7a2b-8c3d-4e5f6a7b8c9d","amount":"46.70","paidOn":"2027-01-04","method":"card"}],"relatedDocument":null,"originalDocument":null,"publicPdfUrl":"https://api.renly.sk/api/v1/public/finance/documents/Xk2…/pdf","sentAt":"2027-01-04T10:15:02+01:00","issuedAt":"2027-01-04T10:15:00+01:00","cancelledAt":null,"createdAt":"2027-01-04T10:15:00+01:00","updatedAt":"2027-01-04T10:15:02+01:00"},"meta":[]}}}},"PartnerOk":{"description":"Partner.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Partner"}}}}}},"PartnerCreated":{"description":"Založený partner.","headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Partner"}}},"example":{"data":{"id":"019a5f6e-9999-7a2b-8c3d-4e5f6a7b8c9d","test":false,"name":"Hotel Tatra s. r. o.","ico":"36512345","dic":"2020123456","icDph":"SK2020123456","registryEntry":"","street":"Hlavná 1","city":"Poprad","postalCode":"05801","countryCode":"SK","email":"uctaren@hoteltatra.sk","phone":"","contacts":[{"id":"019a5f6e-aaaa-7a2b-8c3d-4e5f6a7b8c9d","name":"Eva Kováčová","jobTitle":"","email":"uctaren@hoteltatra.sk","phone":"","note":"","roles":["invoices","reminders"],"isPrimary":true}],"isCustomer":true,"isSupplier":false,"defaultDueDays":30,"documentLanguage":null,"note":"","vatVerifiedAt":"2027-01-04T10:15:00+01:00","createdAt":"2027-01-04T10:15:00+01:00","updatedAt":"2027-01-04T10:15:00+01:00"},"meta":[]}}}},"Invalid":{"description":"Neplatná požiadavka — `finance.document_invalid`, `finance.document_incomplete`, `finance.partner_invalid`, `finance.webhook_invalid` (s `details.fields`), `finance.idempotency_key_required`, `finance.idempotency_key_invalid` alebo `admin.invalid_json`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"finance.document_incomplete","message":"Doklad sa nedá vystaviť — doplňte chýbajúce údaje.","details":{"field":"buyer.city","fields":{"buyer.city":"required"}}}}}}},"Unauthorized":{"description":"Kľúč chýba, je neplatný alebo zrušený (`finance.api_key_unauthorized`).","headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"finance.api_key_unauthorized","message":"API kľúč chýba, je neplatný alebo bol zrušený.","details":[]}}}}},"Forbidden":{"description":"Kľúču chýba oprávnenie (`finance.api_key_scope_missing` s `details.scope`) alebo firma nemá Financie (`finance.api_not_available`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"finance.api_key_scope_missing","message":"API kľúč nemá oprávnenie na túto operáciu.","details":{"scope":"documents:write"}}}}}},"NotFound":{"description":"Záznam neexistuje alebo patrí inej spoločnosti.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"finance.document_not_found","message":"Doklad sa nenašiel.","details":[]}}}}},"Conflict":{"description":"Akciu nemožno urobiť v aktuálnom stave — pozri tabuľku v kapitole [Chyby](#guide/chyby).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"finance.idempotency_key_reused","message":"Tento Idempotency-Key už bol použitý pre inú požiadavku.","details":[]}}}}},"RateLimited":{"description":"Priveľa požiadaviek (`finance.api_rate_limited`).","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","details"],"properties":{"code":{"type":"string","description":"Stabilný kód chyby."},"message":{"type":"string","description":"Text pre človeka, môže sa zmeniť."},"details":{"type":"object","description":"Podrobnosti, napr. `fields`, `scope`, `existingId`."}}}}},"ListMeta":{"type":"object","required":["limit","nextCursor"],"properties":{"limit":{"type":"integer"},"nextCursor":{"type":["string","null"],"description":"Kurzor ďalšej stránky, `null` = posledná stránka."}}},"WriteMeta":{"type":"object","properties":{"sendError":{"type":"string","description":"Kód chyby, keď doklad vznikol, ale e-mail sa nepodarilo odoslať (napr. `finance.document_send_failed`)."}}},"Me":{"type":"object","required":["key","company"],"properties":{"key":{"type":"object","required":["id","name","keyPrefix","mode","scopes","active"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"keyPrefix":{"type":"string","description":"Začiatok kľúča (`rfk_` alebo `rfk_test_` a 12 znakov) — podľa neho ho spoznáte vo Financiách."},"mode":{"type":"string","enum":["live","test"],"description":"`test` = testovací kľúč, doklady mimo radu, exportu, e-mailov a e-faktúr."},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/Scope"}},"createdByName":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"lastUsedAt":{"type":["string","null"],"format":"date-time"},"revokedAt":{"type":["string","null"],"format":"date-time"},"active":{"type":"boolean"}}},"company":{"type":"object","required":["id","tenantId","name","active"],"properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid","description":"ID firmy v Renly."},"name":{"type":"string"},"active":{"type":"boolean","description":"`false` = spoločnosť nad limitom balíčka, API iba číta."}}}}},"Scope":{"type":"string","enum":["documents:read","documents:write","payments:write","partners:read","partners:write","catalog:read","webhooks:write"]},"DocumentType":{"type":"string","description":"`invoice` faktúra, `proforma` zálohová faktúra, `credit_note` dobropis, `corrective_invoice` ťarchopis\n(opravná faktúra na zvýšenie), `payment_receipt` daňový doklad k prijatej platbe. Vystaviť cez\n`POST /documents` sa dá faktúra, zálohová faktúra a dobropis k faktúre mimo Renly (s `originalDocument`).\n","enum":["invoice","proforma","credit_note","corrective_invoice","payment_receipt"]},"PaymentMethod":{"type":"string","enum":["bank_transfer","cash","card","cash_on_delivery","other"],"description":"Prevod, hotovosť, karta, dobierka, iné. Odpoveď môže obsahovať aj `advance` (zápočet zálohy pri vyúčtovaní)."},"Money":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","example":"46.70"},"Decimal":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","example":"19.90"},"Party":{"type":"object","description":"Odberateľ dokladu.","properties":{"name":{"type":"string","maxLength":200},"ico":{"type":"string","pattern":"^\\d{8}$","description":"IČO (8 číslic)."},"dic":{"type":"string","description":"DIČ."},"icDph":{"type":"string","description":"IČ DPH s kódom krajiny, napr. `SK2020123456`."},"street":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"postalCode":{"type":"string","maxLength":10},"countryCode":{"type":"string","pattern":"^[A-Z]{2}$","default":"SK"},"email":{"type":"string","format":"email","maxLength":180,"description":"Adresa, na ktorú pôjde doklad pri `send`."}}},"LineInput":{"type":"object","additionalProperties":false,"required":["description","quantity","unitPrice"],"properties":{"description":{"type":"string","maxLength":500},"detail":{"type":"string","maxLength":1000,"description":"Doplňujúci text pod názvom položky."},"quantity":{"$ref":"#/components/schemas/Decimal"},"unit":{"type":"string","maxLength":10,"example":"ks"},"unitPrice":{"$ref":"#/components/schemas/Decimal"},"discountPercent":{"$ref":"#/components/schemas/Decimal"},"vatRate":{"type":["integer","null"],"enum":[23,19,5,0,27,21,20,18,13,12,10,8,7,null],"description":"Sadzba DPH; neplatiteľ `null`. Sadzby iných štátov iba pri `vatMode: oss`."}}},"CreateDocument":{"type":"object","required":["type","lines"],"properties":{"type":{"type":"string","enum":["invoice","proforma","credit_note"],"description":"`credit_note` iba k faktúre mimo Renly — s `originalDocument`, `correctionReason` a zápornými množstvami."},"originalDocument":{"type":"object","additionalProperties":false,"required":["number","issueDate"],"description":"Dobropis k faktúre vystavenej mimo Renly (napr. v predošlom programe).","properties":{"number":{"type":"string","maxLength":64,"description":"Číslo pôvodnej faktúry."},"issueDate":{"type":"string","format":"date","description":"Dátum vystavenia pôvodnej faktúry."}}},"correctionReason":{"type":"string","maxLength":300,"description":"Dôvod opravy — povinný pri dobropise."},"externalSource":{"type":"string","pattern":"^[a-z0-9][a-z0-9_.-]{0,39}$","description":"Váš systém, napr. `mojeshop`. Vždy spolu s `externalId`."},"externalId":{"type":"string","maxLength":100,"description":"ID objednávky vo vašom systéme. Nie je jedinečné — dobropis ho prevezme."},"partnerId":{"type":"string","format":"uuid","description":"Partner z adresára; doplní odberateľa, splatnosť a jazyk."},"buyer":{"$ref":"#/components/schemas/Party"},"lines":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/LineInput"}},"number":{"type":"string","maxLength":30,"description":"Vlastné číslo mimo radu. Bez neho číslo pridelí rad."},"seriesId":{"type":"string","format":"uuid","description":"Rad z `GET /number-series`; predvolený rad druhu dokladu."},"issueDate":{"type":"string","format":"date"},"deliveryDate":{"type":"string","format":"date"},"dueDate":{"type":"string","format":"date"},"orderNumber":{"type":"string","description":"Číslo objednávky na PDF."},"variableSymbol":{"type":"string","description":"Predvolene číslice čísla dokladu."},"constantSymbol":{"type":"string"},"specificSymbol":{"type":"string"},"paymentMethod":{"$ref":"#/components/schemas/PaymentMethod"},"bankAccountId":{"type":"string","format":"uuid","description":"Účet z `GET /bank-accounts`; predvolený účet spoločnosti."},"currency":{"type":"string","enum":["EUR","CZK","USD","GBP","PLN","HUF","CHF","SEK","NOK","DKK","RON"],"default":"EUR"},"exchangeRate":{"$ref":"#/components/schemas/Decimal"},"language":{"type":"string","enum":["sk","cs","en","de","hu","pl","hr","sl","ro","ru","uk","es","it","nl"],"default":"sk"},"vatMode":{"type":"string","enum":["standard","reverse_charge","exempt","non_payer","oss"]},"vatCountry":{"type":"string","pattern":"^[A-Z]{2}$","description":"Štát spotreby pri `oss` (AT, CZ, DE, HU, PL); predvolene štát odberateľa."},"vatExemptionReason":{"type":"string","maxLength":300,"description":"Povinný pri `exempt`."},"vatExemptionCode":{"type":["string","null"],"enum":["VATEX-EU-79-C","VATEX-EU-132-1A","VATEX-EU-132-1B","VATEX-EU-132-1C","VATEX-EU-132-1D","VATEX-EU-132-1E","VATEX-EU-132-1P","VATEX-EU-132-1G","VATEX-EU-132-1H","VATEX-EU-132-1I","VATEX-EU-132-1J","VATEX-EU-132-1L","VATEX-EU-132-1F","VATEX-EU-132-1M","VATEX-EU-132-1N","VATEX-EU-132-1O","VATEX-EU-132-1Q","VATEX-EU-135-1","VATEX-EU-132",null],"description":"Kód dôvodu oslobodenia (VATEX) pri `exempt` pre e-faktúru, napr. `VATEX-EU-135-1` pri nájme nehnuteľnosti (§ 38). Nepovinný."},"pricesIncludeVat":{"type":"boolean","default":false},"discountPercent":{"$ref":"#/components/schemas/Decimal"},"introText":{"type":"string","description":"Text nad položkami."},"closingText":{"type":"string","description":"Text pod položkami."},"internalNote":{"type":"string","description":"Poznámka viditeľná iba vo Financiách."},"payment":{"$ref":"#/components/schemas/PaymentInput"},"send":{"$ref":"#/components/schemas/SendOption"}}},"PaymentInput":{"type":"object","additionalProperties":false,"required":["paidOn","method"],"properties":{"amount":{"$ref":"#/components/schemas/Money","description":"Bez sumy celý zostatok."},"paidOn":{"type":"string","format":"date"},"method":{"$ref":"#/components/schemas/PaymentMethod"},"note":{"type":"string","maxLength":300}}},"SendInput":{"type":"object","additionalProperties":false,"properties":{"to":{"type":"array","items":{"type":"string","format":"email"},"description":"Príjemcovia; predvolene odberateľ alebo kontaktné osoby partnera."},"cc":{"type":"array","items":{"type":"string","format":"email"}},"subject":{"type":"string","maxLength":200},"message":{"type":"string","maxLength":5000}}},"SendOption":{"description":"`true` = e-mail s predvoleným textom, objekt = vlastní príjemcovia či text, `false` alebo nič = neposlať.","oneOf":[{"type":"boolean"},{"$ref":"#/components/schemas/SendInput"}]},"Document":{"type":"object","required":["id","type","status","paymentStatus","number","issueDate","currency","buyer","lines","totalWithVat","remainingAmount","payments","publicPdfUrl"],"properties":{"id":{"type":"string","format":"uuid"},"type":{"$ref":"#/components/schemas/DocumentType"},"status":{"type":"string","enum":["issued","cancelled"]},"paymentStatus":{"type":["string","null"],"enum":["unpaid","partially_paid","paid","overdue",null],"description":"Stav úhrady faktúry, zálohovej faktúry a ťarchopisu; ostatné `null`."},"number":{"type":"string"},"variableSymbol":{"type":"string"},"orderNumber":{"type":"string"},"externalSource":{"type":["string","null"]},"externalId":{"type":["string","null"]},"test":{"type":"boolean","description":"Testovací doklad z testovacieho kľúča — číslo `TEST-…`, nie je účtovným dokladom."},"issueDate":{"type":"string","format":"date"},"deliveryDate":{"type":["string","null"],"format":"date"},"dueDate":{"type":["string","null"],"format":"date"},"currency":{"type":"string"},"language":{"type":"string"},"paymentMethod":{"type":"string"},"vatMode":{"type":"string"},"vatCountry":{"type":["string","null"],"description":"Štát spotreby pri `oss`."},"pricesIncludeVat":{"type":"boolean"},"buyer":{"type":"object","required":["name","ico","dic","icDph","street","city","postalCode","countryCode","email"],"properties":{"name":{"type":"string"},"ico":{"type":"string"},"dic":{"type":"string"},"icDph":{"type":"string"},"street":{"type":"string"},"city":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string"},"email":{"type":"string"}}},"lines":{"type":"array","items":{"type":"object","required":["kind","description","quantity","unitPrice","vatRate","totalWithoutVat","vat","totalWithVat"],"properties":{"id":{"type":"string","format":"uuid","description":"ID položky — `lineId` čiastočného dobropisu."},"kind":{"type":"string","enum":["item","advance"],"description":"`advance` = odpočet zálohy pri vyúčtovaní."},"description":{"type":"string"},"detail":{"type":"string"},"quantity":{"type":"string"},"unit":{"type":"string"},"unitPrice":{"type":"string"},"discountPercent":{"type":"string"},"vatRate":{"type":["integer","null"]},"totalWithoutVat":{"$ref":"#/components/schemas/Money"},"vat":{"$ref":"#/components/schemas/Money"},"totalWithVat":{"$ref":"#/components/schemas/Money"}}}},"vatRecap":{"type":"array","description":"Rekapitulácia DPH po sadzbách (záväzná pre DPH); bez DPH prázdna.","items":{"type":"object","required":["rate","base","vat","total"],"properties":{"rate":{"type":"integer"},"base":{"$ref":"#/components/schemas/Money"},"vat":{"$ref":"#/components/schemas/Money"},"total":{"$ref":"#/components/schemas/Money"}}}},"totalWithoutVat":{"$ref":"#/components/schemas/Money"},"totalVat":{"$ref":"#/components/schemas/Money"},"totalWithVat":{"$ref":"#/components/schemas/Money"},"paidAmount":{"$ref":"#/components/schemas/Money"},"remainingAmount":{"$ref":"#/components/schemas/Money","description":"Zostáva uhradiť: suma − úhrady − dobropisy."},"creditedAmount":{"$ref":"#/components/schemas/Money","description":"Faktúra: súčet vystavených dobropisov s DPH (kladný)."},"payments":{"type":"array","items":{"type":"object","required":["id","amount","paidOn","method"],"properties":{"id":{"type":"string","format":"uuid"},"amount":{"$ref":"#/components/schemas/Money"},"paidOn":{"type":"string","format":"date"},"method":{"type":"string"}}}},"relatedDocument":{"description":"Dobropis → faktúra, vyúčtovanie → zálohová faktúra.","oneOf":[{"type":"null"},{"type":"object","required":["id","type","number"],"properties":{"id":{"type":"string","format":"uuid"},"type":{"$ref":"#/components/schemas/DocumentType"},"number":{"type":["string","null"]}}}]},"originalDocument":{"description":"Dobropis k faktúre mimo Renly: číslo a dátum pôvodnej faktúry; inak `null`.","oneOf":[{"type":"null"},{"type":"object","required":["number","issueDate"],"properties":{"number":{"type":"string"},"issueDate":{"type":["string","null"],"format":"date"}}}]},"publicPdfUrl":{"type":["string","null"],"format":"uri","description":"PDF bez prihlásenia; `null` pri doklade vystavenom v appke alebo po storne."},"sentAt":{"type":["string","null"],"format":"date-time"},"issuedAt":{"type":["string","null"],"format":"date-time"},"cancelledAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"PartnerContactInput":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"Existujúca osoba; bez `id` vznikne nová."},"name":{"type":"string","maxLength":120},"jobTitle":{"type":"string","maxLength":120},"email":{"type":"string","format":"email","maxLength":180},"phone":{"type":"string","maxLength":40},"note":{"type":"string","maxLength":500},"roles":{"type":"array","items":{"type":"string","enum":["invoices","deals","reminders","copy"]},"description":"`invoices` dostáva doklady, `deals` ponuky a objednávky, `reminders` upomienky, `copy` kópiu."},"isPrimary":{"type":"boolean"}}},"PartnerInput":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","maxLength":200,"description":"Povinné pri založení."},"ico":{"type":"string","pattern":"^\\d{8}$"},"dic":{"type":"string"},"icDph":{"type":"string"},"registryEntry":{"type":"string","maxLength":300,"description":"Zápis v obchodnom registri."},"street":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"postalCode":{"type":"string","maxLength":10},"countryCode":{"type":"string","pattern":"^[A-Z]{2}$","default":"SK"},"email":{"type":"string","format":"email","maxLength":180},"phone":{"type":"string","maxLength":40},"isCustomer":{"type":"boolean","default":true},"isSupplier":{"type":"boolean","default":false},"defaultDueDays":{"type":["integer","null"],"minimum":0,"maximum":365,"description":"Splatnosť dokladov partnera v dňoch."},"documentLanguage":{"type":["string","null"],"enum":["sk","cs","en","de","hu","pl","hr","sl","ro","ru","uk","es","it","nl",null]},"note":{"type":"string","maxLength":2000},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/PartnerContactInput"}}}},"Partner":{"type":"object","required":["id","test","name","ico","dic","icDph","street","city","postalCode","countryCode","email","phone","contacts","isCustomer","isSupplier","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"test":{"type":"boolean","description":"Testovací partner založený testovacím kľúčom."},"name":{"type":"string"},"ico":{"type":"string"},"dic":{"type":"string"},"icDph":{"type":"string"},"registryEntry":{"type":"string"},"street":{"type":"string"},"city":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string"},"email":{"type":"string","description":"E-mail hlavnej kontaktnej osoby."},"phone":{"type":"string"},"contacts":{"type":"array","items":{"type":"object","required":["id","name","email","roles","isPrimary"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"jobTitle":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"note":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}},"isPrimary":{"type":"boolean"}}}},"isCustomer":{"type":"boolean"},"isSupplier":{"type":"boolean"},"defaultDueDays":{"type":["integer","null"]},"documentLanguage":{"type":["string","null"]},"note":{"type":"string"},"vatVerifiedAt":{"type":["string","null"],"format":"date-time","description":"Kedy bolo IČ DPH overené vo VIES."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"PriceListItem":{"type":"object","required":["id","name","detail","code","unit","unitPrice","pricesIncludeVat","vatRate","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"detail":{"type":"string"},"code":{"type":"string","description":"Vlastný kód položky (môže byť prázdny)."},"unit":{"type":"string"},"unitPrice":{"$ref":"#/components/schemas/Decimal"},"pricesIncludeVat":{"type":"boolean","description":"`true` = `unitPrice` je s DPH."},"vatRate":{"type":["integer","null"]},"updatedAt":{"type":"string","format":"date-time"}}},"NumberSeries":{"type":"object","required":["id","documentType","name","isDefault","nextNumberPreview"],"properties":{"id":{"type":"string","format":"uuid"},"documentType":{"$ref":"#/components/schemas/DocumentType"},"name":{"type":"string"},"isDefault":{"type":"boolean","description":"Predvolený rad druhu dokladu."},"nextNumberPreview":{"type":"string","description":"Číslo, ktoré by rad vydal dnes."}}},"BankAccount":{"type":"object","required":["id","bankName","iban","bic","currency","isDefault"],"properties":{"id":{"type":"string","format":"uuid"},"bankName":{"type":"string"},"iban":{"type":"string"},"bic":{"type":"string"},"currency":{"type":"string"},"isDefault":{"type":"boolean"}}},"WebhookEvent":{"type":"string","enum":["document.issued","document.payment_recorded","document.paid","document.payment_deleted","document.cancelled","document.sent"]},"Webhook":{"type":"object","required":["id","url","test","events","createdAt","consecutiveFailures"],"properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"test":{"type":"boolean","description":"Webhook testovacieho kľúča — dostáva iba udalosti testovacích dokladov."},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"}},"createdAt":{"type":"string","format":"date-time"},"lastSuccessAt":{"type":["string","null"],"format":"date-time"},"lastFailureAt":{"type":["string","null"],"format":"date-time"},"consecutiveFailures":{"type":"integer"}}},"WebhookDelivery":{"type":"object","required":["id","event","documentId","status","attempts","createdAt"],"properties":{"id":{"type":"string","format":"uuid","description":"Rovnaké ako hlavička `X-Renly-Delivery`."},"event":{"$ref":"#/components/schemas/WebhookEvent"},"documentId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","delivered","failed"]},"attempts":{"type":"integer"},"lastStatusCode":{"type":["integer","null"]},"lastError":{"type":["string","null"]},"lastAttemptAt":{"type":["string","null"],"format":"date-time"},"deliveredAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}}}}}