FunkcieAko to fungujeIntegrácieCenní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}.

Referencia

Kľúč

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

Kľúč a spoločnosť

GET/me

bez oprávnenia

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

Príklad požiadavky

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

Odpovede

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
dataMeáno
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
errorobjectáno
error.codestringáno
Stabilný kód chyby.
error.messagestringáno
Text pre človeka, môže sa zmeniť.
error.detailsobjectáno
Podrobnosti, napr. fields, scope, existingId.

Doklady

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

Zoznam dokladov

GET/documents

Oprávnenie: 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.

Parametre

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

Predvolene: 50

Príklad požiadavky

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

Odpovede

200
Doklady.
PoleTypPovinnéPopis
dataDocument[]áno
metaListMetaáno
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
errorobjectáno
error.codestringáno
Stabilný kód chyby.
error.messagestringáno
Text pre človeka, môže sa zmeniť.
error.detailsobjectáno
Podrobnosti, napr. fields, scope, existingId.

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

POST/documents

Oprávnenie: 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.

Parametre

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

Telo požiadavky

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
}

Príklad požiadavky

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

Odpovede

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
dataDocumentáno
metaWriteMetanie
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
errorobjectáno
error.codestringáno
Stabilný kód chyby.
error.messagestringáno
Text pre človeka, môže sa zmeniť.
error.detailsobjectáno
Podrobnosti, napr. fields, scope, existingId.

Detail dokladu

GET/documents/{documentId}

Oprávnenie: documents:read

Parametre

NázovKdeTypPovinnéPopis
documentIdcestastring (uuid)áno

Príklad požiadavky

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

Odpovede

200
Doklad.
PoleTypPovinnéPopis
dataDocumentáno
metaWriteMetanie
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
errorobjectáno
error.codestringáno
Stabilný kód chyby.
error.messagestringáno
Text pre človeka, môže sa zmeniť.
error.detailsobjectáno
Podrobnosti, napr. fields, scope, existingId.

PDF dokladu

GET/documents/{documentId}/pdf

Oprávnenie: documents:read

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

Parametre

NázovKdeTypPovinnéPopis
documentIdcestastring (uuid)áno
downloadquerystringnie
1 = hlavička na stiahnutie súboru.

Hodnoty: 1

Príklad požiadavky

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

Odpovede

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
errorobjectáno
error.codestringáno
Stabilný kód chyby.
error.messagestringáno
Text pre človeka, môže sa zmeniť.
error.detailsobjectáno
Podrobnosti, napr. fields, scope, existingId.

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

POST/documents/{documentId}/final-invoice

Oprávnenie: documents:write

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

Parametre

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

Telo požiadavky

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

Príklad požiadavky

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

Odpovede

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
dataDocumentáno
metaWriteMetanie
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
errorobjectáno
error.codestringáno
Stabilný kód chyby.
error.messagestringáno
Text pre človeka, môže sa zmeniť.
error.detailsobjectáno
Podrobnosti, napr. fields, scope, existingId.

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

POST/documents/{documentId}/credit-note

Oprávnenie: 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).

Parametre

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

Telo požiadavky

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

Príklad požiadavky

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

Odpovede

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
dataDocumentáno
metaWriteMetanie
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
errorobjectáno
error.codestringáno
Stabilný kód chyby.
error.messagestringáno
Text pre človeka, môže sa zmeniť.
error.detailsobjectáno
Podrobnosti, napr. fields, scope, existingId.

Stornovať zálohovú faktúru

POST/documents/{documentId}/cancel

Oprávnenie: documents:write

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

Parametre

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

Telo požiadavky

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

Príklad požiadavky

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

Odpovede

200
Doklad.
PoleTypPovinnéPopis
dataDocumentáno
metaWriteMetanie
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
errorobjectáno
error.codestringáno
Stabilný kód chyby.
error.messagestringáno
Text pre človeka, môže sa zmeniť.
error.detailsobjectáno
Podrobnosti, napr. fields, scope, existingId.

Úhrady a odoslanie

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

Zapísať úhradu

