FeaturesHow it worksIntegrationsPricingFAQContact

Guides

Rýchly štart

Za päť minút vystavíte prvú faktúru. Potrebujete prístup do Renly Financií s oprávnením upravovať nastavenie a dokončený úvodný sprievodca Financií (údaje firmy, ktoré budú na dokladoch — obchodné meno, adresa, IČO, postavenie voči DPH). Bez neho API vystavenie odmietne chybou 409 finance.profile_incomplete.

1. Vytvorte kľúč

  1. Vo Financiách otvorte Nastavenie → API a e-shopy (finance.renly.sk/nastavenie/api).
  2. Kliknite na Nový API kľúč, zadajte názov systému (napr. „E-shop mojafirma.sk“) a nechajte oprávnenia Čítanie dokladov a Vystavovanie dokladov.
  3. Kľúč rfk_… sa ukáže iba raz. Uložte ho do tajných nastavení svojho systému.

Ďalej v príkladoch je kľúč v premennej prostredia:

bash
export RENLY_FINANCE_KEY='rfk_…'

2. Overte kľúč

bash
curl -s https://api.renly.sk/api/v1/finance/external/me \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY"

Odpoveď ukáže názov kľúča, jeho oprávnenia a spoločnosť, za ktorú bude systém vystavovať doklady.

3. Vystavte faktúru

bash
curl -s https://api.renly.sk/api/v1/finance/external/documents \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY" \
  -H "Idempotency-Key: mojsystem:objednavka-1001:invoice" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "invoice",
    "externalSource": "mojsystem",
    "externalId": "objednavka-1001",
    "buyer": { "name": "Jana Nováková", "street": "Hlavná 1", "city": "Trenčín",
               "postalCode": "91101", "countryCode": "SK", "email": "jana@example.sk" },
    "lines": [ { "description": "Konzultácia", "quantity": "2", "unit": "h", "unitPrice": "50", "vatRate": 23 } ],
    "send": false
  }'

Odpoveď 201 obsahuje vystavený doklad: number (číslo z vášho radu), sumy, paymentStatus a publicPdfUrl — odkaz na PDF, ktorý môžete poslať zákazníkovi. Doklad hneď uvidíte aj vo Financiách v zozname Doklady.

4. Ďalej

Prihlásenie a oprávnenia

Každá požiadavka posiela kľúč v hlavičke Authorization:

http
Authorization: Bearer rfk_AbC123def456…
  • Kľúč patrí jednej spoločnosti vo Financiách. Všetky doklady, partneri aj cenník sú tej spoločnosti. Keď máte vo Financiách viac spoločností, každá potrebuje vlastný kľúč.
  • Kľúč je ostrý (rfk_…) alebo testovací (rfk_test_…), pozri testovanie.
  • Kľúč platí iba pre cesty /api/v1/finance/external/…. Prihlásenie do appky ním nefunguje a naopak.
  • Neplatný, zrušený alebo chýbajúci kľúč vráti vždy 401 finance.api_key_unauthorized.

Oprávnenia kľúča vyberiete pri jeho vytvorení. Dajte kľúču iba tie, ktoré systém naozaj potrebuje.

oprávneniečo dovolí
documents:readčítať doklady a ich PDF, číselné rady a bankové účty
documents:writevystaviť faktúru a zálohovú faktúru, dobropis, vyúčtovanie zálohy, storno a odoslanie e-mailom
payments:writezapísať úhradu dokladu
partners:readčítať adresár partnerov
partners:writezaložiť a upraviť partnera
catalog:readčítať cenník položiek
webhooks:writeregistrovať a spravovať webhooky

Keď kľúču oprávnenie chýba, API vráti 403 finance.api_key_scope_missing a v error.details.scope uvedie chýbajúce oprávnenie. Oprávnenia existujúceho kľúča sa meniť nedajú — vytvorte nový kľúč a starý zrušte.

Spoločnosť a balíček. API funguje, kým má firma Financie v balíčku. Keď je spoločnosť nad limitom balíčka (neaktívna), API z nej iba číta a zápis vráti 409 finance.company_inactive.

AI agenti. Ak chcete Financie ovládať z AI asistenta (Claude, ChatGPT), nepoužívajte API kľúč — pripojte asistenta cez MCP server Renly. Návod je v Pomocníkovi v appke („AI asistent cez MCP“).

Testovanie

Na vývoj a skúšanie si vytvorte testovací kľúč: vo Financiách Nastavenie → API a e-shopy → Nový kľúč, režim Testovací. Kľúč začína rfk_test_ a funguje vo všetkých balíčkoch s Financiami, aj v bezplatnom.

Testovací kľúč volá tie isté cesty a dostane tie isté odpovede ako ostrý, ale nič ostré nevznikne:

  • Doklady dostanú číslo TEST-000001, TEST-000002… mimo číselného radu. Vlastné number dostane predponu (TEST-2027000123). Číslovanie vašich skutočných dokladov sa nezmení.
  • Testovacie doklady nejdú do exportu pre účtovníka, prehľadov ani párovania s bankou a nerátajú sa do počtu dokladov balíčka.
  • E-mail neodíde. send a POST /documents/{id}/send odoslanie iba zaznamenajú (sentAt, história, webhook document.sent). E-faktúra z testovacieho dokladu nevznikne.
  • PDF má vodoznak „TESTOVACÍ – NEPLATNÝ“ a nemá QR kód na platbu. Verejný odkaz publicPdfUrl funguje.
  • Odpoveď má hlavičku X-Renly-Test-Mode: true a doklad, partner aj webhook pole test: true. GET /me vráti key.mode: "test".

Oddelenie od ostrej prevádzky. Testovací kľúč vidí a mení iba testovacie doklady, ostrý kľúč iba ostré (cudzí doklad vráti 404). Idempotency-Key sú oddelené: ten istý kľúč po prechode na ostrý kľúč vystaví nový ostrý doklad. Cenník, číselné rady, bankové účty a partneri sú spoločné, takže seriesId, bankAccountId aj partnerId platia v oboch režimoch — na ostrú prevádzku stačí vymeniť kľúč.

  • Partner založený testovacím kľúčom je testovací: vidí ho iba testovací kľúč. Ostrého partnera testovací kľúč iba číta (PATCH vráti 403 finance.api_test_mode_forbidden).
  • Webhook zaregistrovaný testovacím kľúčom dostáva iba udalosti testovacích dokladov a telo udalosti má "test": true. Ostré webhooky testovacie udalosti nedostanú.

Zmazanie. Testovacie doklady a partnerov zmažete vo Financiách v Nastavenie → API a e-shopy → Testovacie dáta alebo jednotlivo z detailu dokladu. Testovacie dáta staršie ako 30 dní sa mažú samy. Spoločnosť môže mať naraz najviac 1 000 testovacích dokladov (409 finance.api_test_limit).

Na čítanie skutočných dokladov použite ostrý kľúč s oprávneniami iba na čítanie.

Formát údajov

  • Telo požiadavky aj odpovede je JSON v UTF-8 (Content-Type: application/json).
  • Sumy, ceny a množstvá sú reťazce s desatinnou bodkou: "19.90", "2", "-1". Celé číslo JSON sa prijme tiež, číslo s desatinnou čiarkou alebo float nie. Sumy v odpovedi majú vždy dve desatinné miesta ("46.70"), ceny a množstvá najkratší zápis ("19.9").
  • Množstvo najviac 3 desatinné miesta, cena najviac 4, zľava v percentách 0–100 s najviac 2 miestami.
  • Dátumy sú YYYY-MM-DD (slovenský kalendárny deň), časy ISO 8601 s časovou zónou (2027-01-04T10:15:00+01:00).
  • ID sú UUID v textovom tvare.
  • Prázdne textové polia sú v odpovedi "", nie null. null znamená, že údaj neexistuje (napríklad sentAt neodoslaného dokladu).
  • Úspešná odpoveď má tvar { "data": …, "meta": { … } }, chyba { "error": { "code", "message", "details" } }.

DPH. Ceny položiek sú bez DPH. Keď váš systém počíta ceny s DPH (bežné v B2C), pošlite "pricesIncludeVat": true a Financie DPH dopočítajú. Sadzby sú 23, 19 a 5. Režimy DPH (vatMode):

vatModekedy
standardbežný doklad platiteľa DPH (predvolené)
reverse_chargeprenesenie daňovej povinnosti, napr. firma z inej krajiny EÚ s IČ DPH — sadzby sa vynulujú
exemptoslobodené plnenie, napr. zákazník mimo EÚ — povinný vatExemptionReason
non_payerdodávateľ nie je platiteľ DPH (nastaví sa sám podľa profilu spoločnosti)
ossspotrebiteľ v inom štáte EÚ, DPH štátu spotreby — iba spoločnosť registrovaná v OSS

OSS. Pri "vatMode": "oss" pošlite vatCountry (štát spotreby, predvolene štát odberateľa) a sadzby toho š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 štáty Financie zatiaľ nepoznajú — takú objednávku vystavte ručne.

Mena a jazyk. currency je EUR alebo CZK, USD, GBP, PLN, HUF, CHF, SEK, NOK, DKK, RON (kurz doplní Financie z ECB, alebo pošlite exchangeRate). language dokladu je kód ISO 639-1: sk, cs, en, de, hu, pl, hr, sl, ro, ru, uk, es, it, nl.

Stránkovanie

Zoznamy (doklady, partneri, cenník) vracajú najviac limit záznamov (predvolene 50, najviac 100) a v meta.nextCursor reťazec ďalšej stránky. Ďalšiu stránku získate rovnakou požiadavkou s parametrom cursor:

bash
curl -s "https://api.renly.sk/api/v1/finance/external/documents?from=2027-01-01&limit=100&cursor=$CURSOR" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY"

Keď je meta.nextCursor null, ďalšia stránka nie je. Kurzor je nepriehľadný — neskladajte ho ani neupravujte a pri zmene filtrov začnite bez neho.

Idempotencia

Sieť vypadne, webhook e-shopu príde dvakrát, proces spadne po odoslaní požiadavky. Aby zákazník nedostal dve faktúry, každý POST na doklady, úhrady a partnerov vyžaduje hlavičku Idempotency-Key.

