Prepojte vporiadku so svojím systémom

Čo API vie

Každá požiadavka prechádza tými istými pravidlami ako aplikácia: číslovanie radov, kontrola sadzieb DPH, limity plánu aj auditný záznam. API je ďalšie vstupné miesto do produktu, nie jeho druhá kópia.

• Faktúry a doklady

  Zoznam s filtrami podľa typu, stavu, klienta, dátumov, štítkov a zmeny, detail, PDF, ISDOC a UBL, vytvorenie, kópia, úprava, vystavenie, odoslanie e-mailom, upomienka, dobropis a storno.

• Platby

  Úhrady dokladu: zoznam, zaevidovanie, uhradenie zvyšnej sumy jedným volaním a zmazanie. Stav dokladu sa prepočíta sám.

• Klienti

  Adresár odberateľov: vyhľadávanie podľa názvu, IČO, DIČ alebo e-mailu, zmeny od zvoleného okamihu, detail, vytvorenie s kontrolou duplicít, úprava a zmazanie.

• Cenník

  Položky a služby katalógu: filtrovanie, triedenie, vytvorenie, úprava a zmazanie. Súčasť plánu Profi.

• Náklady

  Prijaté doklady: zoznam s filtrami podľa stavu, kategórie, obdobia a zmeny, zaúčtovanie, úprava a zmazanie. Súčasť plánu Profi.

• Prijaté e-faktúry

  Doručená schránka e-faktúr: zoznam, detail s riadkami a rozpisom DPH a archivovaný originál UBL. Čítanie cez API nič neoznačí ako prečítané.

• Opakované faktúry

  Rozvrhy opakovaných faktúr a ich posledné behy (na čítanie).

• Firemné profily

  Firmy, pod ktorými pracovný priestor vystavuje doklady, s označením tej predvolenej (na čítanie).

• Bankové účty

  Účty, na ktoré sa doklady uhrádzajú, s označením hlavného (na čítanie).

• Webhooky

  Udalosti, ktoré vporiadku pošle na vašu adresu: vystavenie, úhrada, nový náklad, prijatá e-faktúra a ďalšie. Podpísané HMAC-SHA256, spravované v aplikácii alebo cez API.

• Partnerské aplikácie

  OAuth 2.0 s PKCE: zákazníci pripoja vašu aplikáciu jedným klikom a vy máte token pre každý pracovný priestor s presne tými oprávneniami, ktoré schválili.

Rýchly štart

Základná adresa API je https://api.vporiadku.sk/api/v1. Odpovede sú JSON, peniaze desatinné čísla v mene dokladu, dátumy YYYY-MM-DD.

1. Krok 1

   Zapnite modul Firma

   Verejné API je súčasťou doplnkového modulu Firma k plánu Profi. Bez neho API odpovedá 403.

2. Krok 2

   Vytvorte kľúč

   V Nastavenia → API vytvorí vlastník alebo administrátor kľúč a vyberie mu oprávnenia. Celý kľúč sa zobrazí iba raz.

3. Krok 3

   Pošlite prvú požiadavku

   Ping overí kľúč a vráti jeho oprávnenia. Kľúč uložte do premennej prostredia, nikdy nie do kódu.

4. Krok 4

   Pokračujte v referencii

   Každé pole každej požiadavky a odpovede je v referencii OpenAPI 3.1, z ktorej si viete vygenerovať aj klienta.

curl https://api.vporiadku.sk/api/v1/ping \
  -H "Authorization: Bearer $VPORIADKU_API_KEY"

Overenie kľúčom

Kľúč pošlite v jednej z dvoch hlavičiek, alebo z partnerskej aplikácie prístupový token OAuth. Kľúče začínajú fak_, prístupové tokeny vpa_.

Authorization: Bearer fak_…
X-API-Key: fak_…
Authorization: Bearer vpa_…

