FunkceJak to fungujeIntegraceCeníkFAQKontakt

Návody

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

bez oprávnění

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

Příklad požadavku

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

Odpovědi

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": []
}
PoleTypPovinnéPopis
dataMeano
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Objekt: 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).

Objekt: Error

PoleTypPovinnéPopis
errorobjectano
error.codestringano
Stabilný kód chyby.
error.messagestringano
Text pre človeka, môže sa zmeniť.
error.detailsobjectano
Podrobnosti, napr. fields, scope, existingId.

Doklady

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

Zoznam dokladov

GET/documents

Oprávnění: 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.

Parametry

NázevKdeTypPovinnéPopis
externalSourcequerystringne
Systém objednávky, ako pri vystavení. Iba spolu s externalId.
externalIdquerystringne
ID objednávky v systéme. Iba spolu s externalSource.
typequerystringne
Druhy dokladu oddelené čiarkou.
statusquerystringne
issued (vystavený) alebo cancelled (stornovaný), oddelené čiarkou. Predvolene oba.
paymentStatusquerystringne
unpaid, partially_paid, paid, overdue, oddelené čiarkou.
partnerIdquerystring (uuid)ne
Iba doklady partnera z adresára.
fromquerystring (date)ne
Dátum vystavenia od (vrátane).
toquerystring (date)ne
Dátum vystavenia do (vrátane).
qquerystringne
Hľadanie v čísle dokladu, mene a IČO odberateľa.
cursorquerystringne
meta.nextCursor predchádzajúcej stránky.
limitqueryintegerne
Počet záznamov na stránku.

Výchozí: 50

Příklad požadavku

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

Odpovědi

200
Doklady.
PoleTypPovinnéPopis
dataDocument[]ano
metaListMetaano
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.

Objekt: 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).

Objekt: 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).

Objekt: 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).

Objekt: Error

PoleTypPovinnéPopis
errorobjectano
error.codestringano
Stabilný kód chyby.
error.messagestringano
Text pre človeka, môže sa zmeniť.
error.detailsobjectano
Podrobnosti, napr. fields, scope, existingId.

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

POST/documents

Oprávnění: 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.

Parametry

NázevKdeTypPovinnéPopis
Idempotency-Keyhlavičkastringano
Jedinečný kľúč zápisu v spoločnosti, 1–255 viditeľných znakov ASCII. Pozri Idempotencia.

Tělo požadavku

Objekt: 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
}

Příklad požadavku

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
}'

Odpovědi

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": []
}
PoleTypPovinnéPopis
dataDocumentano
metaWriteMetane
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.

Objekt: 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).

Objekt: 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).

Objekt: 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.

Objekt: 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).

Objekt: Error

PoleTypPovinnéPopis
errorobjectano
error.codestringano
Stabilný kód chyby.
error.messagestringano
Text pre človeka, môže sa zmeniť.
error.detailsobjectano
Podrobnosti, napr. fields, scope, existingId.

Detail dokladu

GET/documents/{documentId}

Oprávnění: documents:read

Parametry

NázevKdeTypPovinnéPopis
documentIdcestastring (uuid)ano

Příklad požadavku

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

Odpovědi

200
Doklad.
PoleTypPovinnéPopis
dataDocumentano
metaWriteMetane
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Objekt: 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).

Objekt: 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.

Objekt: Error

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

Objekt: Error

PoleTypPovinnéPopis
errorobjectano
error.codestringano
Stabilný kód chyby.
error.messagestringano
Text pre človeka, môže sa zmeniť.
error.detailsobjectano
Podrobnosti, napr. fields, scope, existingId.

PDF dokladu

GET/documents/{documentId}/pdf

Oprávnění: documents:read

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

Parametry

NázevKdeTypPovinnéPopis
documentIdcestastring (uuid)ano
downloadquerystringne
1 = hlavička na stiahnutie súboru.

Hodnoty: 1

Příklad požadavku

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

Odpovědi

200
PDF.

application/pdf string (binary)

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

Objekt: 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).