http
Idempotency-Key: mojsystem:objednavka-1001:invoice
  • Kľúč je 1–255 viditeľných znakov ASCII bez medzier a je jedinečný v rámci spoločnosti. Odporúčaný tvar je <systém>:<objednávka>:<akcia> — jednoznačne určuje, čo chcete urobiť.
  • Prvá úspešná požiadavka si kľúč zapamätá. Rovnaký kľúč s rovnakým telom vráti ten istý doklad (aktuálny stav), pôvodný HTTP stav a hlavičku Idempotent-Replayed: true — nič sa nevystaví ani nepošle druhýkrát.
  • Rovnaký kľúč s iným telom alebo pre inú akciu vráti 409 finance.idempotency_key_reused. Kľúč nikdy nepoužívajte pre inú objednávku.
  • Chybná požiadavka (4xx, 5xx) sa nezapamätá. Po oprave pošlite požiadavku znova s tým istým kľúčom.
  • 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).
  • Zapamätané kľúče sa nemažú, takže opakovanie funguje aj po dňoch.

PATCH partnera a registrácia webhooku hlavičku nepotrebujú — opakovaná úprava dá ten istý výsledok a tá istá adresa webhooku sa druhýkrát nezaregistruje (409 finance.webhook_duplicate).

Chyby

Chyba má HTTP stav a stabilný kód v error.code. Podľa kódu sa rozhodujte vo svojom systéme; message je text pre človeka a môže sa zmeniť.

json
{ "error": { "code": "finance.document_incomplete", "message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
             "details": { "field": "buyer.city", "fields": { "buyer.city": "required" } } } }

Pri chybe tvaru je v details.fields mapa pole → dôvod (required, invalid, out_of_range, taken). Pole položky má tvar lines.0.unitPrice.

stavkódčo spraviť
400admin.invalid_jsontelo nie je platný JSON objekt
400finance.document_invalid, finance.partner_invalid, finance.webhook_invalidopravte polia z details.fields a pošlite znova s tým istým Idempotency-Key
400finance.document_incompletedoklad nemá všetko na vystavenie (details.fields); nevznikne ani ako koncept
400finance.idempotency_key_required, finance.idempotency_key_invaliddoplňte alebo opravte hlavičku Idempotency-Key
401finance.api_key_unauthorizedkľúč chýba, je neúplný alebo zrušený — neopakujte
403finance.api_key_scope_missingkľúču chýba oprávnenie z details.scope
403finance.api_not_availablefirma nemá Financie v balíčku alebo je vypnutá
403finance.api_test_mode_forbiddentestovací kľúč mení iba testovacích partnerov (testovanie)
404finance.document_not_found, finance.partner_not_found, finance.price_list_item_not_found, finance.webhook_not_foundzáznam neexistuje alebo patrí inej spoločnosti
409finance.document_not_editableakcia sa na doklad v jeho stave nedá urobiť (napr. storno uhradenej zálohy)
409finance.payment_exceeds_totalúhrada je vyššia ako zostatok (details.remainingAmount)
409finance.document_issue_quotafirma vyčerpala počet dokladov balíčka
409finance.api_test_limitspoločnosť má 1 000 testovacích dokladov — zmažte ich vo Financiách (details.limit)
409finance.document_number_conflictvlastné číslo number už má iný doklad
409finance.partner_duplicatepartner s rovnakým IČO už existuje (details.existingId)
409finance.idempotency_key_reusedten istý Idempotency-Key s iným telom
409finance.company_inactivespoločnosť je nad limitom balíčka, iba čítanie
409finance.profile_incompletespoločnosť nemá vo Financiách vyplnené údaje firmy (details.fields) — dokončite sprievodcu alebo Nastavenie → Firma
429finance.api_rate_limitedpočkajte počet sekúnd z hlavičky Retry-After
5xx—zopakujte s tým istým Idempotency-Key

Doklad, ktorý vznikol, ale e-mail sa nepodarilo odoslať, vráti úspech (201) s meta.sendError (kód chyby). E-mail pošlete znova cez POST /documents/{id}/send s novým Idempotency-Key.

Limity

čolimit
požiadavky120 za minútu na kľúč, potom 429 s hlavičkou Retry-After (sekundy)
aktívne kľúče10 na spoločnosť
webhooky5 adries na spoločnosť
stránka zoznamunajviac 100 záznamov (limit), doklady jednej objednávky najviac 50
verejné PDF120 stiahnutí za 10 minút na odkaz a IP adresu
dokladypodľa balíčka Financií (409 finance.document_issue_quota)

Pri synchronizácii veľkého množstva údajov posielajte požiadavky postupne a reagujte na Retry-After. O zmenách sa radšej nechajte informovať webhookmi, než by ste zoznamy čítali stále dokola.

Verzovanie a zmeny

Verzia API je v adrese (/api/v1/…). V rámci verzie 1 sa zmeny robia iba spätne kompatibilne:

  • pribúdajú nové endpointy, nepovinné parametre a polia v odpovedi,
  • pribúdajú nové hodnoty zoznamov (napr. nový druh dokladu, nová udalosť webhooku) a nové chybové kódy.

Váš systém preto má ignorovať neznáme polia a s neznámou hodnotou zaobchádzať rozumne (napr. neznámy druh dokladu preskočiť). Zmenu, ktorá by existujúcu integráciu rozbila, by sme vydali ako novú verziu v adrese a vopred oznámili e-mailom správcom spoločností, ktoré API používajú.

Strojovo čitateľná špecifikácia OpenAPI 3.1 je na api.renly.sk/api/v1/public/finance/api/openapi.json — importujete ju do Postmana, Insomnie alebo generátora klienta.

Bezpečnosť kľúča

Kľúč má rovnakú moc ako človek, ktorý vo Financiách vystavuje doklady. Narábajte s ním ako s heslom.

  • Kľúč patrí iba na server — do tajných nastavení, trezoru alebo premennej prostredia. Nikdy nie do prehliadača, mobilnej aplikácie, zdrojového kódu v repozitári ani do logov.
  • 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 uvidíte „API: <názov kľúča>“ a pri kľúči čas posledného použitia.
  • Dajte kľúču iba potrebné oprávnenia. E-shop, ktorý iba vystavuje faktúry, nepotrebuje meniť partnerov.
  • Pri podozrení na únik kľúč vo Financiách okamžite zrušte (Nastavenie → API a e-shopy → Zrušiť kľúč) a vytvorte nový. Zrušenie platí hneď a nedá sa vrátiť.
  • Webhook prijímajte iba cez HTTPS a vždy overte podpis (kapitola Webhooky).

Scenár: faktúra k zaplatenej objednávke

Zákazník zaplatil kartou alebo v hotovosti. Vystavte faktúru rovno s úhradou a pošlite ju e-mailom:

bash
curl -s https://api.renly.sk/api/v1/finance/external/documents \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY" \
  -H "Idempotency-Key: mojeshop:2027000123:invoice" \
  -H "Content-Type: application/json" \
  -d '{
    "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
  }'
  • externalSource a externalId spoja doklad s objednávkou — podľa nich neskôr nájdete všetky jej doklady.
  • Firma: doplňte do buyer aj ico, dic a icDph. Firme z EÚ s IČ DPH pošlite "vatMode": "reverse_charge".
  • Zľava: discountPercent pri položke, alebo samostatná položka so záporným množstvom.
  • Bez payment je faktúra neuhradená a splatnosť dostane podľa nastavenia spoločnosti alebo partnera.

Scenár: platba prevodom so zálohovou faktúrou

  1. Pri objednávke vystavte zálohovú faktúru: "type": "proforma", "paymentMethod": "bank_transfer". PDF má QR kód na platbu (PAY by square) a variabilný symbol.
  2. Keď peniaze prídu, zapíšte úhradu: POST /documents/{id}/payments s { "paidOn": "2027-01-06", "method": "bank_transfer" }. Ak úhradu zapíše účtovník z bankového výpisu, dozviete sa to webhookom document.paid.
  3. Vystavte faktúru, ktorá zálohu vyúčtuje: POST /documents/{id}/final-invoice s { "send": true }.

Nezaplatenú zálohovú faktúru zrušíte cez POST /documents/{id}/cancel s { "reason": "Objednávka zrušená" }.

Scenár: poslať doklad e-mailom

Pri vystavení stačí "send": true — Financie pošlú e-mail s PDF na buyer.email (alebo kontaktné osoby partnera) s predmetom a textom v jazyku dokladu, rovnako ako tlačidlo Odoslať v appke. Vlastných príjemcov a text pošlete objektom:

json
"send": { "to": ["uctaren@firma.sk"], "cc": ["nakup@firma.sk"],
          "subject": "Faktúra k objednávke 1001", "message": "Dobrý deň, posielame faktúru…" }

Už vystavený doklad pošlete (aj znova) cez POST /documents/{id}/send. Každé odoslanie potrebuje nový Idempotency-Key, napr. mojsystem:objednavka-1001:invoice:send-2. Čas posledného odoslania je v sentAt.

Scenár: zistiť, či je doklad uhradený

Stav úhrady je v poli paymentStatus: unpaid, partially_paid, paid alebo overdue (po splatnosti). Zostatok je v remainingAmount, jednotlivé úhrady v payments.

  • Odporúčané: zaregistrujte webhook s udalosťou document.paid — Financie vám dajú vedieť hneď, ako je doklad uhradený, aj keď úhradu spároval účtovník z bankového výpisu.
  • Bez webhooku: raz za čas si prečítajte neuhradené doklady:
bash
curl -s "https://api.renly.sk/api/v1/finance/external/documents?type=invoice,proforma&paymentStatus=unpaid,partially_paid,overdue" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY"

Doklady jednej objednávky nájdete podľa externalSource a externalId: GET /documents?externalSource=mojeshop&externalId=2027000123.

Scenár: partneri

Stáli odberatelia (firmy) môžu byť v adresári Financií. Doklad pre partnera potom stačí vystaviť s partnerId — Financie doplnia odberateľa, splatnosť partnera, jazyk dokladu aj príjemcov e-mailu z kontaktných osôb.

  1. Nájdite partnera podľa IČO alebo názvu: GET /partners?q=36512345.
  2. Ak neexistuje, založte ho: POST /partners s Idempotency-Key, napr. mojsystem:zakaznik-77:partner. Partner s IČO, ktoré už v adresári je, vráti 409 finance.partner_duplicate s details.existingId.
  3. Vystavte doklad s "partnerId": "…" (bez buyer). Ak pošlete aj buyer, má prednosť pred adresárom.
  4. Zmenu adresy zapíšte PATCH /partners/{id} — pošlite iba menené polia. Zmena sa prejaví na nových dokladoch; vystavené doklady majú odberateľa uloženého v čase vystavenia.

Partnera cez API nezmažete — archivovať ho môže iba človek v appke.