POST/documents/{documentId}/payments

Oprávnenie: 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.

Parametre

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

Telo požiadavky

Objekt: PaymentInput

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

Príklad požiadavky

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

Odpovede

200
Doklad.
PoleTypPovinnéPopis
dataDocumentáno
metaWriteMetanie
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
errorobjectáno
error.codestringáno
Stabilný kód chyby.
error.messagestringáno
Text pre človeka, môže sa zmeniť.
error.detailsobjectáno
Podrobnosti, napr. fields, scope, existingId.

Poslať doklad e-mailom

POST/documents/{documentId}/send

Oprávnenie: 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.

Parametre

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

Telo požiadavky

Objekt: SendInput

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

Príklad požiadavky

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

Odpovede

200
Doklad.
PoleTypPovinnéPopis
dataDocumentáno
metaWriteMetanie
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
errorobjectáno
error.codestringáno
Stabilný kód chyby.
error.messagestringáno
Text pre človeka, môže sa zmeniť.
error.detailsobjectáno
Podrobnosti, napr. fields, scope, existingId.

Partneri

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

Zoznam partnerov

GET/partners

Oprávnenie: partners:read

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

Parametre

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

Hodnoty: customer, supplier

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

Predvolene: 50

Príklad požiadavky

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

Odpovede

200
Partneri.
PoleTypPovinnéPopis
dataPartner[]áno
metaListMetaáno
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
errorobjectáno
error.codestringáno
Stabilný kód chyby.
error.messagestringáno
Text pre človeka, môže sa zmeniť.
error.detailsobjectáno
Podrobnosti, napr. fields, scope, existingId.

Založiť partnera

POST/partners

Oprávnenie: 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).

Parametre

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

Telo požiadavky

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

Príklad požiadavky

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

Odpovede

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
dataPartneráno
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
errorobjectáno
error.codestringáno
Stabilný kód chyby.
error.messagestringáno
Text pre človeka, môže sa zmeniť.
error.detailsobjectáno
Podrobnosti, napr. fields, scope, existingId.

Detail partnera

GET/partners/{partnerId}

Oprávnenie: partners:read

Parametre

NázovKdeTypPovinnéPopis
partnerIdcestastring (uuid)áno

Príklad požiadavky

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

Odpovede

200
Partner.
PoleTypPovinnéPopis
dataPartneráno
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
errorobjectáno
error.codestringáno
Stabilný kód chyby.
error.messagestringáno
Text pre človeka, môže sa zmeniť.
error.detailsobjectáno
Podrobnosti, napr. fields, scope, existingId.

Upraviť partnera

PATCH/partners/{partnerId}

Oprávnenie: 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.

Parametre

NázovKdeTypPovinnéPopis
partnerIdcestastring (uuid)áno

Telo požiadavky

Objekt: PartnerInput

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

Príklad požiadavky

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

Odpovede

200
Partner.
PoleTypPovinnéPopis
dataPartneráno
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
errorobjectáno
error.codestringáno
Stabilný kód chyby.
error.messagestringáno
Text pre človeka, môže sa zmeniť.
error.detailsobjectáno
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ávnenie: catalog:read

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

Parametre

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

Predvolene: 50

Príklad požiadavky

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

Odpovede

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[]áno
metaListMetaáno
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
errorobjectáno
error.codestringáno
Stabilný kód chyby.
error.messagestringáno
Text pre človeka, môže sa zmeniť.
error.detailsobjectáno
Podrobnosti, napr. fields, scope, existingId.

Položka cenníka

GET/price-list-items/{itemId}

Oprávnenie: catalog:read

Parametre

NázovKdeTypPovinnéPopis
itemIdcestastring (uuid)áno

Príklad požiadavky

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

Odpovede

200
Položka.
PoleTypPovinnéPopis
dataPriceListItemáno
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
errorobjectáno
error.codestringáno
Stabilný kód chyby.
error.messagestringáno
Text pre človeka, môže sa zmeniť.
error.detailsobjectáno
Podrobnosti, napr. fields, scope, existingId.

Číselné rady

GET/number-series