Objekt: 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.

Objekt: Error

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

Objekt: Error

PoleTypPovinnéPopis
errorobjectano
error.codestringano
Stabilný kód chyby.
error.messagestringano
Text pre človeka, môže sa zmeniť.
error.detailsobjectano
Podrobnosti, napr. fields, scope, existingId.

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

POST/documents/{documentId}/final-invoice

Oprávnění: documents:write

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

Parametry

NázevKdeTypPovinnéPopis
documentIdcestastring (uuid)ano
Idempotency-Keyhlavičkastringano
Jedinečný kľúč zápisu v spoločnosti, 1–255 viditeľných znakov ASCII. Pozri Idempotencia.

Tělo požadavku

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

Příklad požadavku

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
}'

Odpovědi

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": []
}
PoleTypPovinnéPopis
dataDocumentano
metaWriteMetane
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.

Objekt: 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).

Objekt: 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).

Objekt: 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.

Objekt: 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.

Objekt: 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).

Objekt: Error

PoleTypPovinnéPopis
errorobjectano
error.codestringano
Stabilný kód chyby.
error.messagestringano
Text pre človeka, môže sa zmeniť.
error.detailsobjectano
Podrobnosti, napr. fields, scope, existingId.

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

POST/documents/{documentId}/credit-note

Oprávnění: 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).

Parametry

NázevKdeTypPovinnéPopis
documentIdcestastring (uuid)ano
Idempotency-Keyhlavičkastringano
Jedinečný kľúč zápisu v spoločnosti, 1–255 viditeľných znakov ASCII. Pozri Idempotencia.

Tělo požadavku

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

Příklad požadavku

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
}'

Odpovědi

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": []
}
PoleTypPovinnéPopis
dataDocumentano
metaWriteMetane
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.

Objekt: 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).

Objekt: 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).

Objekt: 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.

Objekt: 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.

Objekt: 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).

Objekt: Error

PoleTypPovinnéPopis
errorobjectano
error.codestringano
Stabilný kód chyby.
error.messagestringano
Text pre človeka, môže sa zmeniť.
error.detailsobjectano
Podrobnosti, napr. fields, scope, existingId.

Stornovať zálohovú faktúru

POST/documents/{documentId}/cancel

Oprávnění: documents:write

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

Parametry

NázevKdeTypPovinnéPopis
documentIdcestastring (uuid)ano
Idempotency-Keyhlavičkastringano
Jedinečný kľúč zápisu v spoločnosti, 1–255 viditeľných znakov ASCII. Pozri Idempotencia.

Tělo požadavku

json
{
  "reason": "Objednávka zrušená zákazníkom"
}
PoleTypPovinnéPopis
reasonstringano

Příklad požadavku

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"
}'

Odpovědi

200
Doklad.
PoleTypPovinnéPopis
dataDocumentano
metaWriteMetane
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.

Objekt: 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).

Objekt: 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).

Objekt: 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.

Objekt: 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.

Objekt: 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).

Objekt: Error

PoleTypPovinnéPopis
errorobjectano
error.codestringano
Stabilný kód chyby.
error.messagestringano
Text pre človeka, môže sa zmeniť.
error.detailsobjectano
Podrobnosti, napr. fields, scope, existingId.

Úhrady a odoslanie

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

Zapísať úhradu

POST/documents/{documentId}/payments

Oprávnění: 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.

Parametry

NázevKdeTypPovinnéPopis
documentIdcestastring (uuid)ano
Idempotency-Keyhlavičkastringano
Jedinečný kľúč zápisu v spoločnosti, 1–255 viditeľných znakov ASCII. Pozri Idempotencia.

Tělo požadavku

Objekt: PaymentInput

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

Příklad požadavku

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"
}'

Odpovědi

200
Doklad.
PoleTypPovinnéPopis
dataDocumentano
metaWriteMetane
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.

Objekt: 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).

Objekt: 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).

Objekt: 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.

Objekt: 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.

Objekt: 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).

Objekt: Error