Scenár: cenník

Ak vediete položky (služby, tovar) v cenníku Financií, váš systém si ich môže načítať (GET /price-list-items, oprávnenie catalog:read) a použiť ich názov, jednotku, cenu a sadzbu DPH v položkách dokladu. Hľadanie: ?q=konzultácia.

Položka cenníka má unitPrice buď bez DPH, alebo s DPH podľa pricesIncludeVat. Na doklade musia byť všetky položky rovnako — keď kombinujete položky s cenou s DPH a bez nej, prepočítajte ich alebo vystavte "pricesIncludeVat" podľa väčšiny a cenu druhých upravte. Cenník mení iba človek v appke.

Scenár: vrátenie tovaru

POST /documents/{id}/credit-note s { "reason": "Vrátenie tovaru", "send": true } vystaví dobropis celej faktúry. Dobropis má v relatedDocument pôvodnú faktúru a prevezme jej externalSource a externalId.

Čiastočné vrátenie (jeden kus, zľava pri reklamácii, poštovné):

  • vybrané položky — { "reason": "Vrátený tovar", "lines": [ { "lineId": "…", "quantity": "1" } ] }; lineId je lines[].id faktúry, množstvo kladné a najviac to, čo z položky ešte nevrátili predošlé dobropisy,
  • suma s DPH — { "reason": "Reklamácia 2027000123-R1", "amount": "10.00", "description": "Zľava – reklamácia" }; Financie ju rozdelia po sadzbách DPH faktúry.

Dobropisov k jednej faktúre môže byť viac; spolu ani v žiadnej sadzbe DPH nesmú prekročiť faktúru (409 finance.credit_note_exceeds_invoice s remainingAmount, pri položke finance.credit_note_exceeds_line). Faktúra má v creditedAmount súčet dobropisov a remainingAmount je po ich odpočte. Pre opakovanie použite vlastný Idempotency-Key každého vrátenia (napr. mojeshop:2027000123-R1:credit-note).

Faktúra zo starého programu: dobropis k faktúre, ktorá vo Financiách nie je, vystavíte cez POST /documents s "type": "credit_note", correctionReason, originalDocument (number a issueDate pôvodnej faktúry) a položkami so záporným množstvom.

Webhooky

Webhook je HTTPS adresa vášho systému, na ktorú Financie pošlú POST pri každej zmene dokladu — aj pri zmene urobenej v appke, z bankového výpisu alebo automaticky (upomienka). Registrujete ho cez POST /webhooks (oprávnenie webhooks:write); odpoveď obsahuje secret na overenie podpisu — iba raz.

udalosťkedy
document.issuedvystavený doklad, aj dobropis a vyúčtovanie zálohy
document.payment_recordedzapísaná úhrada (aj čiastočná)
document.paiddoklad je po úhrade celý uhradený
document.payment_deletedúhrada bola zmazaná
document.cancelledstornovaná zálohová faktúra
document.sentdoklad alebo upomienka odoslaná e-mailom

Hlavičky požiadavky:

hlavičkahodnota
X-Renly-Eventudalosť, napr. document.paid
X-Renly-DeliveryID doručenia — rovnaké pri každom pokuse
X-Renly-Timestampčas pokusu (Unix sekundy)
X-Renly-Signaturesha256= + hex HMAC-SHA256 tajomstva nad "<X-Renly-Timestamp>.<telo>"
json
{ "id": "019a…", "type": "document.paid", "createdAt": "2027-01-04T10:15:00+01:00", "companyId": "019a…",
  "test": false,
  "data": {
    "document": { "id": "019a…", "type": "invoice", "status": "issued", "paymentStatus": "paid",
                  "number": "2027001", "variableSymbol": "2027001", "externalSource": "mojeshop",
                  "externalId": "2027000123", "currency": "EUR", "totalWithVat": "46.70",
                  "paidAmount": "46.70", "remainingAmount": "0.00", "relatedDocumentId": null },
    "payment": { "id": "019a…", "amount": "46.70" } } }

Overenie podpisu (PHP):

php
$body = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_RENLY_TIMESTAMP'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_RENLY_SIGNATURE'] ?? '') || abs(time() - (int) $timestamp) > 300) {
    http_response_code(401);
    exit;
}

Node.js:

js
import { createHmac, timingSafeEqual } from 'node:crypto';

const verify = (rawBody, headers, secret) => {
  const timestamp = headers['x-renly-timestamp'] ?? '';
  const expected = 'sha256=' + createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
  const received = headers['x-renly-signature'] ?? '';
  return expected.length === received.length
    && timingSafeEqual(Buffer.from(expected), Buffer.from(received))
    && Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
};

Pravidlá:

  • Odpovedzte 2xx do 10 sekúnd a prácu urobte až potom (fronta). Presmerovanie sa nesleduje.
  • Neúspešné doručenie Financie zopakujú o 1 min, 5 min, 30 min, 2 h a 12 h (spolu 6 pokusov). Históriu nájdete cez GET /webhooks/{id}/deliveries.
  • Ten istý webhook môže prísť viackrát (rovnaké X-Renly-Delivery) — spracujte ho iba raz.
  • Poradie doručení nie je zaručené. data.document je stav v čase udalosti; aktuálny stav si načítajte cez GET /documents/{id}.

Reference

Kľúč

Overenie kľúča a spoločnosti, ku ktorej patrí.

Kľúč a spoločnosť

GET/me

no permission needed

Overí kľúč a vráti jeho oprávnenia a spoločnosť, za ktorú systém pracuje. Nepotrebuje oprávnenie.

Example request

bash
curl -s "https://api.renly.sk/api/v1/finance/external/me" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY"

Responses

200
Kľúč je platný.
json
{
  "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": []
}
FieldTypeRequiredDescription
dataMeyes
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_unauthorized",
    "message": "API kľúč chýba, je neplatný alebo bol zrušený.",
    "details": []
  }
}
429
Priveľa požiadaviek (finance.api_rate_limited).

Object: Error

FieldTypeRequiredDescription
errorobjectyes
error.codestringyes
Stabilný kód chyby.
error.messagestringyes
Text pre človeka, môže sa zmeniť.
error.detailsobjectyes
Podrobnosti, napr. fields, scope, existingId.

Doklady

Faktúry, zálohové faktúry, dobropisy a ich PDF.

Zoznam dokladov

GET/documents

Permission: documents:read

Dva spôsoby hľadania:

  • Doklady objednávky — s externalSource a externalId vráti všetky doklady jednej objednávky (zálohová faktúra, faktúra, dobropisy) od najstaršieho, najviac 50, bez stránkovania.
  • Všetky doklady — bez nich vráti vystavené a stornované účtovné doklady spoločnosti od najnovšieho (podľa dátumu vystavenia a čísla) s filtrami a stránkovaním. Aj doklady vystavené v appke alebo iným systémom.

Koncepty (rozpísané doklady v appke), cenové ponuky, objednávky a dodacie listy API nevracia.

Parameters

NameInTypeRequiredDescription
externalSourcequerystringno
Systém objednávky, ako pri vystavení. Iba spolu s externalId.
externalIdquerystringno
ID objednávky v systéme. Iba spolu s externalSource.
typequerystringno
Druhy dokladu oddelené čiarkou.
statusquerystringno
issued (vystavený) alebo cancelled (stornovaný), oddelené čiarkou. Predvolene oba.
paymentStatusquerystringno
unpaid, partially_paid, paid, overdue, oddelené čiarkou.
partnerIdquerystring (uuid)no
Iba doklady partnera z adresára.
fromquerystring (date)no
Dátum vystavenia od (vrátane).
toquerystring (date)no
Dátum vystavenia do (vrátane).
qquerystringno
Hľadanie v čísle dokladu, mene a IČO odberateľa.
cursorquerystringno
meta.nextCursor predchádzajúcej stránky.
limitqueryintegerno
Počet záznamov na stránku.

Default: 50

Example request

bash
curl -s "https://api.renly.sk/api/v1/finance/external/documents" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY"

Responses

200
Doklady.
FieldTypeRequiredDescription
dataDocument[]yes
metaListMetayes
400
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.

Object: Error

json
{
  "error": {
    "code": "finance.document_incomplete",
    "message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
    "details": {
      "field": "buyer.city",
      "fields": {
        "buyer.city": "required"
      }
    }
  }
}
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_unauthorized",
    "message": "API kľúč chýba, je neplatný alebo bol zrušený.",
    "details": []
  }
}
403
Kľúču chýba oprávnenie (finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_scope_missing",
    "message": "API kľúč nemá oprávnenie na túto operáciu.",
    "details": {
      "scope": "documents:write"
    }
  }
}
429
Priveľa požiadaviek (finance.api_rate_limited).

Object: Error

FieldTypeRequiredDescription
errorobjectyes
error.codestringyes
Stabilný kód chyby.
error.messagestringyes
Text pre človeka, môže sa zmeniť.
error.detailsobjectyes
Podrobnosti, napr. fields, scope, existingId.

Vystaviť faktúru alebo zálohovú faktúru

POST/documents

Permission: documents:write

Vystaví doklad hneď — dostane číslo z radu, PDF a odkaz publicPdfUrl. Obsah je rovnaký ako formulár dokladu v appke. Neposlané polia dostanú hodnotu nového dokladu v appke: rad pre druh dokladu, vystavenie dnes, dodanie v deň vystavenia (zálohová faktúra bez dodania), splatnosť podľa partnera alebo nastavenia spoločnosti, predvolený bankový účet a texty vzhľadu dokladu.

Povinné sú type, lines a odberateľ — buyer (meno, ulica, mesto) alebo partnerId. Neúplný doklad je 400 finance.document_incomplete a nevznikne ani ako koncept.

Parameters

NameInTypeRequiredDescription
Idempotency-Keyheaderstringyes
Jedinečný kľúč zápisu v spoločnosti, 1–255 viditeľných znakov ASCII. Pozri Idempotencia.

Request body

Object: CreateDocument

json
{
  "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
}

Example request

bash
curl -s -X POST "https://api.renly.sk/api/v1/finance/external/documents" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY" \
  -H "Idempotency-Key: mojeshop:2027000123:invoice" \
  -H "Content-Type: application/json" \
  -d '{
  "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
Vystavený doklad.
json
{
  "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": []
}
FieldTypeRequiredDescription
dataDocumentyes
metaWriteMetano
400
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.

Object: Error