Oprávnenie: documents:read

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

Príklad požiadavky

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

Odpovede

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[]áno
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
errorobjectáno
error.codestringáno
Stabilný kód chyby.
error.messagestringáno
Text pre človeka, môže sa zmeniť.
error.detailsobjectáno
Podrobnosti, napr. fields, scope, existingId.

Bankové účty

GET/bank-accounts

Oprávnenie: documents:read

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

Príklad požiadavky

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

Odpovede

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[]áno
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
errorobjectáno
error.codestringáno
Stabilný kód chyby.
error.messagestringáno
Text pre človeka, môže sa zmeniť.
error.detailsobjectáno
Podrobnosti, napr. fields, scope, existingId.

Webhooky

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

Zoznam webhookov

GET/webhooks

Oprávnenie: webhooks:write

Príklad požiadavky

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

Odpovede

200
Aktívne adresy (bez tajomstva).
PoleTypPovinnéPopis
dataWebhook[]áno
metaobjectáno
meta.limitintegernie
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
errorobjectáno
error.codestringáno
Stabilný kód chyby.
error.messagestringáno
Text pre človeka, môže sa zmeniť.
error.detailsobjectáno
Podrobnosti, napr. fields, scope, existingId.

Zaregistrovať webhook

POST/webhooks

Oprávnenie: 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.

Telo požiadavky

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

Príklad požiadavky

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

Odpovede

201
Webhook so secret.
PoleTypPovinnéPopis
dataWebhook & objectáno
data.secretstringáno
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
errorobjectáno
error.codestringáno
Stabilný kód chyby.
error.messagestringáno
Text pre človeka, môže sa zmeniť.
error.detailsobjectáno
Podrobnosti, napr. fields, scope, existingId.

Zmazať webhook

DELETE/webhooks/{webhookId}

Oprávnenie: webhooks:write

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

Parametre

NázovKdeTypPovinnéPopis
webhookIdcestastring (uuid)áno

Príklad požiadavky

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

Odpovede

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
errorobjectáno
error.codestringáno
Stabilný kód chyby.
error.messagestringáno
Text pre človeka, môže sa zmeniť.
error.detailsobjectáno
Podrobnosti, napr. fields, scope, existingId.

História doručení

GET/webhooks/{webhookId}/deliveries

Oprávnenie: webhooks:write

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

Parametre

NázovKdeTypPovinnéPopis
webhookIdcestastring (uuid)áno

Príklad požiadavky

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

Odpovede

200
Doručenia.
PoleTypPovinnéPopis
dataWebhookDelivery[]áno
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
errorobjectáno
error.codestringáno
Stabilný kód chyby.
error.messagestringáno
Text pre človeka, môže sa zmeniť.
error.detailsobjectáno
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 prihláseniaServer: 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.

Parametre

NázovKdeTypPovinnéPopis
tokencestastringáno
downloadquerystringnie

Hodnoty: 1

Príklad požiadavky

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

Odpovede

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
errorobjectáno
error.codestringáno
Stabilný kód chyby.
error.messagestringáno
Text pre človeka, môže sa zmeniť.
error.detailsobjectáno
Podrobnosti, napr. fields, scope, existingId.

ListMeta

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

WriteMeta

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

Me

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

Hodnoty: live, test

key.scopesScope[]áno
key.createdByNamestringnie
key.createdAtstring (date-time)nie
key.lastUsedAtstring (date-time) | nullnie
key.revokedAtstring (date-time) | nullnie
key.activebooleanáno
companyobjectáno
company.idstring (uuid)áno
company.tenantIdstring (uuid)áno
ID firmy v Renly.
company.namestringáno
company.activebooleanáno
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}$

Príklad: 46.70

Decimal

Typ: string

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

Príklad: 19.90

Party

Odberateľ dokladu.

PoleTypPovinnéPopis
namestringnie
icostringnie
IČO (8 číslic).
dicstringnie
DIČ.
icDphstringnie
IČ DPH s kódom krajiny, napr. SK2020123456.
streetstringnie
citystringnie
postalCodestringnie
countryCodestringnie