PoleTypPovinnéPopis
errorobjectano
error.codestringano
Stabilný kód chyby.
error.messagestringano
Text pre človeka, môže sa zmeniť.
error.detailsobjectano
Podrobnosti, napr. fields, scope, existingId.

Poslať doklad e-mailom

POST/documents/{documentId}/send

Oprávnění: 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.

Parametry

NázevKdeTypPovinnéPopis
documentIdcestastring (uuid)ano
Idempotency-Keyhlavičkastringano
Jedinečný kľúč zápisu v spoločnosti, 1–255 viditeľných znakov ASCII. Pozri Idempotencia.

Tělo požadavku

Objekt: SendInput

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

Příklad požadavku

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."
}'

Odpovědi

200
Doklad.
PoleTypPovinnéPopis
dataDocumentano
metaWriteMetane
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.

Objekt: 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).

Objekt: 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).

Objekt: 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.

Objekt: 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.

Objekt: 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).

Objekt: Error

PoleTypPovinnéPopis
errorobjectano
error.codestringano
Stabilný kód chyby.
error.messagestringano
Text pre človeka, môže sa zmeniť.
error.detailsobjectano
Podrobnosti, napr. fields, scope, existingId.

Partneri

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

Zoznam partnerov

GET/partners

Oprávnění: partners:read

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

Parametry

NázevKdeTypPovinnéPopis
qquerystringne
Hľadanie v názve, IČO a kontaktných osobách.
rolequerystringne
Iba odberatelia alebo iba dodávatelia.

Hodnoty: customer, supplier

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

Výchozí: 50

Příklad požadavku

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

Odpovědi

200
Partneri.
PoleTypPovinnéPopis
dataPartner[]ano
metaListMetaano
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.

Objekt: 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).

Objekt: 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).

Objekt: 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).

Objekt: Error

PoleTypPovinnéPopis
errorobjectano
error.codestringano
Stabilný kód chyby.
error.messagestringano
Text pre človeka, môže sa zmeniť.
error.detailsobjectano
Podrobnosti, napr. fields, scope, existingId.

Založiť partnera

POST/partners

Oprávnění: 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).

Parametry

NázevKdeTypPovinnéPopis
Idempotency-Keyhlavičkastringano
Jedinečný kľúč zápisu v spoločnosti, 1–255 viditeľných znakov ASCII. Pozri Idempotencia.

Tělo požadavku

Objekt: 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
    }
  ]
}

Příklad požadavku

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
    }
  ]
}'

Odpovědi

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": []
}
PoleTypPovinnéPopis
dataPartnerano
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.

Objekt: 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).

Objekt: 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).

Objekt: 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.

Objekt: 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).

Objekt: Error

PoleTypPovinnéPopis
errorobjectano
error.codestringano
Stabilný kód chyby.
error.messagestringano
Text pre človeka, môže sa zmeniť.
error.detailsobjectano
Podrobnosti, napr. fields, scope, existingId.

Detail partnera

GET/partners/{partnerId}

Oprávnění: partners:read

Parametry

NázevKdeTypPovinnéPopis
partnerIdcestastring (uuid)ano

Příklad požadavku

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

Odpovědi

200
Partner.
PoleTypPovinnéPopis
dataPartnerano
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Objekt: 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).

Objekt: 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.

Objekt: Error

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

Objekt: Error

PoleTypPovinnéPopis
errorobjectano
error.codestringano
Stabilný kód chyby.
error.messagestringano
Text pre človeka, môže sa zmeniť.
error.detailsobjectano
Podrobnosti, napr. fields, scope, existingId.

Upraviť partnera

PATCH/partners/{partnerId}

Oprávnění: 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.

Parametry

NázevKdeTypPovinnéPopis
partnerIdcestastring (uuid)ano

Tělo požadavku

Objekt: PartnerInput

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

Příklad požadavku

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"
}'

Odpovědi

200
Partner.
PoleTypPovinnéPopis
dataPartnerano
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.

Objekt: 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).

Objekt: 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).