• Celý kľúč sa zobrazí iba pri vytvorení; uchovávame len jeho odtlačok SHA-256. Stratený kľúč sa neobnovuje. Zrušte ho a vytvorte nový.
• Kľúč aj prístupový token koná ako vlastník svojho pracovného priestoru a nikdy nesiahne do iného.
• API je určené na komunikáciu server-server. Kľúč nepatrí do prehliadača ani do mobilnej aplikácie: kto ho uvidí, môže ho použiť.
• Kľúč zrušíte jedným klikom v Nastavenia → API; ďalšia požiadavka s ním dostane 401.
• Aplikácia, ktorá slúži mnohým zákazníkom vporiadku, nezbiera ich kľúče: pripája sa cez OAuth 2.0, ktorý popisuje nasledujúca časť.

Partnerské aplikácie (OAuth 2.0)

Robíte integráciu pre mnohých zákazníkov vporiadku: platformu e-shopov, účtovný softvér, CRM? Zaregistrujte ju raz ako aplikáciu. Každý zákazník ju pripojí jedným klikom na obrazovke súhlasu a váš server dostane prístupový token pre každý pracovný priestor s presne tými oprávneniami, ktoré zákazník schválil. Štandardný tok authorization code s PKCE a tie isté oprávnenia ako pri API kľúčoch.

1. 1

   Zaregistrujte aplikáciu

   V Nastavenia → API → Aplikácie: názov a web, ktoré uvidia zákazníci, vaše adresy presmerovania a najviac, o čo môže aplikácia žiadať. Dostanete client_id a client_secret; secret sa zobrazí iba raz. Pracovný priestor môže zaregistrovať najviac 10 aplikácií a platený plán na to netreba.

2. 2

   Pošlite zákazníka na obrazovku súhlasu

   S response_type=code, vaším client_id, zaregistrovanou redirect_uri, potrebnými oprávneniami, parametrom state a kódom PKCE code_challenge (S256). Zákazník sa prihlási, vyberie pracovný priestor a schváli, alebo zruší a vy dostanete error=access_denied. Pracovný priestor potrebuje modul Firma a schváliť môže len jeho vlastník alebo administrátor.

3. 3

   Vymeňte kód za tokeny

   Kód sa vráti na vašu adresu presmerovania spolu s vaším state. Do 10 minút ho vymeňte na tokenovom endpointe s vaším client secret a code_verifier. Dostanete prístupový token, obnovovací token, udelené oprávnenia (scope) a workspace_id.

4. 4

   Volajte API

   Prístupový token posielajte v hlavičke Authorization: Bearer pri každej požiadavke na /api/v1. Platí 60 minút; ping vám povie pracovný priestor a oprávnenia, ktoré nesie.

5. 5

   Obnovte ho skôr, než vyprší

   grant_type=refresh_token vráti novú dvojicu a starý obnovovací token spotrebuje. Obnovovací token platí 365 dní od vydania; ak ho niekto predloží znova viac ako 30 sekúnd po spotrebovaní, zruší sa celý reťazec.

6. 6

   Odpojenie

   Token zrušíte na endpointe na zrušenie tokenov (RFC 7009); zrušením posledného obnovovacieho tokenu sa aplikácia od pracovného priestoru odpojí. Aj zákazník môže vašu aplikáciu kedykoľvek odpojiť. Jej tokeny potom dostanú 401.

Zaregistrovať aplikáciu v Nastavenia → API → Aplikácie →

Endpointy

Obrazovka súhlasu

https://vporiadku.sk/oauth/authorize

Tokenový endpoint

https://api.vporiadku.sk/api/oauth/token

Zrušenie tokenu

https://api.vporiadku.sk/api/oauth/revoke