Predvolene: SK

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

LineInput

PoleTypPovinnéPopis
descriptionstringáno
detailstringnie
Doplňujúci text pod názvom položky.
quantityDecimaláno
unitstringnie
unitPriceDecimaláno
discountPercentDecimalnie
vatRateinteger | nullnie
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
typestringáno
credit_note iba k faktúre mimo Renly — s originalDocument, correctionReason a zápornými množstvami.

Hodnoty: invoice, proforma, credit_note

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

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

Predvolene: EUR

exchangeRateDecimalnie
languagestringnie

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

Predvolene: sk

vatModestringnie

Hodnoty: standard, reverse_charge, exempt, non_payer, oss

vatCountrystringnie
Štát spotreby pri oss (AT, CZ, DE, HU, PL); predvolene štát odberateľa.
vatExemptionReasonstringnie
Povinný pri exempt.
vatExemptionCodestring | nullnie
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

pricesIncludeVatbooleannie

Predvolene: false

discountPercentDecimalnie
introTextstringnie
Text nad položkami.
closingTextstringnie
Text pod položkami.
internalNotestringnie
Poznámka viditeľná iba vo Financiách.
paymentPaymentInputnie
sendSendOptionnie
true = e-mail s predvoleným textom, objekt = vlastní príjemcovia či text, false alebo nič = neposlať.

PaymentInput

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

SendInput

PoleTypPovinnéPopis
toarray<string (email)>nie
Príjemcovia; predvolene odberateľ alebo kontaktné osoby partnera.
ccarray<string (email)>nie
subjectstringnie
messagestringnie

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)áno
typeDocumentTypeáno
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).
statusstringáno

Hodnoty: issued, cancelled

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

Hodnoty: unpaid, partially_paid, paid, overdue, null

numberstringáno
variableSymbolstringnie
orderNumberstringnie
externalSourcestring | nullnie
externalIdstring | nullnie
testbooleannie
Testovací doklad z testovacieho kľúča — číslo TEST-…, nie je účtovným dokladom.
issueDatestring (date)áno
deliveryDatestring (date) | nullnie
dueDatestring (date) | nullnie
currencystringáno
languagestringnie
paymentMethodstringnie
vatModestringnie
vatCountrystring | nullnie
Štát spotreby pri oss.
pricesIncludeVatbooleannie
buyerobjectáno
buyer.namestringáno
buyer.icostringáno
buyer.dicstringáno
buyer.icDphstringáno
buyer.streetstringáno
buyer.citystringáno
buyer.postalCodestringáno
buyer.countryCodestringáno
buyer.emailstringáno
linesobject[]áno
lines[].idstring (uuid)nie
ID položky — lineId čiastočného dobropisu.
lines[].kindstringáno
advance = odpočet zálohy pri vyúčtovaní.

Hodnoty: item, advance

lines[].descriptionstringáno
lines[].detailstringnie
lines[].quantitystringáno
lines[].unitstringnie
lines[].unitPricestringáno
lines[].discountPercentstringnie
lines[].vatRateinteger | nulláno
lines[].totalWithoutVatMoneyáno
lines[].vatMoneyáno
lines[].totalWithVatMoneyáno
vatRecapobject[]nie
Rekapitulácia DPH po sadzbách (záväzná pre DPH); bez DPH prázdna.
vatRecap[].rateintegeráno
vatRecap[].baseMoneyáno
vatRecap[].vatMoneyáno
vatRecap[].totalMoneyáno
totalWithoutVatMoneynie
totalVatMoneynie
totalWithVatMoneyáno
paidAmountMoneynie
remainingAmountMoneyáno
Zostáva uhradiť: suma − úhrady − dobropisy.
creditedAmountMoneynie
Faktúra: súčet vystavených dobropisov s DPH (kladný).
paymentsobject[]áno
payments[].idstring (uuid)áno
payments[].amountMoneyáno
payments[].paidOnstring (date)áno
payments[].methodstringáno
relatedDocumentnull | objectnie
Dobropis → faktúra, vyúčtovanie → zálohová faktúra.
relatedDocument.idstring (uuid)áno
relatedDocument.typeDocumentTypeáno
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 | nulláno
originalDocumentnull | objectnie
Dobropis k faktúre mimo Renly: číslo a dátum pôvodnej faktúry; inak null.
originalDocument.numberstringáno
originalDocument.issueDatestring (date) | nulláno
publicPdfUrlstring (uri) | nulláno
PDF bez prihlásenia; null pri doklade vystavenom v appke alebo po storne.
sentAtstring (date-time) | nullnie
issuedAtstring (date-time) | nullnie
cancelledAtstring (date-time) | nullnie
createdAtstring (date-time)nie
updatedAtstring (date-time)nie