Objekt: 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.

Objekt: 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.

Objekt: 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).

Objekt: Error

PoleTypPovinnéPopis
errorobjectano
error.codestringano
Stabilný kód chyby.
error.messagestringano
Text pre človeka, môže sa zmeniť.
error.detailsobjectano
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

Oprávnění: catalog:read

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

Parametry

NázevKdeTypPovinnéPopis
qquerystringne
Hľadanie v názve a kóde položky.
cursorquerystringne
meta.nextCursor predchádzajúcej stránky.
limitqueryintegerne
Počet záznamov na stránku.

Výchozí: 50

Příklad požadavku

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

Odpovědi

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
  }
}
PoleTypPovinnéPopis
dataPriceListItem[]ano
metaListMetaano
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.

Objekt: 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).

Objekt: 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).

Objekt: 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).

Objekt: Error

PoleTypPovinnéPopis
errorobjectano
error.codestringano
Stabilný kód chyby.
error.messagestringano
Text pre človeka, môže sa zmeniť.
error.detailsobjectano
Podrobnosti, napr. fields, scope, existingId.

Položka cenníka

GET/price-list-items/{itemId}

Oprávnění: catalog:read

Parametry

NázevKdeTypPovinnéPopis
itemIdcestastring (uuid)ano

Příklad požadavku

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

Odpovědi

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

Objekt: 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).

Objekt: 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.

Objekt: Error

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

Objekt: Error

PoleTypPovinnéPopis
errorobjectano
error.codestringano
Stabilný kód chyby.
error.messagestringano
Text pre človeka, môže sa zmeniť.
error.detailsobjectano
Podrobnosti, napr. fields, scope, existingId.

Číselné rady

GET/number-series

Oprávnění: documents:read

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

Příklad požadavku

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

Odpovědi

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": []
}
PoleTypPovinnéPopis
dataNumberSeries[]ano
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Objekt: 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).

Objekt: 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).

Objekt: Error

PoleTypPovinnéPopis
errorobjectano
error.codestringano
Stabilný kód chyby.
error.messagestringano
Text pre človeka, môže sa zmeniť.
error.detailsobjectano
Podrobnosti, napr. fields, scope, existingId.

Bankové účty

GET/bank-accounts

Oprávnění: documents:read

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

Příklad požadavku

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

Odpovědi

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

Objekt: 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).

Objekt: 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).

Objekt: Error

PoleTypPovinnéPopis
errorobjectano
error.codestringano
Stabilný kód chyby.
error.messagestringano
Text pre človeka, môže sa zmeniť.
error.detailsobjectano
Podrobnosti, napr. fields, scope, existingId.

Webhooky

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

Zoznam webhookov

GET/webhooks

Oprávnění: webhooks:write

Příklad požadavku

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

Odpovědi

200
Aktívne adresy (bez tajomstva).
PoleTypPovinnéPopis
dataWebhook[]ano
metaobjectano
meta.limitintegerne
401
Kľúč chýba, je neplatný alebo zrušený (finance.api_key_unauthorized).

Objekt: 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).

Objekt: 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).

Objekt: Error

PoleTypPovinnéPopis
errorobjectano
error.codestringano
Stabilný kód chyby.
error.messagestringano
Text pre človeka, môže sa zmeniť.
error.detailsobjectano
Podrobnosti, napr. fields, scope, existingId.

Zaregistrovať webhook

POST/webhooks

Oprávnění: 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.

Tělo požadavku

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

Příklad požadavku

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"
  ]
}'

Odpovědi

201
Webhook so secret.
PoleTypPovinnéPopis
dataWebhook & objectano
data.secretstringano
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.

Objekt: 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).

Objekt: 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).

Objekt: 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.

Objekt: 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).

Objekt: Error

PoleTypPovinnéPopis
errorobjectano
error.codestringano
Stabilný kód chyby.
error.messagestringano
Text pre človeka, môže sa zmeniť.
error.detailsobjectano
Podrobnosti, napr. fields, scope, existingId.

Zmazať webhook