json
{
  "error": {
    "code": "finance.document_incomplete",
    "message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
    "details": {
      "field": "buyer.city",
      "fields": {
        "buyer.city": "required"
      }
    }
  }
}
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_unauthorized",
    "message": "API kľúč chýba, je neplatný alebo bol zrušený.",
    "details": []
  }
}
403
Kľúču chýba oprávnenie (finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_scope_missing",
    "message": "API kľúč nemá oprávnenie na túto operáciu.",
    "details": {
      "scope": "documents:write"
    }
  }
}
409
Akciu nemožno urobiť v aktuálnom stave — pozri tabuľku v kapitole Chyby.

Object: Error

json
{
  "error": {
    "code": "finance.idempotency_key_reused",
    "message": "Tento Idempotency-Key už bol použitý pre inú požiadavku.",
    "details": []
  }
}
429
Priveľa požiadaviek (finance.api_rate_limited).

Object: Error

FieldTypeRequiredDescription
errorobjectyes
error.codestringyes
Stabilný kód chyby.
error.messagestringyes
Text pre človeka, môže sa zmeniť.
error.detailsobjectyes
Podrobnosti, napr. fields, scope, existingId.

Detail dokladu

GET/documents/{documentId}

Permission: documents:read

Parameters

NameInTypeRequiredDescription
documentIdpathstring (uuid)yes

Example request

bash
curl -s "https://api.renly.sk/api/v1/finance/external/documents/${DOCUMENT_ID}" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY"

Responses

200
Doklad.
FieldTypeRequiredDescription
dataDocumentyes
metaWriteMetano
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_unauthorized",
    "message": "API kľúč chýba, je neplatný alebo bol zrušený.",
    "details": []
  }
}
403
Kľúču chýba oprávnenie (finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_scope_missing",
    "message": "API kľúč nemá oprávnenie na túto operáciu.",
    "details": {
      "scope": "documents:write"
    }
  }
}
404
Záznam neexistuje alebo patrí inej spoločnosti.

Object: Error

json
{
  "error": {
    "code": "finance.document_not_found",
    "message": "Doklad sa nenašiel.",
    "details": []
  }
}
429
Priveľa požiadaviek (finance.api_rate_limited).

Object: Error

FieldTypeRequiredDescription
errorobjectyes
error.codestringyes
Stabilný kód chyby.
error.messagestringyes
Text pre človeka, môže sa zmeniť.
error.detailsobjectyes
Podrobnosti, napr. fields, scope, existingId.

PDF dokladu

GET/documents/{documentId}/pdf

Permission: documents:read

PDF so vzhľadom dokladu spoločnosti. S download=1 ako príloha na stiahnutie.

Parameters

NameInTypeRequiredDescription
documentIdpathstring (uuid)yes
downloadquerystringno
1 = hlavička na stiahnutie súboru.

Values: 1

Example request

bash
curl -s "https://api.renly.sk/api/v1/finance/external/documents/${DOCUMENT_ID}/pdf" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY" \
  -o get-document-pdf.pdf

Responses

200
PDF.

application/pdf string (binary)

401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_unauthorized",
    "message": "API kľúč chýba, je neplatný alebo bol zrušený.",
    "details": []
  }
}
403
Kľúču chýba oprávnenie (finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_scope_missing",
    "message": "API kľúč nemá oprávnenie na túto operáciu.",
    "details": {
      "scope": "documents:write"
    }
  }
}
404
Záznam neexistuje alebo patrí inej spoločnosti.

Object: Error

json
{
  "error": {
    "code": "finance.document_not_found",
    "message": "Doklad sa nenašiel.",
    "details": []
  }
}
429
Priveľa požiadaviek (finance.api_rate_limited).

Object: Error

FieldTypeRequiredDescription
errorobjectyes
error.codestringyes
Stabilný kód chyby.
error.messagestringyes
Text pre človeka, môže sa zmeniť.
error.detailsobjectyes
Podrobnosti, napr. fields, scope, existingId.

Vyúčtovať zálohovú faktúru

POST/documents/{documentId}/final-invoice

Permission: documents:write

Vystaví faktúru, ktorá vyúčtuje uhradenú zálohovú faktúru (odpočíta zálohu).

Parameters

NameInTypeRequiredDescription
documentIdpathstring (uuid)yes
Idempotency-Keyheaderstringyes
Jedinečný kľúč zápisu v spoločnosti, 1–255 viditeľných znakov ASCII. Pozri Idempotencia.

Request body

json
{
  "send": true
}
FieldTypeRequiredDescription
sendSendOptionno
true = e-mail s predvoleným textom, objekt = vlastní príjemcovia či text, false alebo nič = neposlať.

Example request

bash
curl -s -X POST "https://api.renly.sk/api/v1/finance/external/documents/${DOCUMENT_ID}/final-invoice" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY" \
  -H "Idempotency-Key: mojeshop:2027000123:invoice" \
  -H "Content-Type: application/json" \
  -d '{
  "send": true
}'

Responses

201
Vystavený doklad.
json
{
  "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": []
}
FieldTypeRequiredDescription
dataDocumentyes
metaWriteMetano
400
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.

Object: Error

json
{
  "error": {
    "code": "finance.document_incomplete",
    "message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
    "details": {
      "field": "buyer.city",
      "fields": {
        "buyer.city": "required"
      }
    }
  }
}
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_unauthorized",
    "message": "API kľúč chýba, je neplatný alebo bol zrušený.",
    "details": []
  }
}
403
Kľúču chýba oprávnenie (finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_scope_missing",
    "message": "API kľúč nemá oprávnenie na túto operáciu.",
    "details": {
      "scope": "documents:write"
    }
  }
}
404
Záznam neexistuje alebo patrí inej spoločnosti.

Object: Error

json
{
  "error": {
    "code": "finance.document_not_found",
    "message": "Doklad sa nenašiel.",
    "details": []
  }
}
409
Akciu nemožno urobiť v aktuálnom stave — pozri tabuľku v kapitole Chyby.

Object: Error

json
{
  "error": {
    "code": "finance.idempotency_key_reused",
    "message": "Tento Idempotency-Key už bol použitý pre inú požiadavku.",
    "details": []
  }
}
429
Priveľa požiadaviek (finance.api_rate_limited).

Object: Error

FieldTypeRequiredDescription
errorobjectyes
error.codestringyes
Stabilný kód chyby.
error.messagestringyes
Text pre človeka, môže sa zmeniť.
error.detailsobjectyes
Podrobnosti, napr. fields, scope, existingId.

Dobropis faktúry (celej alebo čiastočný)

POST/documents/{documentId}/credit-note

Permission: documents:write

Vystaví dobropis k faktúre: bez lines a amount celej faktúry, s lines vybraných položiek a vráteného množstva, s amount sumy s DPH rozdelenej po sadzbách. Najviac jedno z lines a amount. Súčet dobropisov nesmie prekročiť faktúru spolu, v sadzbe DPH ani v množstve položky (409).

Parameters

NameInTypeRequiredDescription
documentIdpathstring (uuid)yes
Idempotency-Keyheaderstringyes
Jedinečný kľúč zápisu v spoločnosti, 1–255 viditeľných znakov ASCII. Pozri Idempotencia.

Request body

json
{
  "reason": "Reklamácia 2027000123-R1",
  "amount": "10.00",
  "description": "Zľava – reklamácia",
  "send": true
}
FieldTypeRequiredDescription
reasonstringyes
Dôvod opravy, je na PDF dobropisu.
linesobject[]no
Vybrané položky faktúry a vrátené množstvo (kladné, najviac zostatok položky).
lines[].lineIdstring (uuid)yes
lines[].id faktúry.
lines[].quantityDecimalyes
amountMoneyno
Suma dobropisu s DPH namiesto položiek.
descriptionstringno
Názov položky pri amount; predvolene „Zľava k faktúre …“.
sendSendOptionno
true = e-mail s predvoleným textom, objekt = vlastní príjemcovia či text, false alebo nič = neposlať.

Example request

bash
curl -s -X POST "https://api.renly.sk/api/v1/finance/external/documents/${DOCUMENT_ID}/credit-note" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY" \
  -H "Idempotency-Key: mojeshop:2027000123:invoice" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Reklamácia 2027000123-R1",
  "amount": "10.00",
  "description": "Zľava – reklamácia",
  "send": true
}'

Responses

201
Vystavený doklad.
json
{
  "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": []
}
FieldTypeRequiredDescription
dataDocumentyes
metaWriteMetano
400
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.

Object: Error

json
{
  "error": {
    "code": "finance.document_incomplete",
    "message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
    "details": {
      "field": "buyer.city",
      "fields": {
        "buyer.city": "required"
      }
    }
  }
}
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_unauthorized",
    "message": "API kľúč chýba, je neplatný alebo bol zrušený.",
    "details": []
  }
}
403
Kľúču chýba oprávnenie (finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_scope_missing",
    "message": "API kľúč nemá oprávnenie na túto operáciu.",
    "details": {
      "scope": "documents:write"
    }
  }
}
404
Záznam neexistuje alebo patrí inej spoločnosti.

Object: Error

json
{
  "error": {
    "code": "finance.document_not_found",
    "message": "Doklad sa nenašiel.",
    "details": []
  }
}
409
Akciu nemožno urobiť v aktuálnom stave — pozri tabuľku v kapitole Chyby.

Object: Error

json
{
  "error": {
    "code": "finance.idempotency_key_reused",
    "message": "Tento Idempotency-Key už bol použitý pre inú požiadavku.",
    "details": []
  }
}
429
Priveľa požiadaviek (finance.api_rate_limited).

Object: Error

FieldTypeRequiredDescription
errorobjectyes
error.codestringyes
Stabilný kód chyby.
error.messagestringyes
Text pre človeka, môže sa zmeniť.
error.detailsobjectyes
Podrobnosti, napr. fields, scope, existingId.

Stornovať zálohovú faktúru

POST/documents/{documentId}/cancel

Permission: documents:write

Stornuje zálohovú faktúru bez úhrad. Faktúra sa nestornuje — opravuje sa dobropisom.

Parameters

NameInTypeRequiredDescription
documentIdpathstring (uuid)yes
Idempotency-Keyheaderstringyes
Jedinečný kľúč zápisu v spoločnosti, 1–255 viditeľných znakov ASCII. Pozri Idempotencia.

Request body

json
{
  "reason": "Objednávka zrušená zákazníkom"
}
FieldTypeRequiredDescription
reasonstringyes

Example request