• PKCE s S256 je povinné, rovnako redirect_uri, ktorá sa musí presne zhodovať so zaregistrovanou: https, alebo http len pre localhost.
• Každá aplikácia je dôverný klient: tokenový endpoint chce váš client secret, cez HTTP Basic alebo ako client_id a client_secret vo formulári, nikdy oboje. Secret držte na svojom serveri.
• Oprávnenia sú tie isté ako pri API kľúčoch. Požiadavka nad rámec toho, čo zákazník schválil, dostane 403 API_KEY_SCOPE_MISSING s hlavičkou WWW-Authenticate: Bearer error="insufficient_scope".
• Limit sa počíta pre aplikáciu a pracovný priestor: 120 požiadaviek za 60 sekúnd pre každý pracovný priestor, ku ktorému je aplikácia pripojená, vrátane obnovených tokenov.
• Vaša aplikácia môže v každom pripojenom pracovnom priestore zaregistrovať cez /webhooks najviac 5 adries webhookov; dostávajú len udalosti, ktoré vaše oprávnenia dovoľujú čítať, a zmažú sa, keď zákazník aplikáciu odpojí.
• Chyby tokenového endpointu sú podľa RFC 6749: error a error_description; klient, ktorý ho volá príliš často, dostane 429 temporarily_unavailable s Retry-After. Prístupový token po uplynutí platnosti dostane 401 s WWW-Authenticate: Bearer error="invalid_token". Obnovte ho a požiadavku zopakujte.

import { createHash, randomBytes } from 'node:crypto'

const codeVerifier = randomBytes(32).toString('base64url')
const codeChallenge = createHash('sha256').update(codeVerifier).digest('base64url')
const state = randomBytes(16).toString('base64url')

// Keep codeVerifier and state in the user's session until the callback;
// send codeChallenge and state with the user to the consent screen.

https://vporiadku.sk/oauth/authorize?response_type=code&client_id=$CLIENT_ID&redirect_uri=https%3A%2F%2Fyour-app.example%2Foauth%2Fcallback&scope=invoices%3Awrite%20clients%3Aread%20webhooks%3Awrite&state=$STATE&code_challenge=$CODE_CHALLENGE&code_challenge_method=S256

curl -X POST https://api.vporiadku.sk/api/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri=https://your-app.example/oauth/callback \
  -d code_verifier="$CODE_VERIFIER"

curl -X POST https://api.vporiadku.sk/api/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token="$REFRESH_TOKEN"

curl -X POST https://api.vporiadku.sk/api/v1/webhooks \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-app.example/hooks/vporiadku", "events": ["invoice.paid", "client.created"]}'

Oprávnenia kľúča

Kľúč smie len to, čo mu vlastník pri vytvorení dovolil, a partnerská aplikácia len to, čo schválil zákazník. Integrácia e-shopu potrebuje zapisovať faktúry, reportovací nástroj nepotrebuje zapisovať nič.

• Zápis zahŕňa čítanie toho istého zdroja: kto vytvorí faktúru, dostane ju späť v odpovedi.
• Operácia mimo oprávnení skončí 403 API_KEY_SCOPE_MISSING a v details.required je oprávnenie, ktoré chýba. Rozsah existujúceho kľúča sa nemení: vytvorte nový; aplikácia požiada zákazníka o nový súhlas.
• Kľúče vytvorené pred zavedením oprávnení majú plný prístup (zapísaný ako *), aby existujúce integrácie fungovali ďalej.

Limity a stránkovanie

Každý kľúč (a každá partnerská aplikácia v každom pracovnom priestore, ku ktorému je pripojená) môže poslať 120 požiadaviek za 60 sekúnd, spolu na všetky endpointy. Okno je pevné a po uplynutí sa celé obnoví.

HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 60

• Každá odpoveď nesie X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset (počet sekúnd do obnovenia okna).
• Po vyčerpaní limitu príde 429 RATE_LIMIT_EXCEEDED s hlavičkou Retry-After; počkajte uvedený počet sekúnd. Každý kľúč má vlastné okno a rovnako každá aplikácia v každom pracovnom priestore, ku ktorému je pripojená.
• Po 30 neúspešných overeniach z jednej adresy za 60 sekúnd prestane API kľúče z tejto adresy overovať, kým okno neuplynie.
• Zoznamy berú page (od 1) a limit (predvolene 20, najviac 100) a odpovedajú { data, total, page, limit }.

Idempotency-Key

Pošlite hlavičku Idempotency-Key pri POST a PATCH a opakovanie požiadavky po výpadku spojenia nevytvorí druhú faktúru. Kľúč platí 24 hodín a patrí k API kľúču (alebo k partnerskej aplikácii v danom pracovnom priestore), ktorý ho poslal.