DELETE/webhooks/{webhookId}

Oprávnění: webhooks:write

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

Parametry

NázevKdeTypPovinnéPopis
webhookIdcestastring (uuid)ano

Příklad požadavku

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

Odpovědi

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

Objekt: 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).

Objekt: 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.

Objekt: Error

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

Objekt: Error

PoleTypPovinnéPopis
errorobjectano
error.codestringano
Stabilný kód chyby.
error.messagestringano
Text pre človeka, môže sa zmeniť.
error.detailsobjectano
Podrobnosti, napr. fields, scope, existingId.

História doručení

GET/webhooks/{webhookId}/deliveries

Oprávnění: webhooks:write

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

Parametry

NázevKdeTypPovinnéPopis
webhookIdcestastring (uuid)ano

Příklad požadavku

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

Odpovědi

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

Objekt: 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).

Objekt: 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.

Objekt: Error

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

Objekt: Error

PoleTypPovinnéPopis
errorobjectano
error.codestringano
Stabilný kód chyby.
error.messagestringano
Text pre človeka, môže sa zmeniť.
error.detailsobjectano
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

bez přihlášeníServer: 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.

Parametry

NázevKdeTypPovinnéPopis
tokencestastringano
downloadquerystringne

Hodnoty: 1

Příklad požadavku

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

Odpovědi

200
PDF.

application/pdf string (binary)

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

Objekt: Error

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

Objekty

Error

PoleTypPovinnéPopis
errorobjectano
error.codestringano
Stabilný kód chyby.
error.messagestringano
Text pre človeka, môže sa zmeniť.
error.detailsobjectano
Podrobnosti, napr. fields, scope, existingId.

ListMeta

PoleTypPovinnéPopis
limitintegerano
nextCursorstring | nullano
Kurzor ďalšej stránky, null = posledná stránka.

WriteMeta

PoleTypPovinnéPopis
sendErrorstringne
Kód chyby, keď doklad vznikol, ale e-mail sa nepodarilo odoslať (napr. finance.document_send_failed).

Me

PoleTypPovinnéPopis
keyobjectano
key.idstring (uuid)ano
key.namestringano
key.keyPrefixstringano
Začiatok kľúča (rfk_ alebo rfk_test_ a 12 znakov) — podľa neho ho spoznáte vo Financiách.
key.modestringano
test = testovací kľúč, doklady mimo radu, exportu, e-mailov a e-faktúr.

Hodnoty: live, test

key.scopesScope[]ano
key.createdByNamestringne
key.createdAtstring (date-time)ne
key.lastUsedAtstring (date-time) | nullne
key.revokedAtstring (date-time) | nullne
key.activebooleanano
companyobjectano
company.idstring (uuid)ano
company.tenantIdstring (uuid)ano
ID firmy v Renly.
company.namestringano
company.activebooleanano
false = spoločnosť nad limitom balíčka, API iba číta.

Scope

Typ: string

Hodnoty: 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).

Typ: string

Hodnoty: 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í).

Typ: string

Hodnoty: bank_transfer, cash, card, cash_on_delivery, other

Money

Typ: string

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

Příklad: 46.70

Decimal

Typ: string

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

Příklad: 19.90

Party

Odberateľ dokladu.

PoleTypPovinnéPopis
namestringne
icostringne
IČO (8 číslic).
dicstringne
DIČ.
icDphstringne
IČ DPH s kódom krajiny, napr. SK2020123456.
streetstringne
citystringne
postalCodestringne
countryCodestringne

Výchozí: SK

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

LineInput

PoleTypPovinnéPopis
descriptionstringano
detailstringne
Doplňujúci text pod názvom položky.
quantityDecimalano
unitstringne
unitPriceDecimalano
discountPercentDecimalne
vatRateinteger | nullne
Sadzba DPH; neplatiteľ null. Sadzby iných štátov iba pri vatMode: oss.

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

CreateDocument

PoleTypPovinnéPopis
typestringano
credit_note iba k faktúre mimo Renly — s originalDocument, correctionReason a zápornými množstvami.