bash
curl -s -X POST "https://api.renly.sk/api/v1/finance/external/documents/${DOCUMENT_ID}/cancel" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY" \
  -H "Idempotency-Key: mojeshop:2027000123:invoice" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Objednávka zrušená zákazníkom"
}'

Responses

200
Doklad.
FieldTypeRequiredDescription
dataDocumentyes
metaWriteMetano
400
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.

Object: Error

json
{
  "error": {
    "code": "finance.document_incomplete",
    "message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
    "details": {
      "field": "buyer.city",
      "fields": {
        "buyer.city": "required"
      }
    }
  }
}
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_unauthorized",
    "message": "API kľúč chýba, je neplatný alebo bol zrušený.",
    "details": []
  }
}
403
Kľúču chýba oprávnenie (finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_scope_missing",
    "message": "API kľúč nemá oprávnenie na túto operáciu.",
    "details": {
      "scope": "documents:write"
    }
  }
}
404
Záznam neexistuje alebo patrí inej spoločnosti.

Object: Error

json
{
  "error": {
    "code": "finance.document_not_found",
    "message": "Doklad sa nenašiel.",
    "details": []
  }
}
409
Akciu nemožno urobiť v aktuálnom stave — pozri tabuľku v kapitole Chyby.

Object: Error

json
{
  "error": {
    "code": "finance.idempotency_key_reused",
    "message": "Tento Idempotency-Key už bol použitý pre inú požiadavku.",
    "details": []
  }
}
429
Priveľa požiadaviek (finance.api_rate_limited).

Object: Error

FieldTypeRequiredDescription
errorobjectyes
error.codestringyes
Stabilný kód chyby.
error.messagestringyes
Text pre človeka, môže sa zmeniť.
error.detailsobjectyes
Podrobnosti, napr. fields, scope, existingId.

Úhrady a odoslanie

Zápis úhrady a odoslanie dokladu e-mailom.

Zapísať úhradu

POST/documents/{documentId}/payments

Permission: payments:write

Zapíše úhradu faktúry alebo zálohovej faktúry. Bez amount uhradí celý zostatok. Úplná úhrada pošle zákazníkovi poďakovanie, ak ho má spoločnosť zapnuté, a webhook document.paid.

Parameters

NameInTypeRequiredDescription
documentIdpathstring (uuid)yes
Idempotency-Keyheaderstringyes
Jedinečný kľúč zápisu v spoločnosti, 1–255 viditeľných znakov ASCII. Pozri Idempotencia.

Request body

Object: PaymentInput

json
{
  "paidOn": "2027-01-06",
  "method": "bank_transfer"
}

Example request

bash
curl -s -X POST "https://api.renly.sk/api/v1/finance/external/documents/${DOCUMENT_ID}/payments" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY" \
  -H "Idempotency-Key: mojeshop:2027000123:invoice" \
  -H "Content-Type: application/json" \
  -d '{
  "paidOn": "2027-01-06",
  "method": "bank_transfer"
}'

Responses

200
Doklad.
FieldTypeRequiredDescription
dataDocumentyes
metaWriteMetano
400
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.

Object: Error

json
{
  "error": {
    "code": "finance.document_incomplete",
    "message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
    "details": {
      "field": "buyer.city",
      "fields": {
        "buyer.city": "required"
      }
    }
  }
}
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_unauthorized",
    "message": "API kľúč chýba, je neplatný alebo bol zrušený.",
    "details": []
  }
}
403
Kľúču chýba oprávnenie (finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_scope_missing",
    "message": "API kľúč nemá oprávnenie na túto operáciu.",
    "details": {
      "scope": "documents:write"
    }
  }
}
404
Záznam neexistuje alebo patrí inej spoločnosti.

Object: Error

json
{
  "error": {
    "code": "finance.document_not_found",
    "message": "Doklad sa nenašiel.",
    "details": []
  }
}
409
Akciu nemožno urobiť v aktuálnom stave — pozri tabuľku v kapitole Chyby.

Object: Error

json
{
  "error": {
    "code": "finance.idempotency_key_reused",
    "message": "Tento Idempotency-Key už bol použitý pre inú požiadavku.",
    "details": []
  }
}
429
Priveľa požiadaviek (finance.api_rate_limited).

Object: Error

FieldTypeRequiredDescription
errorobjectyes
error.codestringyes
Stabilný kód chyby.
error.messagestringyes
Text pre človeka, môže sa zmeniť.
error.detailsobjectyes
Podrobnosti, napr. fields, scope, existingId.

Poslať doklad e-mailom

POST/documents/{documentId}/send

Permission: documents:write

Pošle vystavený doklad s PDF e-mailom. Bez tela ({}) ide na predvolených príjemcov s predvoleným predmetom a textom v jazyku dokladu. Každé odoslanie potrebuje nový Idempotency-Key.

Parameters

NameInTypeRequiredDescription
documentIdpathstring (uuid)yes
Idempotency-Keyheaderstringyes
Jedinečný kľúč zápisu v spoločnosti, 1–255 viditeľných znakov ASCII. Pozri Idempotencia.

Request body

Object: SendInput

json
{
  "to": [
    "uctaren@firma.sk"
  ],
  "subject": "Faktúra 2027001",
  "message": "Dobrý deň, v prílohe posielame faktúru."
}

Example request

bash
curl -s -X POST "https://api.renly.sk/api/v1/finance/external/documents/${DOCUMENT_ID}/send" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY" \
  -H "Idempotency-Key: mojeshop:2027000123:invoice" \
  -H "Content-Type: application/json" \
  -d '{
  "to": [
    "uctaren@firma.sk"
  ],
  "subject": "Faktúra 2027001",
  "message": "Dobrý deň, v prílohe posielame faktúru."
}'

Responses

200
Doklad.
FieldTypeRequiredDescription
dataDocumentyes
metaWriteMetano
400
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.

Object: Error

json
{
  "error": {
    "code": "finance.document_incomplete",
    "message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
    "details": {
      "field": "buyer.city",
      "fields": {
        "buyer.city": "required"
      }
    }
  }
}
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_unauthorized",
    "message": "API kľúč chýba, je neplatný alebo bol zrušený.",
    "details": []
  }
}
403
Kľúču chýba oprávnenie (finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_scope_missing",
    "message": "API kľúč nemá oprávnenie na túto operáciu.",
    "details": {
      "scope": "documents:write"
    }
  }
}
404
Záznam neexistuje alebo patrí inej spoločnosti.

Object: Error

json
{
  "error": {
    "code": "finance.document_not_found",
    "message": "Doklad sa nenašiel.",
    "details": []
  }
}
409
Akciu nemožno urobiť v aktuálnom stave — pozri tabuľku v kapitole Chyby.

Object: Error

json
{
  "error": {
    "code": "finance.idempotency_key_reused",
    "message": "Tento Idempotency-Key už bol použitý pre inú požiadavku.",
    "details": []
  }
}
429
Priveľa požiadaviek (finance.api_rate_limited).

Object: Error

FieldTypeRequiredDescription
errorobjectyes
error.codestringyes
Stabilný kód chyby.
error.messagestringyes
Text pre človeka, môže sa zmeniť.
error.detailsobjectyes
Podrobnosti, napr. fields, scope, existingId.

Partneri

Adresár odberateľov a dodávateľov.

Zoznam partnerov

GET/partners

Permission: partners:read

Partneri z adresára spoločnosti podľa názvu (abecedne), bez archivovaných.

Parameters

NameInTypeRequiredDescription
qquerystringno
Hľadanie v názve, IČO a kontaktných osobách.
rolequerystringno
Iba odberatelia alebo iba dodávatelia.

Values: customer, supplier

cursorquerystringno
meta.nextCursor predchádzajúcej stránky.
limitqueryintegerno
Počet záznamov na stránku.

Default: 50

Example request

bash
curl -s "https://api.renly.sk/api/v1/finance/external/partners" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY"

Responses

200
Partneri.
FieldTypeRequiredDescription
dataPartner[]yes
metaListMetayes
400
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.

Object: Error

json
{
  "error": {
    "code": "finance.document_incomplete",
    "message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
    "details": {
      "field": "buyer.city",
      "fields": {
        "buyer.city": "required"
      }
    }
  }
}
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_unauthorized",
    "message": "API kľúč chýba, je neplatný alebo bol zrušený.",
    "details": []
  }
}
403
Kľúču chýba oprávnenie (finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_scope_missing",
    "message": "API kľúč nemá oprávnenie na túto operáciu.",
    "details": {
      "scope": "documents:write"
    }
  }
}
429
Priveľa požiadaviek (finance.api_rate_limited).

Object: Error

FieldTypeRequiredDescription
errorobjectyes
error.codestringyes
Stabilný kód chyby.
error.messagestringyes
Text pre človeka, môže sa zmeniť.
error.detailsobjectyes
Podrobnosti, napr. fields, scope, existingId.

Založiť partnera

POST/partners

Permission: partners:write

Založí partnera v adresári. IČO je v spoločnosti jedinečné — partner s existujúcim IČO je 409 finance.partner_duplicate s details.existingId. IČ DPH sa overí v systéme VIES (vatVerifiedAt).

Parameters

NameInTypeRequiredDescription
Idempotency-Keyheaderstringyes
Jedinečný kľúč zápisu v spoločnosti, 1–255 viditeľných znakov ASCII. Pozri Idempotencia.

Request body

Object: PartnerInput

json
{
  "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
    }
  ]
}

Example request

bash
curl -s -X POST "https://api.renly.sk/api/v1/finance/external/partners" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY" \
  -H "Idempotency-Key: mojeshop:2027000123:invoice" \
  -H "Content-Type: application/json" \
  -d '{
  "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
Založený partner.
json
{
  "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": []
}
FieldTypeRequiredDescription
dataPartneryes
400
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.

Object: Error

json
{
  "error": {
    "code": "finance.document_incomplete",
    "message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
    "details": {
      "field": "buyer.city",
      "fields": {
        "buyer.city": "required"
      }
    }
  }
}
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_unauthorized",
    "message": "API kľúč chýba, je neplatný alebo bol zrušený.",
    "details": []
  }
}
403
Kľúču chýba oprávnenie (finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_scope_missing",
    "message": "API kľúč nemá oprávnenie na túto operáciu.",
    "details": {
      "scope": "documents:write"
    }
  }
}
409
Akciu nemožno urobiť v aktuálnom stave — pozri tabuľku v kapitole Chyby.

Object: Error

json
{
  "error": {
    "code": "finance.idempotency_key_reused",
    "message": "Tento Idempotency-Key už bol použitý pre inú požiadavku.",
    "details": []
  }
}
429
Priveľa požiadaviek (finance.api_rate_limited).