• Opakovanie s tou istou metódou, cestou a telom dostane uloženú odpoveď s hlavičkou Idempotent-Replayed: true a nič sa nevykoná znova: žiadna druhá faktúra, e-mail ani webhook.
• Ten istý kľúč s inou požiadavkou skončí 409 IDEMPOTENCY_KEY_REUSED.
• Opakovanie, kým prvá požiadavka ešte beží, skončí 409 IDEMPOTENCY_KEY_IN_USE. Skúste o chvíľu.
• Ukladá sa len úspešná odpoveď: neúspešnú požiadavku môžete zopakovať s tým istým kľúčom.

curl -X POST https://api.vporiadku.sk/api/v1/clients \
  -H "Authorization: Bearer $VPORIADKU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a9e-4b7d-4e0a-9c55-0f3e8a1b2c4d" \
  -d '{"name": "Novák s.r.o.", "ico": "12345678", "email": "faktury@novak.sk"}'

Chyby

Každá chyba má rovnaký tvar. Rozhodujte sa podľa error.code; správa je anglická a môže sa zmeniť. Neznáme pole v tele požiadavky je chyba 400, nie ticho ignorovaná hodnota.

{
  "data": null,
  "meta": null,
  "error": {
    "code": "API_KEY_SCOPE_MISSING",
    "message": "This API key lacks the \"invoices:write\" scope",
    "details": {
      "operation": "createInvoice",
      "required": "invoices:write",
      "granted": [
        "invoices:read"
      ]
    }
  }
}

Endpointy

49 operácií pod adresou https://api.vporiadku.sk/api/v1. Tabuľka sa generuje z toho istého katalógu, z ktorého beží server.

Všetky polia, parametre a odpovede v referencii API →

Príklady

Kľúč čítajú z premennej prostredia VPORIADKU_API_KEY. Hodnoty v lomených zátvorkách nahraďte identifikátormi z predchádzajúcich odpovedí.

curl "https://api.vporiadku.sk/api/v1/invoices?status=overdue&page=1&limit=50" \
  -H "Authorization: Bearer $VPORIADKU_API_KEY"

# 1. A draft; the server computes every total itself
curl -X POST https://api.vporiadku.sk/api/v1/invoices \
  -H "Authorization: Bearer $VPORIADKU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-2026-1001" \
  -d '{"clientId": "<client id>", "issueDate": "2026-10-12", "dueDate": "2026-10-26", "items": [{"name": "Konzultácia", "quantity": 2, "unit": "hod", "unitPrice": 60, "vatRate": 23}]}'

# 2. Issue it: the number is fixed and the content locked
curl -X POST https://api.vporiadku.sk/api/v1/invoices/<invoice id>/issue \
  -H "Authorization: Bearer $VPORIADKU_API_KEY"

# 3. E-mail it to the client with the PDF attached
curl -X POST https://api.vporiadku.sk/api/v1/invoices/<invoice id>/send \
  -H "Authorization: Bearer $VPORIADKU_API_KEY"

curl -X POST https://api.vporiadku.sk/api/v1/invoices/<invoice id>/payments \
  -H "Authorization: Bearer $VPORIADKU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 147.60, "paymentDate": "2026-10-20", "paymentMethod": "bank_transfer"}'

Webhooky

35 udalostí v 13 skupinách. vporiadku ich pošle metódou POST na adresu, ktorú zaregistrujete, a podpíše ich tajomstvom tejto adresy.

• Adresa dostane len udalosti, ktoré si vyberiete; každá adresa má vlastné tajomstvo whsec_.
• Podpis je v hlavičke x-vporiadku-signature: v1= a HMAC-SHA256 reťazca „časová pečiatka.telo“. Overujte nad nespracovaným telom, porovnávajte v konštantnom čase a odmietnite doručenie staršie ako 300 sekúnd.
• Odpovedzte kódom 2xx do 10 sekúnd. Ostatné pokusy opakujeme s narastajúcim odstupom, spolu 8-krát; na 400, 401, 403, 404, 405, 410 a 422 už nie.
• To isté doručenie môže prísť dvakrát. Duplicity zahadzujte podľa idempotencyKey z obálky.
• Adresy, výber udalostí, tajomstvá, testovacia udalosť a denník doručení sú v Nastavenia → API → Webhooky. Cez /webhooks s oprávnením webhooks:write viete adresy registrovať, meniť, testovať, mazať a meniť ich tajomstvá. Partnerská aplikácia vidí a spravuje len adresy, ktoré sama zaregistrovala.
• Cez API môže adresa dostávať len udalosti, ktorých dáta kľúč alebo token smie čítať: udalosti faktúr a dokladov potrebujú invoices:read, platieb payments:read, nákladov expenses:read a tak ďalej. Udalosti bankového prepojenia, priznania DPH, predplatného a tímu sa nastavujú len v aplikácii.