PartnerContactInput

PoleTypPovinnéPopis
idstring (uuid)nie
Existujúca osoba; bez id vznikne nová.
namestringnie
jobTitlestringnie
emailstring (email)nie
phonestringnie
notestringnie
rolesstring[]nie
invoices dostáva doklady, deals ponuky a objednávky, reminders upomienky, copy kópiu.
isPrimarybooleannie

PartnerInput

PoleTypPovinnéPopis
namestringnie
Povinné pri založení.
icostringnie
dicstringnie
icDphstringnie
registryEntrystringnie
Zápis v obchodnom registri.
streetstringnie
citystringnie
postalCodestringnie
countryCodestringnie

Predvolene: SK

emailstring (email)nie
phonestringnie
isCustomerbooleannie

Predvolene: true

isSupplierbooleannie

Predvolene: false

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

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

notestringnie
contactsPartnerContactInput[]nie

Partner

PoleTypPovinnéPopis
idstring (uuid)áno
testbooleanáno
Testovací partner založený testovacím kľúčom.
namestringáno
icostringáno
dicstringáno
icDphstringáno
registryEntrystringnie
streetstringáno
citystringáno
postalCodestringáno
countryCodestringáno
emailstringáno
E-mail hlavnej kontaktnej osoby.
phonestringáno
contactsobject[]áno
contacts[].idstring (uuid)áno
contacts[].namestringáno
contacts[].jobTitlestringnie
contacts[].emailstringáno
contacts[].phonestringnie
contacts[].notestringnie
contacts[].rolesstring[]áno
contacts[].isPrimarybooleanáno
isCustomerbooleanáno
isSupplierbooleanáno
defaultDueDaysinteger | nullnie
documentLanguagestring | nullnie
notestringnie
vatVerifiedAtstring (date-time) | nullnie
Kedy bolo IČ DPH overené vo VIES.
createdAtstring (date-time)áno
updatedAtstring (date-time)áno

PriceListItem

PoleTypPovinnéPopis
idstring (uuid)áno
namestringáno
detailstringáno
codestringáno
Vlastný kód položky (môže byť prázdny).
unitstringáno
unitPriceDecimaláno
pricesIncludeVatbooleanáno
true = unitPrice je s DPH.
vatRateinteger | nulláno
updatedAtstring (date-time)áno

NumberSeries

PoleTypPovinnéPopis
idstring (uuid)áno
documentTypeDocumentTypeáno
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).
namestringáno
isDefaultbooleanáno
Predvolený rad druhu dokladu.
nextNumberPreviewstringáno
Číslo, ktoré by rad vydal dnes.

BankAccount

PoleTypPovinnéPopis
idstring (uuid)áno
bankNamestringáno
ibanstringáno
bicstringáno
currencystringáno
isDefaultbooleanáno

WebhookEvent

Typ: string

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

Webhook

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

WebhookDelivery

PoleTypPovinnéPopis
idstring (uuid)áno
Rovnaké ako hlavička X-Renly-Delivery.
eventWebhookEventáno
documentIdstring (uuid)áno
statusstringáno

Hodnoty: pending, delivered, failed

attemptsintegeráno
lastStatusCodeinteger | nullnie
lastErrorstring | nullnie
lastAttemptAtstring (date-time) | nullnie
deliveredAtstring (date-time) | nullnie
createdAtstring (date-time)áno