Object: Error

FieldTypeRequiredDescription
errorobjectyes
error.codestringyes
Stabilný kód chyby.
error.messagestringyes
Text pre človeka, môže sa zmeniť.
error.detailsobjectyes
Podrobnosti, napr. fields, scope, existingId.

Detail partnera

GET/partners/{partnerId}

Permission: partners:read

Parameters

NameInTypeRequiredDescription
partnerIdpathstring (uuid)yes

Example request

bash
curl -s "https://api.renly.sk/api/v1/finance/external/partners/${PARTNER_ID}" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY"

Responses

200
Partner.
FieldTypeRequiredDescription
dataPartneryes
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_unauthorized",
    "message": "API kľúč chýba, je neplatný alebo bol zrušený.",
    "details": []
  }
}
403
Kľúču chýba oprávnenie (finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_scope_missing",
    "message": "API kľúč nemá oprávnenie na túto operáciu.",
    "details": {
      "scope": "documents:write"
    }
  }
}
404
Záznam neexistuje alebo patrí inej spoločnosti.

Object: Error

json
{
  "error": {
    "code": "finance.document_not_found",
    "message": "Doklad sa nenašiel.",
    "details": []
  }
}
429
Priveľa požiadaviek (finance.api_rate_limited).

Object: Error

FieldTypeRequiredDescription
errorobjectyes
error.codestringyes
Stabilný kód chyby.
error.messagestringyes
Text pre človeka, môže sa zmeniť.
error.detailsobjectyes
Podrobnosti, napr. fields, scope, existingId.

Upraviť partnera

PATCH/partners/{partnerId}

Permission: partners:write

Zmení iba poslané polia. contacts nahradí celý zoznam kontaktných osôb — existujúcu osobu ponecháte poslaním jej id. Vystavené doklady sa nemenia.

Parameters

NameInTypeRequiredDescription
partnerIdpathstring (uuid)yes

Request body

Object: PartnerInput

json
{
  "street": "Nová 5",
  "city": "Poprad",
  "postalCode": "05801"
}

Example request

bash
curl -s -X PATCH "https://api.renly.sk/api/v1/finance/external/partners/${PARTNER_ID}" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "street": "Nová 5",
  "city": "Poprad",
  "postalCode": "05801"
}'

Responses

200
Partner.
FieldTypeRequiredDescription
dataPartneryes
400
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.

Object: Error

json
{
  "error": {
    "code": "finance.document_incomplete",
    "message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
    "details": {
      "field": "buyer.city",
      "fields": {
        "buyer.city": "required"
      }
    }
  }
}
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_unauthorized",
    "message": "API kľúč chýba, je neplatný alebo bol zrušený.",
    "details": []
  }
}
403
Kľúču chýba oprávnenie (finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_scope_missing",
    "message": "API kľúč nemá oprávnenie na túto operáciu.",
    "details": {
      "scope": "documents:write"
    }
  }
}
404
Záznam neexistuje alebo patrí inej spoločnosti.

Object: Error

json
{
  "error": {
    "code": "finance.document_not_found",
    "message": "Doklad sa nenašiel.",
    "details": []
  }
}
409
Akciu nemožno urobiť v aktuálnom stave — pozri tabuľku v kapitole Chyby.

Object: Error

json
{
  "error": {
    "code": "finance.idempotency_key_reused",
    "message": "Tento Idempotency-Key už bol použitý pre inú požiadavku.",
    "details": []
  }
}
429
Priveľa požiadaviek (finance.api_rate_limited).

Object: Error

FieldTypeRequiredDescription
errorobjectyes
error.codestringyes
Stabilný kód chyby.
error.messagestringyes
Text pre človeka, môže sa zmeniť.
error.detailsobjectyes
Podrobnosti, napr. fields, scope, existingId.

Cenník a nastavenia

Položky cenníka, číselné rady a bankové účty pre vystavenie dokladu.

Cenník položiek

GET/price-list-items

Permission: catalog:read

Položky cenníka spoločnosti podľa názvu (abecedne), bez archivovaných.

Parameters

NameInTypeRequiredDescription
qquerystringno
Hľadanie v názve a kóde položky.
cursorquerystringno
meta.nextCursor predchádzajúcej stránky.
limitqueryintegerno
Počet záznamov na stránku.

Default: 50

Example request

bash
curl -s "https://api.renly.sk/api/v1/finance/external/price-list-items" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY"

Responses

200
Položky cenníka.
json
{
  "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
  }
}
FieldTypeRequiredDescription
dataPriceListItem[]yes
metaListMetayes
400
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.

Object: Error

json
{
  "error": {
    "code": "finance.document_incomplete",
    "message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
    "details": {
      "field": "buyer.city",
      "fields": {
        "buyer.city": "required"
      }
    }
  }
}
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_unauthorized",
    "message": "API kľúč chýba, je neplatný alebo bol zrušený.",
    "details": []
  }
}
403
Kľúču chýba oprávnenie (finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_scope_missing",
    "message": "API kľúč nemá oprávnenie na túto operáciu.",
    "details": {
      "scope": "documents:write"
    }
  }
}
429
Priveľa požiadaviek (finance.api_rate_limited).

Object: Error

FieldTypeRequiredDescription
errorobjectyes
error.codestringyes
Stabilný kód chyby.
error.messagestringyes
Text pre človeka, môže sa zmeniť.
error.detailsobjectyes
Podrobnosti, napr. fields, scope, existingId.

Položka cenníka

GET/price-list-items/{itemId}

Permission: catalog:read

Parameters

NameInTypeRequiredDescription
itemIdpathstring (uuid)yes

Example request

bash
curl -s "https://api.renly.sk/api/v1/finance/external/price-list-items/${ITEM_ID}" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY"

Responses

200
Položka.
FieldTypeRequiredDescription
dataPriceListItemyes
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_unauthorized",
    "message": "API kľúč chýba, je neplatný alebo bol zrušený.",
    "details": []
  }
}
403
Kľúču chýba oprávnenie (finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_scope_missing",
    "message": "API kľúč nemá oprávnenie na túto operáciu.",
    "details": {
      "scope": "documents:write"
    }
  }
}
404
Záznam neexistuje alebo patrí inej spoločnosti.

Object: Error

json
{
  "error": {
    "code": "finance.document_not_found",
    "message": "Doklad sa nenašiel.",
    "details": []
  }
}
429
Priveľa požiadaviek (finance.api_rate_limited).

Object: Error

FieldTypeRequiredDescription
errorobjectyes
error.codestringyes
Stabilný kód chyby.
error.messagestringyes
Text pre človeka, môže sa zmeniť.
error.detailsobjectyes
Podrobnosti, napr. fields, scope, existingId.

Číselné rady

GET/number-series

Permission: documents:read

Rady účtovných dokladov. id radu pošlite ako seriesId pri vystavení, ak nechcete predvolený rad.

Example request

bash
curl -s "https://api.renly.sk/api/v1/finance/external/number-series" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY"

Responses

200
Rady.
json
{
  "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": []
}
FieldTypeRequiredDescription
dataNumberSeries[]yes
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_unauthorized",
    "message": "API kľúč chýba, je neplatný alebo bol zrušený.",
    "details": []
  }
}
403
Kľúču chýba oprávnenie (finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_scope_missing",
    "message": "API kľúč nemá oprávnenie na túto operáciu.",
    "details": {
      "scope": "documents:write"
    }
  }
}
429
Priveľa požiadaviek (finance.api_rate_limited).

Object: Error

FieldTypeRequiredDescription
errorobjectyes
error.codestringyes
Stabilný kód chyby.
error.messagestringyes
Text pre človeka, môže sa zmeniť.
error.detailsobjectyes
Podrobnosti, napr. fields, scope, existingId.

Bankové účty

GET/bank-accounts

Permission: documents:read

Účty spoločnosti pre platbu prevodom. id účtu pošlite ako bankAccountId, ak nechcete predvolený.

Example request

bash
curl -s "https://api.renly.sk/api/v1/finance/external/bank-accounts" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY"

Responses

200
Účty.
json
{
  "data": [
    {
      "id": "019a5f6e-6666-7a2b-8c3d-4e5f6a7b8c9d",
      "bankName": "Slovenská sporiteľňa",
      "iban": "SK3109000000000123456789",
      "bic": "GIBASKBX",
      "currency": "EUR",
      "isDefault": true
    }
  ],
  "meta": []
}
FieldTypeRequiredDescription
dataBankAccount[]yes
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_unauthorized",
    "message": "API kľúč chýba, je neplatný alebo bol zrušený.",
    "details": []
  }
}
403
Kľúču chýba oprávnenie (finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_scope_missing",
    "message": "API kľúč nemá oprávnenie na túto operáciu.",
    "details": {
      "scope": "documents:write"
    }
  }
}
429
Priveľa požiadaviek (finance.api_rate_limited).

Object: Error

FieldTypeRequiredDescription
errorobjectyes
error.codestringyes
Stabilný kód chyby.
error.messagestringyes
Text pre človeka, môže sa zmeniť.
error.detailsobjectyes
Podrobnosti, napr. fields, scope, existingId.

Webhooky

Správy o zmenách dokladov, ktoré sa stali vo Financiách.

Zoznam webhookov

GET/webhooks

Permission: webhooks:write

Example request

bash
curl -s "https://api.renly.sk/api/v1/finance/external/webhooks" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY"

Responses

200
Aktívne adresy (bez tajomstva).
FieldTypeRequiredDescription
dataWebhook[]yes
metaobjectyes
meta.limitintegerno
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_unauthorized",
    "message": "API kľúč chýba, je neplatný alebo bol zrušený.",
    "details": []
  }
}
403
Kľúču chýba oprávnenie (finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_scope_missing",
    "message": "API kľúč nemá oprávnenie na túto operáciu.",
    "details": {
      "scope": "documents:write"
    }
  }
}
429
Priveľa požiadaviek (finance.api_rate_limited).

Object: Error

FieldTypeRequiredDescription
errorobjectyes
error.codestringyes
Stabilný kód chyby.
error.messagestringyes
Text pre človeka, môže sa zmeniť.
error.detailsobjectyes
Podrobnosti, napr. fields, scope, existingId.

Zaregistrovať webhook

POST/webhooks

Permission: webhooks:write

