Renly Financie API
Dokumentace API je zatím jen ve slovenštině.
Vystavujte faktúry, zapisujte úhrady a spravujte partnerov z vlastného systému.
API Financií je pre e-shopy, pokladne, rezervačné systémy a ďalšie aplikácie, ktoré chcú vystavovať doklady cez Renly Financie. Financie dokladu pridelia číslo z radu, vytvoria PDF so vzhľadom vašej firmy, pošlú ho odberateľovi e-mailom, evidujú úhrady, upomínajú po splatnosti a doklad odovzdajú účtovníkovi rovnako ako doklad vystavený ručne.
- Základní adresa
https://api.renly.sk/api/v1/finance/external- Verze
1.0
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ľúč
- Vo Financiách otvorte Nastavenie → API a e-shopy (finance.renly.sk/nastavenie/api).
- Kliknite na Nový API kľúč, zadajte názov systému (napr. „E-shop mojafirma.sk“) a nechajte oprávnenia Čítanie dokladov a Vystavovanie dokladov.
- 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:
export RENLY_FINANCE_KEY='rfk_…'2. Overte kľúč
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
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
- Faktúru pošlite zákazníkovi e-mailom:
"send": truepri vystavení aleboPOST /documents/{id}/send. - Keď zákazník zaplatí, zapíšte úhradu:
POST /documents/{id}/payments. - O úhradách zapísaných vo Financiách (napríklad z bankového výpisu) sa dozviete cez webhooky.
Prihlásenie a oprávnenia
Každá požiadavka posiela kľúč v hlavičke Authorization:
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:write | vystaviť faktúru a zálohovú faktúru, dobropis, vyúčtovanie zálohy, storno a odoslanie e-mailom |
payments:write | zapísať úhradu dokladu |
partners:read | čítať adresár partnerov |
partners:write | založiť a upraviť partnera |
catalog:read | čítať cenník položiek |
webhooks:write | registrovať 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énumberdostane 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.
sendaPOST /documents/{id}/sendodoslanie iba zaznamenajú (sentAt, história, webhookdocument.sent). E-faktúra z testovacieho dokladu nevznikne. - PDF má vodoznak „TESTOVACÍ – NEPLATNÝ“ a nemá QR kód na platbu. Verejný odkaz
publicPdfUrlfunguje. - Odpoveď má hlavičku
X-Renly-Test-Mode: truea doklad, partner aj webhook poletest: true.GET /mevrátikey.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 (
PATCHvráti403 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
"", nienull.nullznamená, že údaj neexistuje (napríkladsentAtneodoslané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):
vatMode | kedy |
|---|---|
standard | bežný doklad platiteľa DPH (predvolené) |
reverse_charge | prenesenie daňovej povinnosti, napr. firma z inej krajiny EÚ s IČ DPH — sadzby sa vynulujú |
exempt | oslobodené plnenie, napr. zákazník mimo EÚ — povinný vatExemptionReason |
non_payer | dodávateľ nie je platiteľ DPH (nastaví sa sám podľa profilu spoločnosti) |
oss | spotrebiteľ 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:
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.
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
5xxpož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ť.
{ "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.
| stav | kód | čo spraviť |
|---|---|---|
| 400 | admin.invalid_json | telo nie je platný JSON objekt |
| 400 | finance.document_invalid, finance.partner_invalid, finance.webhook_invalid | opravte polia z details.fields a pošlite znova s tým istým Idempotency-Key |
| 400 | finance.document_incomplete | doklad nemá všetko na vystavenie (details.fields); nevznikne ani ako koncept |
| 400 | finance.idempotency_key_required, finance.idempotency_key_invalid | doplňte alebo opravte hlavičku Idempotency-Key |
| 401 | finance.api_key_unauthorized | kľúč chýba, je neúplný alebo zrušený — neopakujte |
| 403 | finance.api_key_scope_missing | kľúču chýba oprávnenie z details.scope |
| 403 | finance.api_not_available | firma nemá Financie v balíčku alebo je vypnutá |
| 403 | finance.api_test_mode_forbidden | testovací kľúč mení iba testovacích partnerov (testovanie) |
| 404 | finance.document_not_found, finance.partner_not_found, finance.price_list_item_not_found, finance.webhook_not_found | záznam neexistuje alebo patrí inej spoločnosti |
| 409 | finance.document_not_editable | akcia sa na doklad v jeho stave nedá urobiť (napr. storno uhradenej zálohy) |
| 409 | finance.payment_exceeds_total | úhrada je vyššia ako zostatok (details.remainingAmount) |
| 409 | finance.document_issue_quota | firma vyčerpala počet dokladov balíčka |
| 409 | finance.api_test_limit | spoločnosť má 1 000 testovacích dokladov — zmažte ich vo Financiách (details.limit) |
| 409 | finance.document_number_conflict | vlastné číslo number už má iný doklad |
| 409 | finance.partner_duplicate | partner s rovnakým IČO už existuje (details.existingId) |
| 409 | finance.idempotency_key_reused | ten istý Idempotency-Key s iným telom |
| 409 | finance.company_inactive | spoločnosť je nad limitom balíčka, iba čítanie |
| 409 | finance.profile_incomplete | spoločnosť nemá vo Financiách vyplnené údaje firmy (details.fields) — dokončite sprievodcu alebo Nastavenie → Firma |
| 429 | finance.api_rate_limited | poč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
| čo | limit |
|---|---|
| požiadavky | 120 za minútu na kľúč, potom 429 s hlavičkou Retry-After (sekundy) |
| aktívne kľúče | 10 na spoločnosť |
| webhooky | 5 adries na spoločnosť |
| stránka zoznamu | najviac 100 záznamov (limit), doklady jednej objednávky najviac 50 |
| verejné PDF | 120 stiahnutí za 10 minút na odkaz a IP adresu |
| doklady | podľ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:
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
}'externalSourceaexternalIdspoja doklad s objednávkou — podľa nich neskôr nájdete všetky jej doklady.- Firma: doplňte do
buyerajico,dicaicDph. Firme z EÚ s IČ DPH pošlite"vatMode": "reverse_charge". - Zľava:
discountPercentpri položke, alebo samostatná položka so záporným množstvom. - Bez
paymentje faktúra neuhradená a splatnosť dostane podľa nastavenia spoločnosti alebo partnera.
Scenár: platba prevodom so zálohovou faktúrou
- 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. - Keď peniaze prídu, zapíšte úhradu:
POST /documents/{id}/paymentss{ "paidOn": "2027-01-06", "method": "bank_transfer" }. Ak úhradu zapíše účtovník z bankového výpisu, dozviete sa to webhookomdocument.paid. - Vystavte faktúru, ktorá zálohu vyúčtuje:
POST /documents/{id}/final-invoices{ "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:
"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:
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.
- Nájdite partnera podľa IČO alebo názvu:
GET /partners?q=36512345. - Ak neexistuje, založte ho:
POST /partnerssIdempotency-Key, napr.mojsystem:zakaznik-77:partner. Partner s IČO, ktoré už v adresári je, vráti409 finance.partner_duplicatesdetails.existingId. - Vystavte doklad s
"partnerId": "…"(bezbuyer). Ak pošlete ajbuyer, má prednosť pred adresárom. - 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" } ] };lineIdjelines[].idfaktú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.issued | vystavený doklad, aj dobropis a vyúčtovanie zálohy |
document.payment_recorded | zapísaná úhrada (aj čiastočná) |
document.paid | doklad je po úhrade celý uhradený |
document.payment_deleted | úhrada bola zmazaná |
document.cancelled | stornovaná zálohová faktúra |
document.sent | doklad alebo upomienka odoslaná e-mailom |
Hlavičky požiadavky:
| hlavička | hodnota |
|---|---|
X-Renly-Event | udalosť, napr. document.paid |
X-Renly-Delivery | ID doručenia — rovnaké pri každom pokuse |
X-Renly-Timestamp | čas pokusu (Unix sekundy) |
X-Renly-Signature | sha256= + hex HMAC-SHA256 tajomstva nad "<X-Renly-Timestamp>.<telo>" |
{ "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):
$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:
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
2xxdo 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.documentje stav v čase udalosti; aktuálny stav si načítajte cezGET /documents/{id}.
Reference
Kľúč
Overenie kľúča a spoločnosti, ku ktorej patrí.
Kľúč a spoločnosť
GET/me
Overí kľúč a vráti jeho oprávnenia a spoločnosť, za ktorú systém pracuje. Nepotrebuje oprávnenie.
Příklad požadavku
curl -s "https://api.renly.sk/api/v1/finance/external/me" \
-H "Authorization: Bearer $RENLY_FINANCE_KEY"Odpovědi
{
"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": []
}| Pole | Typ | Povinné | Popis |
|---|---|---|---|
data | Me | ano |
finance.api_key_unauthorized).Objekt: Error
{
"error": {
"code": "finance.api_key_unauthorized",
"message": "API kľúč chýba, je neplatný alebo bol zrušený.",
"details": []
}
}finance.api_rate_limited).Objekt: Error
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
error | object | ano | |
error.code | string | ano | Stabilný kód chyby. |
error.message | string | ano | Text pre človeka, môže sa zmeniť. |
error.details | object | ano | Podrobnosti, napr. fields, scope, existingId. |
Doklady
Faktúry, zálohové faktúry, dobropisy a ich PDF.
Zoznam dokladov
GET/documents
Dva spôsoby hľadania:
- Doklady objednávky — s
externalSourceaexternalIdvráti všetky doklady jednej objednávky (zálohová faktúra, faktúra, dobropisy) od najstaršieho, najviac 50, bez stránkovania. - Všetky doklady — bez nich vráti vystavené a stornované účtovné doklady spoločnosti od najnovšieho (podľa dátumu vystavenia a čísla) s filtrami a stránkovaním. Aj doklady vystavené v appke alebo iným systémom.
Koncepty (rozpísané doklady v appke), cenové ponuky, objednávky a dodacie listy API nevracia.
Parametry
| Název | Kde | Typ | Povinné | Popis |
|---|---|---|---|---|
externalSource | query | string | ne | Systém objednávky, ako pri vystavení. Iba spolu s externalId. |
externalId | query | string | ne | ID objednávky v systéme. Iba spolu s externalSource. |
type | query | string | ne | Druhy dokladu oddelené čiarkou. |
status | query | string | ne | issued (vystavený) alebo cancelled (stornovaný), oddelené čiarkou. Predvolene oba. |
paymentStatus | query | string | ne | unpaid, partially_paid, paid, overdue, oddelené čiarkou. |
partnerId | query | string (uuid) | ne | Iba doklady partnera z adresára. |
from | query | string (date) | ne | Dátum vystavenia od (vrátane). |
to | query | string (date) | ne | Dátum vystavenia do (vrátane). |
q | query | string | ne | Hľadanie v čísle dokladu, mene a IČO odberateľa. |
cursor | query | string | ne | meta.nextCursor predchádzajúcej stránky. |
limit | query | integer | ne | Počet záznamov na stránku. |
Příklad požadavku
curl -s "https://api.renly.sk/api/v1/finance/external/documents" \
-H "Authorization: Bearer $RENLY_FINANCE_KEY"Odpovědi
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
{
"error": {
"code": "finance.document_incomplete",
"message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
"details": {
"field": "buyer.city",
"fields": {
"buyer.city": "required"
}
}
}
}finance.api_key_unauthorized).Objekt: Error
{
"error": {
"code": "finance.api_key_unauthorized",
"message": "API kľúč chýba, je neplatný alebo bol zrušený.",
"details": []
}
}finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).Objekt: Error
{
"error": {
"code": "finance.api_key_scope_missing",
"message": "API kľúč nemá oprávnenie na túto operáciu.",
"details": {
"scope": "documents:write"
}
}
}finance.api_rate_limited).Objekt: Error
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
error | object | ano | |
error.code | string | ano | Stabilný kód chyby. |
error.message | string | ano | Text pre človeka, môže sa zmeniť. |
error.details | object | ano | Podrobnosti, napr. fields, scope, existingId. |
Vystaviť faktúru alebo zálohovú faktúru
POST/documents
Vystaví doklad hneď — dostane číslo z radu, PDF a odkaz publicPdfUrl. Obsah je rovnaký ako formulár
dokladu v appke. Neposlané polia dostanú hodnotu nového dokladu v appke: rad pre druh dokladu, vystavenie
dnes, dodanie v deň vystavenia (zálohová faktúra bez dodania), splatnosť podľa partnera alebo nastavenia
spoločnosti, predvolený bankový účet a texty vzhľadu dokladu.
Povinné sú type, lines a odberateľ — buyer (meno, ulica, mesto) alebo partnerId. Neúplný doklad je
400 finance.document_incomplete a nevznikne ani ako koncept.
Parametry
| Název | Kde | Typ | Povinné | Popis |
|---|---|---|---|---|
Idempotency-Key | hlavička | string | ano | Jedinečný kľúč zápisu v spoločnosti, 1–255 viditeľných znakov ASCII. Pozri Idempotencia. |
Tělo požadavku
Objekt: CreateDocument
{
"type": "invoice",
"externalSource": "mojeshop",
"externalId": "2027000123",
"orderNumber": "2027000123",
"paymentMethod": "card",
"pricesIncludeVat": true,
"buyer": {
"name": "Jana Nováková",
"street": "Hlavná 1",
"city": "Bánovce nad Bebravou",
"postalCode": "95701",
"countryCode": "SK",
"email": "jana@example.sk"
},
"lines": [
{
"description": "Pracovný zošit",
"quantity": "2",
"unit": "ks",
"unitPrice": "19.90",
"vatRate": 23
},
{
"description": "Doprava",
"quantity": "1",
"unit": "ks",
"unitPrice": "6.90",
"vatRate": 23
}
],
"payment": {
"paidOn": "2027-01-04",
"method": "card"
},
"send": true
}Příklad požadavku
curl -s -X POST "https://api.renly.sk/api/v1/finance/external/documents" \
-H "Authorization: Bearer $RENLY_FINANCE_KEY" \
-H "Idempotency-Key: mojeshop:2027000123:invoice" \
-H "Content-Type: application/json" \
-d '{
"type": "invoice",
"externalSource": "mojeshop",
"externalId": "2027000123",
"orderNumber": "2027000123",
"paymentMethod": "card",
"pricesIncludeVat": true,
"buyer": {
"name": "Jana Nováková",
"street": "Hlavná 1",
"city": "Bánovce nad Bebravou",
"postalCode": "95701",
"countryCode": "SK",
"email": "jana@example.sk"
},
"lines": [
{
"description": "Pracovný zošit",
"quantity": "2",
"unit": "ks",
"unitPrice": "19.90",
"vatRate": 23
},
{
"description": "Doprava",
"quantity": "1",
"unit": "ks",
"unitPrice": "6.90",
"vatRate": 23
}
],
"payment": {
"paidOn": "2027-01-04",
"method": "card"
},
"send": true
}'Odpovědi
{
"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": []
}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
{
"error": {
"code": "finance.document_incomplete",
"message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
"details": {
"field": "buyer.city",
"fields": {
"buyer.city": "required"
}
}
}
}finance.api_key_unauthorized).Objekt: Error
{
"error": {
"code": "finance.api_key_unauthorized",
"message": "API kľúč chýba, je neplatný alebo bol zrušený.",
"details": []
}
}finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).Objekt: Error
{
"error": {
"code": "finance.api_key_scope_missing",
"message": "API kľúč nemá oprávnenie na túto operáciu.",
"details": {
"scope": "documents:write"
}
}
}Objekt: Error
{
"error": {
"code": "finance.idempotency_key_reused",
"message": "Tento Idempotency-Key už bol použitý pre inú požiadavku.",
"details": []
}
}finance.api_rate_limited).Objekt: Error
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
error | object | ano | |
error.code | string | ano | Stabilný kód chyby. |
error.message | string | ano | Text pre človeka, môže sa zmeniť. |
error.details | object | ano | Podrobnosti, napr. fields, scope, existingId. |
Detail dokladu
GET/documents/{documentId}
Parametry
| Název | Kde | Typ | Povinné | Popis |
|---|---|---|---|---|
documentId | cesta | string (uuid) | ano |
Příklad požadavku
curl -s "https://api.renly.sk/api/v1/finance/external/documents/${DOCUMENT_ID}" \
-H "Authorization: Bearer $RENLY_FINANCE_KEY"Odpovědi
finance.api_key_unauthorized).Objekt: Error
{
"error": {
"code": "finance.api_key_unauthorized",
"message": "API kľúč chýba, je neplatný alebo bol zrušený.",
"details": []
}
}finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).Objekt: Error
{
"error": {
"code": "finance.api_key_scope_missing",
"message": "API kľúč nemá oprávnenie na túto operáciu.",
"details": {
"scope": "documents:write"
}
}
}Objekt: Error
{
"error": {
"code": "finance.document_not_found",
"message": "Doklad sa nenašiel.",
"details": []
}
}finance.api_rate_limited).Objekt: Error
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
error | object | ano | |
error.code | string | ano | Stabilný kód chyby. |
error.message | string | ano | Text pre človeka, môže sa zmeniť. |
error.details | object | ano | Podrobnosti, napr. fields, scope, existingId. |
PDF dokladu
GET/documents/{documentId}/pdf
PDF so vzhľadom dokladu spoločnosti. S download=1 ako príloha na stiahnutie.
Parametry
| Název | Kde | Typ | Povinné | Popis |
|---|---|---|---|---|
documentId | cesta | string (uuid) | ano | |
download | query | string | ne | 1 = hlavička na stiahnutie súboru. |
Příklad požadavku
curl -s "https://api.renly.sk/api/v1/finance/external/documents/${DOCUMENT_ID}/pdf" \
-H "Authorization: Bearer $RENLY_FINANCE_KEY" \
-o get-document-pdf.pdfOdpovědi
application/pdf string (binary)
finance.api_key_unauthorized).Objekt: Error
{
"error": {
"code": "finance.api_key_unauthorized",
"message": "API kľúč chýba, je neplatný alebo bol zrušený.",
"details": []
}
}finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).Objekt: Error
{
"error": {
"code": "finance.api_key_scope_missing",
"message": "API kľúč nemá oprávnenie na túto operáciu.",
"details": {
"scope": "documents:write"
}
}
}Objekt: Error
{
"error": {
"code": "finance.document_not_found",
"message": "Doklad sa nenašiel.",
"details": []
}
}finance.api_rate_limited).Objekt: Error
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
error | object | ano | |
error.code | string | ano | Stabilný kód chyby. |
error.message | string | ano | Text pre človeka, môže sa zmeniť. |
error.details | object | ano | Podrobnosti, napr. fields, scope, existingId. |
Vyúčtovať zálohovú faktúru
POST/documents/{documentId}/final-invoice
Vystaví faktúru, ktorá vyúčtuje uhradenú zálohovú faktúru (odpočíta zálohu).
Parametry
| Název | Kde | Typ | Povinné | Popis |
|---|---|---|---|---|
documentId | cesta | string (uuid) | ano | |
Idempotency-Key | hlavička | string | ano | Jedinečný kľúč zápisu v spoločnosti, 1–255 viditeľných znakov ASCII. Pozri Idempotencia. |
Tělo požadavku
{
"send": true
}| Pole | Typ | Povinné | Popis |
|---|---|---|---|
send | SendOption | ne | true = e-mail s predvoleným textom, objekt = vlastní príjemcovia či text, false alebo nič = neposlať. |
Příklad požadavku
curl -s -X POST "https://api.renly.sk/api/v1/finance/external/documents/${DOCUMENT_ID}/final-invoice" \
-H "Authorization: Bearer $RENLY_FINANCE_KEY" \
-H "Idempotency-Key: mojeshop:2027000123:invoice" \
-H "Content-Type: application/json" \
-d '{
"send": true
}'Odpovědi
{
"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": []
}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
{
"error": {
"code": "finance.document_incomplete",
"message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
"details": {
"field": "buyer.city",
"fields": {
"buyer.city": "required"
}
}
}
}finance.api_key_unauthorized).Objekt: Error
{
"error": {
"code": "finance.api_key_unauthorized",
"message": "API kľúč chýba, je neplatný alebo bol zrušený.",
"details": []
}
}finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).Objekt: Error
{
"error": {
"code": "finance.api_key_scope_missing",
"message": "API kľúč nemá oprávnenie na túto operáciu.",
"details": {
"scope": "documents:write"
}
}
}Objekt: Error
{
"error": {
"code": "finance.document_not_found",
"message": "Doklad sa nenašiel.",
"details": []
}
}Objekt: Error
{
"error": {
"code": "finance.idempotency_key_reused",
"message": "Tento Idempotency-Key už bol použitý pre inú požiadavku.",
"details": []
}
}finance.api_rate_limited).Objekt: Error
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
error | object | ano | |
error.code | string | ano | Stabilný kód chyby. |
error.message | string | ano | Text pre človeka, môže sa zmeniť. |
error.details | object | ano | Podrobnosti, napr. fields, scope, existingId. |
Dobropis faktúry (celej alebo čiastočný)
POST/documents/{documentId}/credit-note
Vystaví dobropis k faktúre: bez lines a amount celej faktúry, s lines vybraných položiek a vráteného
množstva, s amount sumy s DPH rozdelenej po sadzbách. Najviac jedno z lines a amount. Súčet dobropisov
nesmie prekročiť faktúru spolu, v sadzbe DPH ani v množstve položky (409).
Parametry
| Název | Kde | Typ | Povinné | Popis |
|---|---|---|---|---|
documentId | cesta | string (uuid) | ano | |
Idempotency-Key | hlavička | string | ano | Jedinečný kľúč zápisu v spoločnosti, 1–255 viditeľných znakov ASCII. Pozri Idempotencia. |
Tělo požadavku
{
"reason": "Reklamácia 2027000123-R1",
"amount": "10.00",
"description": "Zľava – reklamácia",
"send": true
}| Pole | Typ | Povinné | Popis |
|---|---|---|---|
reason | string | ano | Dôvod opravy, je na PDF dobropisu. |
lines | object[] | ne | Vybrané položky faktúry a vrátené množstvo (kladné, najviac zostatok položky). |
lines[].lineId | string (uuid) | ano | lines[].id faktúry. |
lines[].quantity | Decimal | ano | |
amount | Money | ne | Suma dobropisu s DPH namiesto položiek. |
description | string | ne | Názov položky pri amount; predvolene „Zľava k faktúre …“. |
send | SendOption | ne | true = e-mail s predvoleným textom, objekt = vlastní príjemcovia či text, false alebo nič = neposlať. |
Příklad požadavku
curl -s -X POST "https://api.renly.sk/api/v1/finance/external/documents/${DOCUMENT_ID}/credit-note" \
-H "Authorization: Bearer $RENLY_FINANCE_KEY" \
-H "Idempotency-Key: mojeshop:2027000123:invoice" \
-H "Content-Type: application/json" \
-d '{
"reason": "Reklamácia 2027000123-R1",
"amount": "10.00",
"description": "Zľava – reklamácia",
"send": true
}'Odpovědi
{
"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": []
}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
{
"error": {
"code": "finance.document_incomplete",
"message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
"details": {
"field": "buyer.city",
"fields": {
"buyer.city": "required"
}
}
}
}finance.api_key_unauthorized).Objekt: Error
{
"error": {
"code": "finance.api_key_unauthorized",
"message": "API kľúč chýba, je neplatný alebo bol zrušený.",
"details": []
}
}finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).Objekt: Error
{
"error": {
"code": "finance.api_key_scope_missing",
"message": "API kľúč nemá oprávnenie na túto operáciu.",
"details": {
"scope": "documents:write"
}
}
}Objekt: Error
{
"error": {
"code": "finance.document_not_found",
"message": "Doklad sa nenašiel.",
"details": []
}
}Objekt: Error
{
"error": {
"code": "finance.idempotency_key_reused",
"message": "Tento Idempotency-Key už bol použitý pre inú požiadavku.",
"details": []
}
}finance.api_rate_limited).Objekt: Error
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
error | object | ano | |
error.code | string | ano | Stabilný kód chyby. |
error.message | string | ano | Text pre človeka, môže sa zmeniť. |
error.details | object | ano | Podrobnosti, napr. fields, scope, existingId. |
Stornovať zálohovú faktúru
POST/documents/{documentId}/cancel
Stornuje zálohovú faktúru bez úhrad. Faktúra sa nestornuje — opravuje sa dobropisom.
Parametry
| Název | Kde | Typ | Povinné | Popis |
|---|---|---|---|---|
documentId | cesta | string (uuid) | ano | |
Idempotency-Key | hlavička | string | ano | Jedinečný kľúč zápisu v spoločnosti, 1–255 viditeľných znakov ASCII. Pozri Idempotencia. |
Tělo požadavku
{
"reason": "Objednávka zrušená zákazníkom"
}| Pole | Typ | Povinné | Popis |
|---|---|---|---|
reason | string | ano |
Příklad požadavku
curl -s -X POST "https://api.renly.sk/api/v1/finance/external/documents/${DOCUMENT_ID}/cancel" \
-H "Authorization: Bearer $RENLY_FINANCE_KEY" \
-H "Idempotency-Key: mojeshop:2027000123:invoice" \
-H "Content-Type: application/json" \
-d '{
"reason": "Objednávka zrušená zákazníkom"
}'Odpovědi
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
{
"error": {
"code": "finance.document_incomplete",
"message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
"details": {
"field": "buyer.city",
"fields": {
"buyer.city": "required"
}
}
}
}finance.api_key_unauthorized).Objekt: Error
{
"error": {
"code": "finance.api_key_unauthorized",
"message": "API kľúč chýba, je neplatný alebo bol zrušený.",
"details": []
}
}finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).Objekt: Error
{
"error": {
"code": "finance.api_key_scope_missing",
"message": "API kľúč nemá oprávnenie na túto operáciu.",
"details": {
"scope": "documents:write"
}
}
}Objekt: Error
{
"error": {
"code": "finance.document_not_found",
"message": "Doklad sa nenašiel.",
"details": []
}
}Objekt: Error
{
"error": {
"code": "finance.idempotency_key_reused",
"message": "Tento Idempotency-Key už bol použitý pre inú požiadavku.",
"details": []
}
}finance.api_rate_limited).Objekt: Error
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
error | object | ano | |
error.code | string | ano | Stabilný kód chyby. |
error.message | string | ano | Text pre človeka, môže sa zmeniť. |
error.details | object | ano | Podrobnosti, napr. fields, scope, existingId. |
Úhrady a odoslanie
Zápis úhrady a odoslanie dokladu e-mailom.
Zapísať úhradu
POST/documents/{documentId}/payments
Zapíše úhradu faktúry alebo zálohovej faktúry. Bez amount uhradí celý zostatok. Úplná úhrada pošle
zákazníkovi poďakovanie, ak ho má spoločnosť zapnuté, a webhook document.paid.
Parametry
| Název | Kde | Typ | Povinné | Popis |
|---|---|---|---|---|
documentId | cesta | string (uuid) | ano | |
Idempotency-Key | hlavička | string | ano | Jedinečný kľúč zápisu v spoločnosti, 1–255 viditeľných znakov ASCII. Pozri Idempotencia. |
Tělo požadavku
Objekt: PaymentInput
{
"paidOn": "2027-01-06",
"method": "bank_transfer"
}Příklad požadavku
curl -s -X POST "https://api.renly.sk/api/v1/finance/external/documents/${DOCUMENT_ID}/payments" \
-H "Authorization: Bearer $RENLY_FINANCE_KEY" \
-H "Idempotency-Key: mojeshop:2027000123:invoice" \
-H "Content-Type: application/json" \
-d '{
"paidOn": "2027-01-06",
"method": "bank_transfer"
}'Odpovědi
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
{
"error": {
"code": "finance.document_incomplete",
"message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
"details": {
"field": "buyer.city",
"fields": {
"buyer.city": "required"
}
}
}
}finance.api_key_unauthorized).Objekt: Error
{
"error": {
"code": "finance.api_key_unauthorized",
"message": "API kľúč chýba, je neplatný alebo bol zrušený.",
"details": []
}
}finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).Objekt: Error
{
"error": {
"code": "finance.api_key_scope_missing",
"message": "API kľúč nemá oprávnenie na túto operáciu.",
"details": {
"scope": "documents:write"
}
}
}Objekt: Error
{
"error": {
"code": "finance.document_not_found",
"message": "Doklad sa nenašiel.",
"details": []
}
}Objekt: Error
{
"error": {
"code": "finance.idempotency_key_reused",
"message": "Tento Idempotency-Key už bol použitý pre inú požiadavku.",
"details": []
}
}finance.api_rate_limited).Objekt: Error
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
error | object | ano | |
error.code | string | ano | Stabilný kód chyby. |
error.message | string | ano | Text pre človeka, môže sa zmeniť. |
error.details | object | ano | Podrobnosti, napr. fields, scope, existingId. |
Poslať doklad e-mailom
POST/documents/{documentId}/send
Pošle vystavený doklad s PDF e-mailom. Bez tela ({}) ide na predvolených príjemcov s predvoleným
predmetom a textom v jazyku dokladu. Každé odoslanie potrebuje nový Idempotency-Key.
Parametry
| Název | Kde | Typ | Povinné | Popis |
|---|---|---|---|---|
documentId | cesta | string (uuid) | ano | |
Idempotency-Key | hlavička | string | ano | Jedinečný kľúč zápisu v spoločnosti, 1–255 viditeľných znakov ASCII. Pozri Idempotencia. |
Tělo požadavku
Objekt: SendInput
{
"to": [
"uctaren@firma.sk"
],
"subject": "Faktúra 2027001",
"message": "Dobrý deň, v prílohe posielame faktúru."
}Příklad požadavku
curl -s -X POST "https://api.renly.sk/api/v1/finance/external/documents/${DOCUMENT_ID}/send" \
-H "Authorization: Bearer $RENLY_FINANCE_KEY" \
-H "Idempotency-Key: mojeshop:2027000123:invoice" \
-H "Content-Type: application/json" \
-d '{
"to": [
"uctaren@firma.sk"
],
"subject": "Faktúra 2027001",
"message": "Dobrý deň, v prílohe posielame faktúru."
}'Odpovědi
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
{
"error": {
"code": "finance.document_incomplete",
"message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
"details": {
"field": "buyer.city",
"fields": {
"buyer.city": "required"
}
}
}
}finance.api_key_unauthorized).Objekt: Error
{
"error": {
"code": "finance.api_key_unauthorized",
"message": "API kľúč chýba, je neplatný alebo bol zrušený.",
"details": []
}
}finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).Objekt: Error
{
"error": {
"code": "finance.api_key_scope_missing",
"message": "API kľúč nemá oprávnenie na túto operáciu.",
"details": {
"scope": "documents:write"
}
}
}Objekt: Error
{
"error": {
"code": "finance.document_not_found",
"message": "Doklad sa nenašiel.",
"details": []
}
}Objekt: Error
{
"error": {
"code": "finance.idempotency_key_reused",
"message": "Tento Idempotency-Key už bol použitý pre inú požiadavku.",
"details": []
}
}finance.api_rate_limited).Objekt: Error
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
error | object | ano | |
error.code | string | ano | Stabilný kód chyby. |
error.message | string | ano | Text pre človeka, môže sa zmeniť. |
error.details | object | ano | Podrobnosti, napr. fields, scope, existingId. |
Partneri
Adresár odberateľov a dodávateľov.
Zoznam partnerov
GET/partners
Partneri z adresára spoločnosti podľa názvu (abecedne), bez archivovaných.
Parametry
| Název | Kde | Typ | Povinné | Popis |
|---|---|---|---|---|
q | query | string | ne | Hľadanie v názve, IČO a kontaktných osobách. |
role | query | string | ne | Iba odberatelia alebo iba dodávatelia. |
cursor | query | string | ne | meta.nextCursor predchádzajúcej stránky. |
limit | query | integer | ne | Počet záznamov na stránku. |
Příklad požadavku
curl -s "https://api.renly.sk/api/v1/finance/external/partners" \
-H "Authorization: Bearer $RENLY_FINANCE_KEY"Odpovědi
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
{
"error": {
"code": "finance.document_incomplete",
"message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
"details": {
"field": "buyer.city",
"fields": {
"buyer.city": "required"
}
}
}
}finance.api_key_unauthorized).Objekt: Error
{
"error": {
"code": "finance.api_key_unauthorized",
"message": "API kľúč chýba, je neplatný alebo bol zrušený.",
"details": []
}
}finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).Objekt: Error
{
"error": {
"code": "finance.api_key_scope_missing",
"message": "API kľúč nemá oprávnenie na túto operáciu.",
"details": {
"scope": "documents:write"
}
}
}finance.api_rate_limited).Objekt: Error
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
error | object | ano | |
error.code | string | ano | Stabilný kód chyby. |
error.message | string | ano | Text pre človeka, môže sa zmeniť. |
error.details | object | ano | Podrobnosti, napr. fields, scope, existingId. |
Založiť partnera
POST/partners
Založí partnera v adresári. IČO je v spoločnosti jedinečné — partner s existujúcim IČO je
409 finance.partner_duplicate s details.existingId. IČ DPH sa overí v systéme VIES (vatVerifiedAt).
Parametry
| Název | Kde | Typ | Povinné | Popis |
|---|---|---|---|---|
Idempotency-Key | hlavička | string | ano | Jedinečný kľúč zápisu v spoločnosti, 1–255 viditeľných znakov ASCII. Pozri Idempotencia. |
Tělo požadavku
Objekt: PartnerInput
{
"name": "Hotel Tatra s. r. o.",
"ico": "36512345",
"dic": "2020123456",
"icDph": "SK2020123456",
"street": "Hlavná 1",
"city": "Poprad",
"postalCode": "05801",
"countryCode": "SK",
"email": "faktury@hoteltatra.sk",
"isCustomer": true,
"defaultDueDays": 30,
"contacts": [
{
"name": "Eva Kováčová",
"email": "uctaren@hoteltatra.sk",
"roles": [
"invoices",
"reminders"
],
"isPrimary": true
}
]
}Příklad požadavku
curl -s -X POST "https://api.renly.sk/api/v1/finance/external/partners" \
-H "Authorization: Bearer $RENLY_FINANCE_KEY" \
-H "Idempotency-Key: mojeshop:2027000123:invoice" \
-H "Content-Type: application/json" \
-d '{
"name": "Hotel Tatra s. r. o.",
"ico": "36512345",
"dic": "2020123456",
"icDph": "SK2020123456",
"street": "Hlavná 1",
"city": "Poprad",
"postalCode": "05801",
"countryCode": "SK",
"email": "faktury@hoteltatra.sk",
"isCustomer": true,
"defaultDueDays": 30,
"contacts": [
{
"name": "Eva Kováčová",
"email": "uctaren@hoteltatra.sk",
"roles": [
"invoices",
"reminders"
],
"isPrimary": true
}
]
}'Odpovědi
{
"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": []
}| Pole | Typ | Povinné | Popis |
|---|---|---|---|
data | Partner | ano |
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
{
"error": {
"code": "finance.document_incomplete",
"message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
"details": {
"field": "buyer.city",
"fields": {
"buyer.city": "required"
}
}
}
}finance.api_key_unauthorized).Objekt: Error
{
"error": {
"code": "finance.api_key_unauthorized",
"message": "API kľúč chýba, je neplatný alebo bol zrušený.",
"details": []
}
}finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).Objekt: Error
{
"error": {
"code": "finance.api_key_scope_missing",
"message": "API kľúč nemá oprávnenie na túto operáciu.",
"details": {
"scope": "documents:write"
}
}
}Objekt: Error
{
"error": {
"code": "finance.idempotency_key_reused",
"message": "Tento Idempotency-Key už bol použitý pre inú požiadavku.",
"details": []
}
}finance.api_rate_limited).Objekt: Error
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
error | object | ano | |
error.code | string | ano | Stabilný kód chyby. |
error.message | string | ano | Text pre človeka, môže sa zmeniť. |
error.details | object | ano | Podrobnosti, napr. fields, scope, existingId. |
Detail partnera
GET/partners/{partnerId}
Parametry
| Název | Kde | Typ | Povinné | Popis |
|---|---|---|---|---|
partnerId | cesta | string (uuid) | ano |
Příklad požadavku
curl -s "https://api.renly.sk/api/v1/finance/external/partners/${PARTNER_ID}" \
-H "Authorization: Bearer $RENLY_FINANCE_KEY"Odpovědi
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
data | Partner | ano |
finance.api_key_unauthorized).Objekt: Error
{
"error": {
"code": "finance.api_key_unauthorized",
"message": "API kľúč chýba, je neplatný alebo bol zrušený.",
"details": []
}
}finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).Objekt: Error
{
"error": {
"code": "finance.api_key_scope_missing",
"message": "API kľúč nemá oprávnenie na túto operáciu.",
"details": {
"scope": "documents:write"
}
}
}Objekt: Error
{
"error": {
"code": "finance.document_not_found",
"message": "Doklad sa nenašiel.",
"details": []
}
}finance.api_rate_limited).Objekt: Error
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
error | object | ano | |
error.code | string | ano | Stabilný kód chyby. |
error.message | string | ano | Text pre človeka, môže sa zmeniť. |
error.details | object | ano | Podrobnosti, napr. fields, scope, existingId. |
Upraviť partnera
PATCH/partners/{partnerId}
Zmení iba poslané polia. contacts nahradí celý zoznam kontaktných osôb — existujúcu osobu ponecháte
poslaním jej id. Vystavené doklady sa nemenia.
Parametry
| Název | Kde | Typ | Povinné | Popis |
|---|---|---|---|---|
partnerId | cesta | string (uuid) | ano |
Tělo požadavku
Objekt: PartnerInput
{
"street": "Nová 5",
"city": "Poprad",
"postalCode": "05801"
}Příklad požadavku
curl -s -X PATCH "https://api.renly.sk/api/v1/finance/external/partners/${PARTNER_ID}" \
-H "Authorization: Bearer $RENLY_FINANCE_KEY" \
-H "Content-Type: application/json" \
-d '{
"street": "Nová 5",
"city": "Poprad",
"postalCode": "05801"
}'Odpovědi
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
data | Partner | ano |
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
{
"error": {
"code": "finance.document_incomplete",
"message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
"details": {
"field": "buyer.city",
"fields": {
"buyer.city": "required"
}
}
}
}finance.api_key_unauthorized).Objekt: Error
{
"error": {
"code": "finance.api_key_unauthorized",
"message": "API kľúč chýba, je neplatný alebo bol zrušený.",
"details": []
}
}finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).Objekt: Error
{
"error": {
"code": "finance.api_key_scope_missing",
"message": "API kľúč nemá oprávnenie na túto operáciu.",
"details": {
"scope": "documents:write"
}
}
}Objekt: Error
{
"error": {
"code": "finance.document_not_found",
"message": "Doklad sa nenašiel.",
"details": []
}
}Objekt: Error
{
"error": {
"code": "finance.idempotency_key_reused",
"message": "Tento Idempotency-Key už bol použitý pre inú požiadavku.",
"details": []
}
}finance.api_rate_limited).Objekt: Error
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
error | object | ano | |
error.code | string | ano | Stabilný kód chyby. |
error.message | string | ano | Text pre človeka, môže sa zmeniť. |
error.details | object | ano | 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
Položky cenníka spoločnosti podľa názvu (abecedne), bez archivovaných.
Parametry
| Název | Kde | Typ | Povinné | Popis |
|---|---|---|---|---|
q | query | string | ne | Hľadanie v názve a kóde položky. |
cursor | query | string | ne | meta.nextCursor predchádzajúcej stránky. |
limit | query | integer | ne | Počet záznamov na stránku. |
Příklad požadavku
curl -s "https://api.renly.sk/api/v1/finance/external/price-list-items" \
-H "Authorization: Bearer $RENLY_FINANCE_KEY"Odpovědi
{
"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
}
}| Pole | Typ | Povinné | Popis |
|---|---|---|---|
data | PriceListItem[] | ano | |
meta | ListMeta | ano |
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
{
"error": {
"code": "finance.document_incomplete",
"message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
"details": {
"field": "buyer.city",
"fields": {
"buyer.city": "required"
}
}
}
}finance.api_key_unauthorized).Objekt: Error
{
"error": {
"code": "finance.api_key_unauthorized",
"message": "API kľúč chýba, je neplatný alebo bol zrušený.",
"details": []
}
}finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).Objekt: Error
{
"error": {
"code": "finance.api_key_scope_missing",
"message": "API kľúč nemá oprávnenie na túto operáciu.",
"details": {
"scope": "documents:write"
}
}
}finance.api_rate_limited).Objekt: Error
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
error | object | ano | |
error.code | string | ano | Stabilný kód chyby. |
error.message | string | ano | Text pre človeka, môže sa zmeniť. |
error.details | object | ano | Podrobnosti, napr. fields, scope, existingId. |
Položka cenníka
GET/price-list-items/{itemId}
Parametry
| Název | Kde | Typ | Povinné | Popis |
|---|---|---|---|---|
itemId | cesta | string (uuid) | ano |
Příklad požadavku
curl -s "https://api.renly.sk/api/v1/finance/external/price-list-items/${ITEM_ID}" \
-H "Authorization: Bearer $RENLY_FINANCE_KEY"Odpovědi
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
data | PriceListItem | ano |
finance.api_key_unauthorized).Objekt: Error
{
"error": {
"code": "finance.api_key_unauthorized",
"message": "API kľúč chýba, je neplatný alebo bol zrušený.",
"details": []
}
}finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).Objekt: Error
{
"error": {
"code": "finance.api_key_scope_missing",
"message": "API kľúč nemá oprávnenie na túto operáciu.",
"details": {
"scope": "documents:write"
}
}
}Objekt: Error
{
"error": {
"code": "finance.document_not_found",
"message": "Doklad sa nenašiel.",
"details": []
}
}finance.api_rate_limited).Objekt: Error
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
error | object | ano | |
error.code | string | ano | Stabilný kód chyby. |
error.message | string | ano | Text pre človeka, môže sa zmeniť. |
error.details | object | ano | Podrobnosti, napr. fields, scope, existingId. |
Číselné rady
GET/number-series
Rady účtovných dokladov. id radu pošlite ako seriesId pri vystavení, ak nechcete predvolený rad.
Příklad požadavku
curl -s "https://api.renly.sk/api/v1/finance/external/number-series" \
-H "Authorization: Bearer $RENLY_FINANCE_KEY"Odpovědi
{
"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": []
}| Pole | Typ | Povinné | Popis |
|---|---|---|---|
data | NumberSeries[] | ano |
finance.api_key_unauthorized).Objekt: Error
{
"error": {
"code": "finance.api_key_unauthorized",
"message": "API kľúč chýba, je neplatný alebo bol zrušený.",
"details": []
}
}finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).Objekt: Error
{
"error": {
"code": "finance.api_key_scope_missing",
"message": "API kľúč nemá oprávnenie na túto operáciu.",
"details": {
"scope": "documents:write"
}
}
}finance.api_rate_limited).Objekt: Error
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
error | object | ano | |
error.code | string | ano | Stabilný kód chyby. |
error.message | string | ano | Text pre človeka, môže sa zmeniť. |
error.details | object | ano | Podrobnosti, napr. fields, scope, existingId. |
Bankové účty
GET/bank-accounts
Účty spoločnosti pre platbu prevodom. id účtu pošlite ako bankAccountId, ak nechcete predvolený.
Příklad požadavku
curl -s "https://api.renly.sk/api/v1/finance/external/bank-accounts" \
-H "Authorization: Bearer $RENLY_FINANCE_KEY"Odpovědi
{
"data": [
{
"id": "019a5f6e-6666-7a2b-8c3d-4e5f6a7b8c9d",
"bankName": "Slovenská sporiteľňa",
"iban": "SK3109000000000123456789",
"bic": "GIBASKBX",
"currency": "EUR",
"isDefault": true
}
],
"meta": []
}| Pole | Typ | Povinné | Popis |
|---|---|---|---|
data | BankAccount[] | ano |
finance.api_key_unauthorized).Objekt: Error
{
"error": {
"code": "finance.api_key_unauthorized",
"message": "API kľúč chýba, je neplatný alebo bol zrušený.",
"details": []
}
}finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).Objekt: Error
{
"error": {
"code": "finance.api_key_scope_missing",
"message": "API kľúč nemá oprávnenie na túto operáciu.",
"details": {
"scope": "documents:write"
}
}
}finance.api_rate_limited).Objekt: Error
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
error | object | ano | |
error.code | string | ano | Stabilný kód chyby. |
error.message | string | ano | Text pre človeka, môže sa zmeniť. |
error.details | object | ano | Podrobnosti, napr. fields, scope, existingId. |
Webhooky
Správy o zmenách dokladov, ktoré sa stali vo Financiách.
Zoznam webhookov
GET/webhooks
Příklad požadavku
curl -s "https://api.renly.sk/api/v1/finance/external/webhooks" \
-H "Authorization: Bearer $RENLY_FINANCE_KEY"Odpovědi
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
data | Webhook[] | ano | |
meta | object | ano | |
meta.limit | integer | ne |
finance.api_key_unauthorized).Objekt: Error
{
"error": {
"code": "finance.api_key_unauthorized",
"message": "API kľúč chýba, je neplatný alebo bol zrušený.",
"details": []
}
}finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).Objekt: Error
{
"error": {
"code": "finance.api_key_scope_missing",
"message": "API kľúč nemá oprávnenie na túto operáciu.",
"details": {
"scope": "documents:write"
}
}
}finance.api_rate_limited).Objekt: Error
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
error | object | ano | |
error.code | string | ano | Stabilný kód chyby. |
error.message | string | ano | Text pre človeka, môže sa zmeniť. |
error.details | object | ano | Podrobnosti, napr. fields, scope, existingId. |
Zaregistrovať webhook
POST/webhooks
Zaregistruje HTTPS adresu a udalosti. Odpoveď obsahuje secret na overenie podpisu — iba raz, uložte ho.
Najviac 5 adries, tá istá adresa dvakrát je 409 finance.webhook_duplicate.
Tělo požadavku
{
"url": "https://mojeshop.sk/renly-webhook",
"events": [
"document.paid",
"document.issued"
]
}| Pole | Typ | Povinné | Popis |
|---|---|---|---|
url | string (uri) | ano | HTTPS adresa bez mena a hesla. |
events | WebhookEvent[] | ano |
Příklad požadavku
curl -s -X POST "https://api.renly.sk/api/v1/finance/external/webhooks" \
-H "Authorization: Bearer $RENLY_FINANCE_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://mojeshop.sk/renly-webhook",
"events": [
"document.paid",
"document.issued"
]
}'Odpovědi
secret.| Pole | Typ | Povinné | Popis |
|---|---|---|---|
data | Webhook & object | ano | |
data.secret | string | ano | Tajomstvo podpisu rfw_…, iba v tejto odpovedi. |
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
{
"error": {
"code": "finance.document_incomplete",
"message": "Doklad sa nedá vystaviť — doplňte chýbajúce údaje.",
"details": {
"field": "buyer.city",
"fields": {
"buyer.city": "required"
}
}
}
}finance.api_key_unauthorized).Objekt: Error
{
"error": {
"code": "finance.api_key_unauthorized",
"message": "API kľúč chýba, je neplatný alebo bol zrušený.",
"details": []
}
}finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).Objekt: Error
{
"error": {
"code": "finance.api_key_scope_missing",
"message": "API kľúč nemá oprávnenie na túto operáciu.",
"details": {
"scope": "documents:write"
}
}
}Objekt: Error
{
"error": {
"code": "finance.idempotency_key_reused",
"message": "Tento Idempotency-Key už bol použitý pre inú požiadavku.",
"details": []
}
}finance.api_rate_limited).Objekt: Error
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
error | object | ano | |
error.code | string | ano | Stabilný kód chyby. |
error.message | string | ano | Text pre človeka, môže sa zmeniť. |
error.details | object | ano | Podrobnosti, napr. fields, scope, existingId. |
Zmazať webhook
DELETE/webhooks/{webhookId}
Adresa sa vypne a čakajúce doručenia sa už nepošlú.
Parametry
| Název | Kde | Typ | Povinné | Popis |
|---|---|---|---|---|
webhookId | cesta | string (uuid) | ano |
Příklad požadavku
curl -s -X DELETE "https://api.renly.sk/api/v1/finance/external/webhooks/${WEBHOOK_ID}" \
-H "Authorization: Bearer $RENLY_FINANCE_KEY"Odpovědi
finance.api_key_unauthorized).Objekt: Error
{
"error": {
"code": "finance.api_key_unauthorized",
"message": "API kľúč chýba, je neplatný alebo bol zrušený.",
"details": []
}
}finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).Objekt: Error
{
"error": {
"code": "finance.api_key_scope_missing",
"message": "API kľúč nemá oprávnenie na túto operáciu.",
"details": {
"scope": "documents:write"
}
}
}Objekt: Error
{
"error": {
"code": "finance.document_not_found",
"message": "Doklad sa nenašiel.",
"details": []
}
}finance.api_rate_limited).Objekt: Error
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
error | object | ano | |
error.code | string | ano | Stabilný kód chyby. |
error.message | string | ano | Text pre človeka, môže sa zmeniť. |
error.details | object | ano | Podrobnosti, napr. fields, scope, existingId. |
História doručení
GET/webhooks/{webhookId}/deliveries
Posledných 50 doručení od najnovšieho — na hľadanie, prečo webhook neprišiel.
Parametry
| Název | Kde | Typ | Povinné | Popis |
|---|---|---|---|---|
webhookId | cesta | string (uuid) | ano |
Příklad požadavku
curl -s "https://api.renly.sk/api/v1/finance/external/webhooks/${WEBHOOK_ID}/deliveries" \
-H "Authorization: Bearer $RENLY_FINANCE_KEY"Odpovědi
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
data | WebhookDelivery[] | ano |
finance.api_key_unauthorized).Objekt: Error
{
"error": {
"code": "finance.api_key_unauthorized",
"message": "API kľúč chýba, je neplatný alebo bol zrušený.",
"details": []
}
}finance.api_key_scope_missing s details.scope) alebo firma nemá Financie (finance.api_not_available).Objekt: Error
{
"error": {
"code": "finance.api_key_scope_missing",
"message": "API kľúč nemá oprávnenie na túto operáciu.",
"details": {
"scope": "documents:write"
}
}
}Objekt: Error
{
"error": {
"code": "finance.document_not_found",
"message": "Doklad sa nenašiel.",
"details": []
}
}finance.api_rate_limited).Objekt: Error
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
error | object | ano | |
error.code | string | ano | Stabilný kód chyby. |
error.message | string | ano | Text pre človeka, môže sa zmeniť. |
error.details | object | ano | 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
Adresa je v poli publicPdfUrl dokladu — nemusíte ju skladať. Platí, kým je doklad vystavený (storno
zálohovej faktúry ju zruší). Limit 120 stiahnutí za 10 minút na odkaz a IP adresu.
Parametry
| Název | Kde | Typ | Povinné | Popis |
|---|---|---|---|---|
token | cesta | string | ano | |
download | query | string | ne |
Příklad požadavku
curl -s "https://api.renly.sk/api/v1/public/finance/documents/${TOKEN}/pdf" \
-o get-public-document-pdf.pdfOdpovědi
application/pdf string (binary)
Objekt: Error
{
"error": {
"code": "finance.document_not_found",
"message": "Doklad sa nenašiel.",
"details": []
}
}Retry-After.Objekty
Error
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
error | object | ano | |
error.code | string | ano | Stabilný kód chyby. |
error.message | string | ano | Text pre človeka, môže sa zmeniť. |
error.details | object | ano | Podrobnosti, napr. fields, scope, existingId. |
ListMeta
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
limit | integer | ano | |
nextCursor | string | null | ano | Kurzor ďalšej stránky, null = posledná stránka. |
WriteMeta
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
sendError | string | ne | Kód chyby, keď doklad vznikol, ale e-mail sa nepodarilo odoslať (napr. finance.document_send_failed). |
Me
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
key | object | ano | |
key.id | string (uuid) | ano | |
key.name | string | ano | |
key.keyPrefix | string | ano | Začiatok kľúča ( rfk_ alebo rfk_test_ a 12 znakov) — podľa neho ho spoznáte vo Financiách. |
key.mode | string | ano | test = testovací kľúč, doklady mimo radu, exportu, e-mailov a e-faktúr. |
key.scopes | Scope[] | ano | |
key.createdByName | string | ne | |
key.createdAt | string (date-time) | ne | |
key.lastUsedAt | string (date-time) | null | ne | |
key.revokedAt | string (date-time) | null | ne | |
key.active | boolean | ano | |
company | object | ano | |
company.id | string (uuid) | ano | |
company.tenantId | string (uuid) | ano | ID firmy v Renly. |
company.name | string | ano | |
company.active | boolean | ano | false = spoločnosť nad limitom balíčka, API iba číta. |
Scope
Typ: string
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
PaymentMethod
Prevod, hotovosť, karta, dobierka, iné. Odpoveď môže obsahovať aj advance (zápočet zálohy pri vyúčtovaní).
Typ: string
Money
Typ: string
Decimal
Typ: string
Party
Odberateľ dokladu.
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
name | string | ne | |
ico | string | ne | IČO (8 číslic). |
dic | string | ne | DIČ. |
icDph | string | ne | IČ DPH s kódom krajiny, napr. SK2020123456. |
street | string | ne | |
city | string | ne | |
postalCode | string | ne | |
countryCode | string | ne | |
email | string (email) | ne | Adresa, na ktorú pôjde doklad pri send. |
LineInput
CreateDocument
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
type | string | ano | credit_note iba k faktúre mimo Renly — s originalDocument, correctionReason a zápornými množstvami. |
originalDocument | object | ne | Dobropis k faktúre vystavenej mimo Renly (napr. v predošlom programe). |
originalDocument.number | string | ano | Číslo pôvodnej faktúry. |
originalDocument.issueDate | string (date) | ano | Dátum vystavenia pôvodnej faktúry. |
correctionReason | string | ne | Dôvod opravy — povinný pri dobropise. |
externalSource | string | ne | Váš systém, napr. mojeshop. Vždy spolu s externalId. |
externalId | string | ne | ID objednávky vo vašom systéme. Nie je jedinečné — dobropis ho prevezme. |
partnerId | string (uuid) | ne | Partner z adresára; doplní odberateľa, splatnosť a jazyk. |
buyer | Party | ne | Odberateľ dokladu. |
lines | LineInput[] | ano | |
number | string | ne | Vlastné číslo mimo radu. Bez neho číslo pridelí rad. |
seriesId | string (uuid) | ne | Rad z GET /number-series; predvolený rad druhu dokladu. |
issueDate | string (date) | ne | |
deliveryDate | string (date) | ne | |
dueDate | string (date) | ne | |
orderNumber | string | ne | Číslo objednávky na PDF. |
variableSymbol | string | ne | Predvolene číslice čísla dokladu. |
constantSymbol | string | ne | |
specificSymbol | string | ne | |
paymentMethod | PaymentMethod | ne | Prevod, hotovosť, karta, dobierka, iné. Odpoveď môže obsahovať aj advance (zápočet zálohy pri vyúčtovaní). |
bankAccountId | string (uuid) | ne | Účet z GET /bank-accounts; predvolený účet spoločnosti. |
currency | string | ne | |
exchangeRate | Decimal | ne | |
language | string | ne | |
vatMode | string | ne | |
vatCountry | string | ne | Štát spotreby pri oss (AT, CZ, DE, HU, PL); predvolene štát odberateľa. |
vatExemptionReason | string | ne | Povinný pri exempt. |
vatExemptionCode | string | null | ne | Kód dôvodu oslobodenia (VATEX) pri exempt pre e-faktúru, napr. VATEX-EU-135-1 pri nájme nehnuteľnosti (§ 38). Nepovinný. |
pricesIncludeVat | boolean | ne | |
discountPercent | Decimal | ne | |
introText | string | ne | Text nad položkami. |
closingText | string | ne | Text pod položkami. |
internalNote | string | ne | Poznámka viditeľná iba vo Financiách. |
payment | PaymentInput | ne | |
send | SendOption | ne | true = e-mail s predvoleným textom, objekt = vlastní príjemcovia či text, false alebo nič = neposlať. |
PaymentInput
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
amount | Money | ne | Bez sumy celý zostatok. |
paidOn | string (date) | ano | |
method | PaymentMethod | ano | Prevod, hotovosť, karta, dobierka, iné. Odpoveď môže obsahovať aj advance (zápočet zálohy pri vyúčtovaní). |
note | string | ne |
SendInput
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
to | array<string (email)> | ne | Príjemcovia; predvolene odberateľ alebo kontaktné osoby partnera. |
cc | array<string (email)> | ne | |
subject | string | ne | |
message | string | ne |
SendOption
true = e-mail s predvoleným textom, objekt = vlastní príjemcovia či text, false alebo nič = neposlať.
Typ: boolean | SendInput
Document
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
id | string (uuid) | ano | |
type | DocumentType | ano | 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). |
status | string | ano | |
paymentStatus | string | null | ano | Stav úhrady faktúry, zálohovej faktúry a ťarchopisu; ostatné null. |
number | string | ano | |
variableSymbol | string | ne | |
orderNumber | string | ne | |
externalSource | string | null | ne | |
externalId | string | null | ne | |
test | boolean | ne | Testovací doklad z testovacieho kľúča — číslo TEST-…, nie je účtovným dokladom. |
issueDate | string (date) | ano | |
deliveryDate | string (date) | null | ne | |
dueDate | string (date) | null | ne | |
currency | string | ano | |
language | string | ne | |
paymentMethod | string | ne | |
vatMode | string | ne | |
vatCountry | string | null | ne | Štát spotreby pri oss. |
pricesIncludeVat | boolean | ne | |
buyer | object | ano | |
buyer.name | string | ano | |
buyer.ico | string | ano | |
buyer.dic | string | ano | |
buyer.icDph | string | ano | |
buyer.street | string | ano | |
buyer.city | string | ano | |
buyer.postalCode | string | ano | |
buyer.countryCode | string | ano | |
buyer.email | string | ano | |
lines | object[] | ano | |
lines[].id | string (uuid) | ne | ID položky — lineId čiastočného dobropisu. |
lines[].kind | string | ano | advance = odpočet zálohy pri vyúčtovaní. |
lines[].description | string | ano | |
lines[].detail | string | ne | |
lines[].quantity | string | ano | |
lines[].unit | string | ne | |
lines[].unitPrice | string | ano | |
lines[].discountPercent | string | ne | |
lines[].vatRate | integer | null | ano | |
lines[].totalWithoutVat | Money | ano | |
lines[].vat | Money | ano | |
lines[].totalWithVat | Money | ano | |
vatRecap | object[] | ne | Rekapitulácia DPH po sadzbách (záväzná pre DPH); bez DPH prázdna. |
vatRecap[].rate | integer | ano | |
vatRecap[].base | Money | ano | |
vatRecap[].vat | Money | ano | |
vatRecap[].total | Money | ano | |
totalWithoutVat | Money | ne | |
totalVat | Money | ne | |
totalWithVat | Money | ano | |
paidAmount | Money | ne | |
remainingAmount | Money | ano | Zostáva uhradiť: suma − úhrady − dobropisy. |
creditedAmount | Money | ne | Faktúra: súčet vystavených dobropisov s DPH (kladný). |
payments | object[] | ano | |
payments[].id | string (uuid) | ano | |
payments[].amount | Money | ano | |
payments[].paidOn | string (date) | ano | |
payments[].method | string | ano | |
relatedDocument | null | object | ne | Dobropis → faktúra, vyúčtovanie → zálohová faktúra. |
relatedDocument.id | string (uuid) | ano | |
relatedDocument.type | DocumentType | ano | 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.number | string | null | ano | |
originalDocument | null | object | ne | Dobropis k faktúre mimo Renly: číslo a dátum pôvodnej faktúry; inak null. |
originalDocument.number | string | ano | |
originalDocument.issueDate | string (date) | null | ano | |
publicPdfUrl | string (uri) | null | ano | PDF bez prihlásenia; null pri doklade vystavenom v appke alebo po storne. |
sentAt | string (date-time) | null | ne | |
issuedAt | string (date-time) | null | ne | |
cancelledAt | string (date-time) | null | ne | |
createdAt | string (date-time) | ne | |
updatedAt | string (date-time) | ne |
PartnerContactInput
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
id | string (uuid) | ne | Existujúca osoba; bez id vznikne nová. |
name | string | ne | |
jobTitle | string | ne | |
email | string (email) | ne | |
phone | string | ne | |
note | string | ne | |
roles | string[] | ne | invoices dostáva doklady, deals ponuky a objednávky, reminders upomienky, copy kópiu. |
isPrimary | boolean | ne |
PartnerInput
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
name | string | ne | Povinné pri založení. |
ico | string | ne | |
dic | string | ne | |
icDph | string | ne | |
registryEntry | string | ne | Zápis v obchodnom registri. |
street | string | ne | |
city | string | ne | |
postalCode | string | ne | |
countryCode | string | ne | |
email | string (email) | ne | |
phone | string | ne | |
isCustomer | boolean | ne | |
isSupplier | boolean | ne | |
defaultDueDays | integer | null | ne | Splatnosť dokladov partnera v dňoch. |
documentLanguage | string | null | ne | |
note | string | ne | |
contacts | PartnerContactInput[] | ne |
Partner
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
id | string (uuid) | ano | |
test | boolean | ano | Testovací partner založený testovacím kľúčom. |
name | string | ano | |
ico | string | ano | |
dic | string | ano | |
icDph | string | ano | |
registryEntry | string | ne | |
street | string | ano | |
city | string | ano | |
postalCode | string | ano | |
countryCode | string | ano | |
email | string | ano | E-mail hlavnej kontaktnej osoby. |
phone | string | ano | |
contacts | object[] | ano | |
contacts[].id | string (uuid) | ano | |
contacts[].name | string | ano | |
contacts[].jobTitle | string | ne | |
contacts[].email | string | ano | |
contacts[].phone | string | ne | |
contacts[].note | string | ne | |
contacts[].roles | string[] | ano | |
contacts[].isPrimary | boolean | ano | |
isCustomer | boolean | ano | |
isSupplier | boolean | ano | |
defaultDueDays | integer | null | ne | |
documentLanguage | string | null | ne | |
note | string | ne | |
vatVerifiedAt | string (date-time) | null | ne | Kedy bolo IČ DPH overené vo VIES. |
createdAt | string (date-time) | ano | |
updatedAt | string (date-time) | ano |
PriceListItem
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
id | string (uuid) | ano | |
name | string | ano | |
detail | string | ano | |
code | string | ano | Vlastný kód položky (môže byť prázdny). |
unit | string | ano | |
unitPrice | Decimal | ano | |
pricesIncludeVat | boolean | ano | true = unitPrice je s DPH. |
vatRate | integer | null | ano | |
updatedAt | string (date-time) | ano |
NumberSeries
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
id | string (uuid) | ano | |
documentType | DocumentType | ano | 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). |
name | string | ano | |
isDefault | boolean | ano | Predvolený rad druhu dokladu. |
nextNumberPreview | string | ano | Číslo, ktoré by rad vydal dnes. |
BankAccount
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
id | string (uuid) | ano | |
bankName | string | ano | |
iban | string | ano | |
bic | string | ano | |
currency | string | ano | |
isDefault | boolean | ano |
WebhookEvent
Typ: string
Webhook
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
id | string (uuid) | ano | |
url | string (uri) | ano | |
test | boolean | ano | Webhook testovacieho kľúča — dostáva iba udalosti testovacích dokladov. |
events | WebhookEvent[] | ano | |
createdAt | string (date-time) | ano | |
lastSuccessAt | string (date-time) | null | ne | |
lastFailureAt | string (date-time) | null | ne | |
consecutiveFailures | integer | ano |
WebhookDelivery
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
id | string (uuid) | ano | Rovnaké ako hlavička X-Renly-Delivery. |
event | WebhookEvent | ano | |
documentId | string (uuid) | ano | |
status | string | ano | |
attempts | integer | ano | |
lastStatusCode | integer | null | ne | |
lastError | string | null | ne | |
lastAttemptAt | string (date-time) | null | ne | |
deliveredAt | string (date-time) | null | ne | |
createdAt | string (date-time) | ano |