Hodnoty: invoice, proforma, credit_note

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

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

Výchozí: EUR

exchangeRateDecimalne
languagestringne

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

Výchozí: sk

vatModestringne

Hodnoty: standard, reverse_charge, exempt, non_payer, oss

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

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

pricesIncludeVatbooleanne

Výchozí: false

discountPercentDecimalne
introTextstringne
Text nad položkami.
closingTextstringne
Text pod položkami.
internalNotestringne
Poznámka viditeľná iba vo Financiách.
paymentPaymentInputne
sendSendOptionne
true = e-mail s predvoleným textom, objekt = vlastní príjemcovia či text, false alebo nič = neposlať.

PaymentInput

PoleTypPovinnéPopis
amountMoneyne
Bez sumy celý zostatok.
paidOnstring (date)ano
methodPaymentMethodano
Prevod, hotovosť, karta, dobierka, iné. Odpoveď môže obsahovať aj advance (zápočet zálohy pri vyúčtovaní).
notestringne

SendInput

PoleTypPovinnéPopis
toarray<string (email)>ne
Príjemcovia; predvolene odberateľ alebo kontaktné osoby partnera.
ccarray<string (email)>ne
subjectstringne
messagestringne

SendOption

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

Typ: boolean | SendInput

Document

PoleTypPovinnéPopis
idstring (uuid)ano
typeDocumentTypeano
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).
statusstringano

Hodnoty: issued, cancelled

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

Hodnoty: unpaid, partially_paid, paid, overdue, null

numberstringano
variableSymbolstringne
orderNumberstringne
externalSourcestring | nullne
externalIdstring | nullne
testbooleanne
Testovací doklad z testovacieho kľúča — číslo TEST-…, nie je účtovným dokladom.
issueDatestring (date)ano
deliveryDatestring (date) | nullne
dueDatestring (date) | nullne
currencystringano
languagestringne
paymentMethodstringne
vatModestringne
vatCountrystring | nullne
Štát spotreby pri oss.
pricesIncludeVatbooleanne
buyerobjectano
buyer.namestringano
buyer.icostringano
buyer.dicstringano
buyer.icDphstringano
buyer.streetstringano
buyer.citystringano
buyer.postalCodestringano
buyer.countryCodestringano
buyer.emailstringano
linesobject[]ano
lines[].idstring (uuid)ne
ID položky — lineId čiastočného dobropisu.
lines[].kindstringano
advance = odpočet zálohy pri vyúčtovaní.

Hodnoty: item, advance

lines[].descriptionstringano
lines[].detailstringne
lines[].quantitystringano
lines[].unitstringne
lines[].unitPricestringano
lines[].discountPercentstringne
lines[].vatRateinteger | nullano
lines[].totalWithoutVatMoneyano
lines[].vatMoneyano
lines[].totalWithVatMoneyano
vatRecapobject[]ne
Rekapitulácia DPH po sadzbách (záväzná pre DPH); bez DPH prázdna.
vatRecap[].rateintegerano
vatRecap[].baseMoneyano
vatRecap[].vatMoneyano
vatRecap[].totalMoneyano
totalWithoutVatMoneyne
totalVatMoneyne
totalWithVatMoneyano
paidAmountMoneyne
remainingAmountMoneyano
Zostáva uhradiť: suma − úhrady − dobropisy.
creditedAmountMoneyne
Faktúra: súčet vystavených dobropisov s DPH (kladný).
paymentsobject[]ano
payments[].idstring (uuid)ano
payments[].amountMoneyano
payments[].paidOnstring (date)ano
payments[].methodstringano
relatedDocumentnull | objectne
Dobropis → faktúra, vyúčtovanie → zálohová faktúra.
relatedDocument.idstring (uuid)ano
relatedDocument.typeDocumentTypeano
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 | nullano
originalDocumentnull | objectne
Dobropis k faktúre mimo Renly: číslo a dátum pôvodnej faktúry; inak null.
originalDocument.numberstringano
originalDocument.issueDatestring (date) | nullano
publicPdfUrlstring (uri) | nullano
PDF bez prihlásenia; null pri doklade vystavenom v appke alebo po storne.
sentAtstring (date-time) | nullne
issuedAtstring (date-time) | nullne
cancelledAtstring (date-time) | nullne
createdAtstring (date-time)ne
updatedAtstring (date-time)ne