Zaregistruje HTTPS adresu a udalosti. Odpoveď obsahuje secret na overenie podpisu — iba raz, uložte ho. Najviac 5 adries, tá istá adresa dvakrát je 409 finance.webhook_duplicate.

Request body

json
{
  "url": "https://mojeshop.sk/renly-webhook",
  "events": [
    "document.paid",
    "document.issued"
  ]
}
FieldTypeRequiredDescription
urlstring (uri)yes
HTTPS adresa bez mena a hesla.
eventsWebhookEvent[]yes

Example request

bash
curl -s -X POST "https://api.renly.sk/api/v1/finance/external/webhooks" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://mojeshop.sk/renly-webhook",
  "events": [
    "document.paid",
    "document.issued"
  ]
}'

Responses

201
Webhook so secret.
FieldTypeRequiredDescription
dataWebhook & objectyes
data.secretstringyes
Tajomstvo podpisu rfw_…, iba v tejto odpovedi.
400
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.

Object: Error

json
{
  "error": {
    "code": "finance.document_incomplete",
    "message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
    "details": {
      "field": "buyer.city",
      "fields": {
        "buyer.city": "required"
      }
    }
  }
}
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_unauthorized",
    "message": "API kľúč chýba, je neplatný alebo bol zrušený.",
    "details": []
  }
}
403
Kľúču chýba oprávnenie (finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_scope_missing",
    "message": "API kľúč nemá oprávnenie na túto operáciu.",
    "details": {
      "scope": "documents:write"
    }
  }
}
409
Akciu nemožno urobiť v aktuálnom stave — pozri tabuľku v kapitole Chyby.

Object: Error

json
{
  "error": {
    "code": "finance.idempotency_key_reused",
    "message": "Tento Idempotency-Key už bol použitý pre inú požiadavku.",
    "details": []
  }
}
429
Priveľa požiadaviek (finance.api_rate_limited).

Object: Error

FieldTypeRequiredDescription
errorobjectyes
error.codestringyes
Stabilný kód chyby.
error.messagestringyes
Text pre človeka, môže sa zmeniť.
error.detailsobjectyes
Podrobnosti, napr. fields, scope, existingId.

Zmazať webhook

DELETE/webhooks/{webhookId}

Permission: webhooks:write

Adresa sa vypne a čakajúce doručenia sa už nepošlú.

Parameters

NameInTypeRequiredDescription
webhookIdpathstring (uuid)yes

Example request

bash
curl -s -X DELETE "https://api.renly.sk/api/v1/finance/external/webhooks/${WEBHOOK_ID}" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY"

Responses

204
Zmazané.
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_unauthorized",
    "message": "API kľúč chýba, je neplatný alebo bol zrušený.",
    "details": []
  }
}
403
Kľúču chýba oprávnenie (finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_scope_missing",
    "message": "API kľúč nemá oprávnenie na túto operáciu.",
    "details": {
      "scope": "documents:write"
    }
  }
}
404
Záznam neexistuje alebo patrí inej spoločnosti.

Object: Error

json
{
  "error": {
    "code": "finance.document_not_found",
    "message": "Doklad sa nenašiel.",
    "details": []
  }
}
429
Priveľa požiadaviek (finance.api_rate_limited).

Object: Error

FieldTypeRequiredDescription
errorobjectyes
error.codestringyes
Stabilný kód chyby.
error.messagestringyes
Text pre človeka, môže sa zmeniť.
error.detailsobjectyes
Podrobnosti, napr. fields, scope, existingId.

História doručení

GET/webhooks/{webhookId}/deliveries

Permission: webhooks:write

Posledných 50 doručení od najnovšieho — na hľadanie, prečo webhook neprišiel.

Parameters

NameInTypeRequiredDescription
webhookIdpathstring (uuid)yes

Example request

bash
curl -s "https://api.renly.sk/api/v1/finance/external/webhooks/${WEBHOOK_ID}/deliveries" \
  -H "Authorization: Bearer $RENLY_FINANCE_KEY"

Responses

200
Doručenia.
FieldTypeRequiredDescription
dataWebhookDelivery[]yes
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_unauthorized",
    "message": "API kľúč chýba, je neplatný alebo bol zrušený.",
    "details": []
  }
}
403
Kľúču chýba oprávnenie (finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).

Object: Error

json
{
  "error": {
    "code": "finance.api_key_scope_missing",
    "message": "API kľúč nemá oprávnenie na túto operáciu.",
    "details": {
      "scope": "documents:write"
    }
  }
}
404
Záznam neexistuje alebo patrí inej spoločnosti.

Object: Error

json
{
  "error": {
    "code": "finance.document_not_found",
    "message": "Doklad sa nenašiel.",
    "details": []
  }
}
429
Priveľa požiadaviek (finance.api_rate_limited).

Object: Error

FieldTypeRequiredDescription
errorobjectyes
error.codestringyes
Stabilný kód chyby.
error.messagestringyes
Text pre človeka, môže sa zmeniť.
error.detailsobjectyes
Podrobnosti, napr. fields, scope, existingId.

Verejné PDF

Odkaz na PDF dokladu bez prihlásenia, ktorý môžete dať zákazníkovi.

PDF dokladu bez prihlásenia

GET/public/finance/documents/{token}/pdf

no sign-inServer: https://api.renly.sk/api/v1

Adresa je v poli publicPdfUrl dokladu — nemusíte ju skladať. Platí, kým je doklad vystavený (storno zálohovej faktúry ju zruší). Limit 120 stiahnutí za 10 minút na odkaz a IP adresu.

Parameters

NameInTypeRequiredDescription
tokenpathstringyes
downloadquerystringno

Values: 1

Example request

bash
curl -s "https://api.renly.sk/api/v1/public/finance/documents/${TOKEN}/pdf" \
  -o get-public-document-pdf.pdf

Responses

200
PDF.

application/pdf string (binary)

404
Záznam neexistuje alebo patrí inej spoločnosti.

Object: Error

json
{
  "error": {
    "code": "finance.document_not_found",
    "message": "Doklad sa nenašiel.",
    "details": []
  }
}
429
Priveľa stiahnutí, počkajte podľa Retry-After.

Objects

Error

FieldTypeRequiredDescription
errorobjectyes
error.codestringyes
Stabilný kód chyby.
error.messagestringyes
Text pre človeka, môže sa zmeniť.
error.detailsobjectyes
Podrobnosti, napr. fields, scope, existingId.

ListMeta

FieldTypeRequiredDescription
limitintegeryes
nextCursorstring | nullyes
Kurzor ďalšej stránky, null = posledná stránka.

WriteMeta

FieldTypeRequiredDescription
sendErrorstringno
Kód chyby, keď doklad vznikol, ale e-mail sa nepodarilo odoslať (napr. finance.document_send_failed).

Me

FieldTypeRequiredDescription
keyobjectyes
key.idstring (uuid)yes
key.namestringyes
key.keyPrefixstringyes
Začiatok kľúča (rfk_ alebo rfk_test_ a 12 znakov) — podľa neho ho spoznáte vo Financiách.
key.modestringyes
test = testovací kľúč, doklady mimo radu, exportu, e-mailov a e-faktúr.

Values: live, test

key.scopesScope[]yes
key.createdByNamestringno
key.createdAtstring (date-time)no
key.lastUsedAtstring (date-time) | nullno
key.revokedAtstring (date-time) | nullno
key.activebooleanyes
companyobjectyes
company.idstring (uuid)yes
company.tenantIdstring (uuid)yes
ID firmy v Renly.
company.namestringyes
company.activebooleanyes
false = spoločnosť nad limitom balíčka, API iba číta.

Scope

Type: string

Values: documents:read, documents:write, payments:write, partners:read, partners:write, catalog:read, webhooks:write

DocumentType

invoice faktúra, proforma zálohová faktúra, credit_note dobropis, corrective_invoice ťarchopis (opravná faktúra na zvýšenie), payment_receipt daňový doklad k prijatej platbe. Vystaviť cez POST /documents sa dá faktúra, zálohová faktúra a dobropis k faktúre mimo Renly (s originalDocument).

Type: string

Values: invoice, proforma, credit_note, corrective_invoice, payment_receipt

PaymentMethod

Prevod, hotovosť, karta, dobierka, iné. Odpoveď môže obsahovať aj advance (zápočet zálohy pri vyúčtovaní).

Type: string

Values: bank_transfer, cash, card, cash_on_delivery, other

Money

Type: string

Pattern: ^-?\d+\.\d{2}$

Example: 46.70

Decimal

Type: string

Pattern: ^-?\d+(\.\d+)?$

Example: 19.90

Party

Odberateľ dokladu.

FieldTypeRequiredDescription
namestringno
icostringno
IČO (8 číslic).
dicstringno
DIČ.
icDphstringno
IČ DPH s kódom krajiny, napr. SK2020123456.
streetstringno
citystringno
postalCodestringno
countryCodestringno

Default: SK

emailstring (email)no
Adresa, na ktorú pôjde doklad pri send.

LineInput

FieldTypeRequiredDescription
descriptionstringyes
detailstringno
Doplňujúci text pod názvom položky.
quantityDecimalyes
unitstringno
unitPriceDecimalyes
discountPercentDecimalno
vatRateinteger | nullno
Sadzba DPH; neplatiteľ null. Sadzby iných štátov iba pri vatMode: oss.

Values: 23, 19, 5, 0, 27, 21, 20, 18, 13, 12, 10, 8, 7, null

CreateDocument

FieldTypeRequiredDescription
typestringyes
credit_note iba k faktúre mimo Renly — s originalDocument, correctionReason a zápornými množstvami.

Values: invoice, proforma, credit_note

originalDocumentobjectno
Dobropis k faktúre vystavenej mimo Renly (napr. v predošlom programe).
originalDocument.numberstringyes
Číslo pôvodnej faktúry.
originalDocument.issueDatestring (date)yes
Dátum vystavenia pôvodnej faktúry.
correctionReasonstringno
Dôvod opravy — povinný pri dobropise.
externalSourcestringno
Váš systém, napr. mojeshop. Vždy spolu s externalId.
externalIdstringno
ID objednávky vo vašom systéme. Nie je jedinečné — dobropis ho prevezme.
partnerIdstring (uuid)no
Partner z adresára; doplní odberateľa, splatnosť a jazyk.
buyerPartyno
Odberateľ dokladu.
linesLineInput[]yes
numberstringno
Vlastné číslo mimo radu. Bez neho číslo pridelí rad.
seriesIdstring (uuid)no
Rad z GET /number-series; predvolený rad druhu dokladu.
issueDatestring (date)no
deliveryDatestring (date)no
dueDatestring (date)no
orderNumberstringno
Číslo objednávky na PDF.
variableSymbolstringno
Predvolene číslice čísla dokladu.
constantSymbolstringno
specificSymbolstringno
paymentMethodPaymentMethodno
Prevod, hotovosť, karta, dobierka, iné. Odpoveď môže obsahovať aj advance (zápočet zálohy pri vyúčtovaní).
bankAccountIdstring (uuid)no
Účet z GET /bank-accounts; predvolený účet spoločnosti.
currencystringno