Udalosti

Faktúry

invoice.createdinvoice.updatedinvoice.sentinvoice.viewedinvoice.paidinvoice.overdueinvoice.cancelled

Ostatné doklady

credit_note.createdquote.createdquote.acceptedquote.rejectedquote.expireddelivery_note.createdorder.created

Platby

payment.recordedpayment.matched

Náklady

expense.createdexpense.updatedexpense.paid

Banka

bank_statement.importedbank_feed.syncedbank_feed.consent_expiring

e-Faktúra

einvoice.senteinvoice.deliveredeinvoice.failedeinvoice.received

Kontakty

client.createdsupplier.created

Cenník

item.created

Opakované faktúry

recurring_invoice.generatedrecurring_invoice.failed

DPH

vat_report.generated

Predplatné

subscription.updated

Tím

team.member_joined

Test

ping

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

export const isGenuine = (rawBody, signature, timestamp, secret) => {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
  const expected = 'v1=' + createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')
  const a = Buffer.from(expected)
  const b = Buffer.from(String(signature))
  return a.length === b.length && timingSafeEqual(a, b)
}

// rawBody = the request body exactly as received; signature = 'x-vporiadku-signature',
// timestamp = 'x-vporiadku-timestamp'. Answer 2xx within 10 seconds, work afterwards,
// and drop repeats by the envelope's idempotencyKey.

Obálka, hlavičky a všetky udalosti v referencii API →

Prístup a cena

Verejné API a webhooky sú súčasťou doplnkového modulu Firma k plánu Profi za 3,90 € mesačne bez DPH. Modul pridáva aj tím s rolami, viac firiem v jednom účte a prístup pre účtovníka.

Časté otázky

Koľko stojí prístup k API?

API a webhooky sú súčasťou doplnkového modulu Firma k plánu Profi. Za volania sa nič navyše neplatí; platí limit 120 požiadaviek za minútu na kľúč.

Viem cez API posielať e-faktúry do siete Peppol?

Nie. Prijaté e-faktúry cez API čítať viete, odosielanie cez Peppol verejné API neponúka.

Je k dispozícii testovacie prostredie?

Samostatný sandbox nemáme: API vždy pracuje s ostrými dátami vášho pracovného priestoru. Začnite kľúčom len na čítanie a zápisy skúšajte s vedomím, že aj koncept dostane číslo zo svojho radu.

Ako sa API mení?

Verzia je v ceste: /api/v1. Pridanie poľa do odpovede nie je zmena, ktorá by niečo rozbila. Neznáme polia ignorujte. Zmena, ktorá by existujúcu integráciu rozbila, by prišla v novej verzii.

Dajú sa webhooky spravovať cez API?

Áno. S oprávnením webhooks:write cez /webhooks adresy registrujete, meníte, testujete a mažete, len pre udalosti, ktorých dáta kľúč alebo token smie čítať. Partnerská aplikácia spravuje v každom pripojenom pracovnom priestore len svoje adresy.

Ako sa k vporiadku pripojí aplikácia pre mnohých zákazníkov?

Cez OAuth 2.0: zaregistrujte aplikáciu v Nastavenia → API → Aplikácie, pošlite každého zákazníka na obrazovku súhlasu a tokeny, ktoré dostanete, si uložte pre každý pracovný priestor zvlášť. Zákazník vyberie pracovný priestor, schváli oprávnenia a aplikáciu môže kedykoľvek odpojiť. Každý pripojený pracovný priestor má vlastný limit 120 požiadaviek za minútu.