PartnerContactInput

PoleTypPovinnéPopis
idstring (uuid)ne
Existujúca osoba; bez id vznikne nová.
namestringne
jobTitlestringne
emailstring (email)ne
phonestringne
notestringne
rolesstring[]ne
invoices dostáva doklady, deals ponuky a objednávky, reminders upomienky, copy kópiu.
isPrimarybooleanne

PartnerInput

PoleTypPovinnéPopis
namestringne
Povinné pri založení.
icostringne
dicstringne
icDphstringne
registryEntrystringne
Zápis v obchodnom registri.
streetstringne
citystringne
postalCodestringne
countryCodestringne

Výchozí: SK

emailstring (email)ne
phonestringne
isCustomerbooleanne

Výchozí: true

isSupplierbooleanne

Výchozí: false

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

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

notestringne
contactsPartnerContactInput[]ne

Partner

PoleTypPovinnéPopis
idstring (uuid)ano
testbooleanano
Testovací partner založený testovacím kľúčom.
namestringano
icostringano
dicstringano
icDphstringano
registryEntrystringne
streetstringano
citystringano
postalCodestringano
countryCodestringano
emailstringano
E-mail hlavnej kontaktnej osoby.
phonestringano
contactsobject[]ano
contacts[].idstring (uuid)ano
contacts[].namestringano
contacts[].jobTitlestringne
contacts[].emailstringano
contacts[].phonestringne
contacts[].notestringne
contacts[].rolesstring[]ano
contacts[].isPrimarybooleanano
isCustomerbooleanano
isSupplierbooleanano
defaultDueDaysinteger | nullne
documentLanguagestring | nullne
notestringne
vatVerifiedAtstring (date-time) | nullne
Kedy bolo IČ DPH overené vo VIES.
createdAtstring (date-time)ano
updatedAtstring (date-time)ano

PriceListItem

PoleTypPovinnéPopis
idstring (uuid)ano
namestringano
detailstringano
codestringano
Vlastný kód položky (môže byť prázdny).
unitstringano
unitPriceDecimalano
pricesIncludeVatbooleanano
true = unitPrice je s DPH.
vatRateinteger | nullano
updatedAtstring (date-time)ano

NumberSeries

PoleTypPovinnéPopis
idstring (uuid)ano
documentTypeDocumentTypeano
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).
namestringano
isDefaultbooleanano
Predvolený rad druhu dokladu.
nextNumberPreviewstringano
Číslo, ktoré by rad vydal dnes.

BankAccount

PoleTypPovinnéPopis
idstring (uuid)ano
bankNamestringano
ibanstringano
bicstringano
currencystringano
isDefaultbooleanano

WebhookEvent

Typ: string

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

Webhook

PoleTypPovinnéPopis
idstring (uuid)ano
urlstring (uri)ano
testbooleanano
Webhook testovacieho kľúča — dostáva iba udalosti testovacích dokladov.
eventsWebhookEvent[]ano
createdAtstring (date-time)ano
lastSuccessAtstring (date-time) | nullne
lastFailureAtstring (date-time) | nullne
consecutiveFailuresintegerano

WebhookDelivery

PoleTypPovinnéPopis
idstring (uuid)ano
Rovnaké ako hlavička X-Renly-Delivery.
eventWebhookEventano
documentIdstring (uuid)ano
statusstringano

Hodnoty: pending, delivered, failed

attemptsintegerano
lastStatusCodeinteger | nullne
lastErrorstring | nullne
lastAttemptAtstring (date-time) | nullne
deliveredAtstring (date-time) | nullne
createdAtstring (date-time)ano