Values: EUR, CZK, USD, GBP, PLN, HUF, CHF, SEK, NOK, DKK, RON

Default: EUR

exchangeRateDecimalno
languagestringno

Values: sk, cs, en, de, hu, pl, hr, sl, ro, ru, uk, es, it, nl

Default: sk

vatModestringno

Values: standard, reverse_charge, exempt, non_payer, oss

vatCountrystringno
Štát spotreby pri oss (AT, CZ, DE, HU, PL); predvolene štát odberateľa.
vatExemptionReasonstringno
Povinný pri exempt.
vatExemptionCodestring | nullno
Kód dôvodu oslobodenia (VATEX) pri exempt pre e-faktúru, napr. VATEX-EU-135-1 pri nájme nehnuteľnosti (§ 38). Nepovinný.

Values: 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

pricesIncludeVatbooleanno

Default: false

discountPercentDecimalno
introTextstringno
Text nad položkami.
closingTextstringno
Text pod položkami.
internalNotestringno
Poznámka viditeľná iba vo Financiách.
paymentPaymentInputno
sendSendOptionno
true = e-mail s predvoleným textom, objekt = vlastní príjemcovia či text, false alebo nič = neposlať.

PaymentInput

FieldTypeRequiredDescription
amountMoneyno
Bez sumy celý zostatok.
paidOnstring (date)yes
methodPaymentMethodyes
Prevod, hotovosť, karta, dobierka, iné. Odpoveď môže obsahovať aj advance (zápočet zálohy pri vyúčtovaní).
notestringno

SendInput

FieldTypeRequiredDescription
toarray<string (email)>no
Príjemcovia; predvolene odberateľ alebo kontaktné osoby partnera.
ccarray<string (email)>no
subjectstringno
messagestringno

SendOption

true = e-mail s predvoleným textom, objekt = vlastní príjemcovia či text, false alebo nič = neposlať.

Type: boolean | SendInput

Document

FieldTypeRequiredDescription
idstring (uuid)yes
typeDocumentTypeyes
invoice faktúra, proforma zálohová faktúra, credit_note dobropis, corrective_invoice ťarchopis (opravná faktúra na zvýšenie), payment_receipt daňový doklad k prijatej platbe. Vystaviť cez POST /documents sa dá faktúra, zálohová faktúra a dobropis k faktúre mimo Renly (s originalDocument).
statusstringyes

Values: issued, cancelled

paymentStatusstring | nullyes
Stav úhrady faktúry, zálohovej faktúry a ťarchopisu; ostatné null.

Values: unpaid, partially_paid, paid, overdue, null

numberstringyes
variableSymbolstringno
orderNumberstringno
externalSourcestring | nullno
externalIdstring | nullno
testbooleanno
Testovací doklad z testovacieho kľúča — číslo TEST-…, nie je účtovným dokladom.
issueDatestring (date)yes
deliveryDatestring (date) | nullno
dueDatestring (date) | nullno
currencystringyes
languagestringno
paymentMethodstringno
vatModestringno
vatCountrystring | nullno
Štát spotreby pri oss.
pricesIncludeVatbooleanno
buyerobjectyes
buyer.namestringyes
buyer.icostringyes
buyer.dicstringyes
buyer.icDphstringyes
buyer.streetstringyes
buyer.citystringyes
buyer.postalCodestringyes
buyer.countryCodestringyes
buyer.emailstringyes
linesobject[]yes
lines[].idstring (uuid)no
ID položky — lineId čiastočného dobropisu.
lines[].kindstringyes
advance = odpočet zálohy pri vyúčtovaní.

Values: item, advance

lines[].descriptionstringyes
lines[].detailstringno
lines[].quantitystringyes
lines[].unitstringno
lines[].unitPricestringyes
lines[].discountPercentstringno
lines[].vatRateinteger | nullyes
lines[].totalWithoutVatMoneyyes
lines[].vatMoneyyes
lines[].totalWithVatMoneyyes
vatRecapobject[]no
Rekapitulácia DPH po sadzbách (záväzná pre DPH); bez DPH prázdna.
vatRecap[].rateintegeryes
vatRecap[].baseMoneyyes
vatRecap[].vatMoneyyes
vatRecap[].totalMoneyyes
totalWithoutVatMoneyno
totalVatMoneyno
totalWithVatMoneyyes
paidAmountMoneyno
remainingAmountMoneyyes
Zostáva uhradiť: suma − úhrady − dobropisy.
creditedAmountMoneyno
Faktúra: súčet vystavených dobropisov s DPH (kladný).
paymentsobject[]yes
payments[].idstring (uuid)yes
payments[].amountMoneyyes
payments[].paidOnstring (date)yes
payments[].methodstringyes
relatedDocumentnull | objectno
Dobropis → faktúra, vyúčtovanie → zálohová faktúra.
relatedDocument.idstring (uuid)yes
relatedDocument.typeDocumentTypeyes
invoice faktúra, proforma zálohová faktúra, credit_note dobropis, corrective_invoice ťarchopis (opravná faktúra na zvýšenie), payment_receipt daňový doklad k prijatej platbe. Vystaviť cez POST /documents sa dá faktúra, zálohová faktúra a dobropis k faktúre mimo Renly (s originalDocument).
relatedDocument.numberstring | nullyes
originalDocumentnull | objectno
Dobropis k faktúre mimo Renly: číslo a dátum pôvodnej faktúry; inak null.
originalDocument.numberstringyes
originalDocument.issueDatestring (date) | nullyes
publicPdfUrlstring (uri) | nullyes
PDF bez prihlásenia; null pri doklade vystavenom v appke alebo po storne.
sentAtstring (date-time) | nullno
issuedAtstring (date-time) | nullno
cancelledAtstring (date-time) | nullno
createdAtstring (date-time)no
updatedAtstring (date-time)no

PartnerContactInput

FieldTypeRequiredDescription
idstring (uuid)no
Existujúca osoba; bez id vznikne nová.
namestringno
jobTitlestringno
emailstring (email)no
phonestringno
notestringno
rolesstring[]no
invoices dostáva doklady, deals ponuky a objednávky, reminders upomienky, copy kópiu.
isPrimarybooleanno

PartnerInput

FieldTypeRequiredDescription
namestringno
Povinné pri založení.
icostringno
dicstringno
icDphstringno
registryEntrystringno
Zápis v obchodnom registri.
streetstringno
citystringno
postalCodestringno
countryCodestringno

Default: SK

emailstring (email)no
phonestringno
isCustomerbooleanno

Default: true

isSupplierbooleanno

Default: false

defaultDueDaysinteger | nullno
Splatnosť dokladov partnera v dňoch.
documentLanguagestring | nullno

Values: sk, cs, en, de, hu, pl, hr, sl, ro, ru, uk, es, it, nl, null

notestringno
contactsPartnerContactInput[]no

Partner

FieldTypeRequiredDescription
idstring (uuid)yes
testbooleanyes
Testovací partner založený testovacím kľúčom.
namestringyes
icostringyes
dicstringyes
icDphstringyes
registryEntrystringno
streetstringyes
citystringyes
postalCodestringyes
countryCodestringyes
emailstringyes
E-mail hlavnej kontaktnej osoby.
phonestringyes
contactsobject[]yes
contacts[].idstring (uuid)yes
contacts[].namestringyes
contacts[].jobTitlestringno
contacts[].emailstringyes
contacts[].phonestringno
contacts[].notestringno
contacts[].rolesstring[]yes
contacts[].isPrimarybooleanyes
isCustomerbooleanyes
isSupplierbooleanyes
defaultDueDaysinteger | nullno
documentLanguagestring | nullno
notestringno
vatVerifiedAtstring (date-time) | nullno
Kedy bolo IČ DPH overené vo VIES.
createdAtstring (date-time)yes
updatedAtstring (date-time)yes

PriceListItem

FieldTypeRequiredDescription
idstring (uuid)yes
namestringyes
detailstringyes
codestringyes
Vlastný kód položky (môže byť prázdny).
unitstringyes
unitPriceDecimalyes
pricesIncludeVatbooleanyes
true = unitPrice je s DPH.
vatRateinteger | nullyes
updatedAtstring (date-time)yes

NumberSeries

FieldTypeRequiredDescription
idstring (uuid)yes
documentTypeDocumentTypeyes
invoice faktúra, proforma zálohová faktúra, credit_note dobropis, corrective_invoice ťarchopis (opravná faktúra na zvýšenie), payment_receipt daňový doklad k prijatej platbe. Vystaviť cez POST /documents sa dá faktúra, zálohová faktúra a dobropis k faktúre mimo Renly (s originalDocument).
namestringyes
isDefaultbooleanyes
Predvolený rad druhu dokladu.
nextNumberPreviewstringyes
Číslo, ktoré by rad vydal dnes.

BankAccount

FieldTypeRequiredDescription
idstring (uuid)yes
bankNamestringyes
ibanstringyes
bicstringyes
currencystringyes
isDefaultbooleanyes

WebhookEvent

Type: string

Values: document.issued, document.payment_recorded, document.paid, document.payment_deleted, document.cancelled, document.sent

Webhook

FieldTypeRequiredDescription
idstring (uuid)yes
urlstring (uri)yes
testbooleanyes
Webhook testovacieho kľúča — dostáva iba udalosti testovacích dokladov.
eventsWebhookEvent[]yes
createdAtstring (date-time)yes
lastSuccessAtstring (date-time) | nullno
lastFailureAtstring (date-time) | nullno
consecutiveFailuresintegeryes

WebhookDelivery

FieldTypeRequiredDescription
idstring (uuid)yes
Rovnaké ako hlavička X-Renly-Delivery.
eventWebhookEventyes
documentIdstring (uuid)yes
statusstringyes

Values: pending, delivered, failed

attemptsintegeryes
lastStatusCodeinteger | nullno
lastErrorstring | nullno
lastAttemptAtstring (date-time) | nullno
deliveredAtstring (date-time) | nullno
createdAtstring (date-time)yes