← Blog 15.4.2026 ONDRÚŠ SOFTWARE developer

Pay by Square API vs. vlastná implementácia

Oplatí sa implementovať Pay by Square knižnicu vlastnými silami alebo použiť hotové REST API? Porovnanie nákladov a komplexity.

Úvod

Pay by Square je slovenský štandard pre platobné QR kódy. Ak budujete fakturačný systém, e-shop alebo účtovný softvér, skôr či neskôr narazíte na otázku — implementovať generovanie QR kódov vo vlastnom kóde alebo použiť hotové REST API? Obe cesty fungujú. Tento článok porovnáva náklady, komplexitu a rozhoduje, kedy má zmysel ktorá.

Čo obnáša vlastná implementácia

Štandard Pay by Square (verzia 1.2.0) je verejne dostupný, ale implementácia nie je triviálna. Budete potrebovať:

Reed-Solomon kódovanie — chyba-korekčný algoritmus pre robustnosť skenovania
LZMA kompresia — Pay by Square komprimuje platobné údaje pre menší QR kód
Base32 výstup — kompaktná textová reprezentácia binárnych dát
XOR checksum + CRC32 — integritné kontroly údajov
QR kód renderovanie — knižnica na vykreslenie samotného obrázka (napr. endroid/qr-code pre PHP alebo qrcode pre Node.js)

Pre skúseného developera je realistický odhad 8 až 20 hodín na implementáciu a zladenie so štandardom. Plus ďalší čas na testovanie — Pay by Square musí fungovať vo všetkých slovenských bankových aplikáciách (Tatra banka, VÚB, ČSOB, Slovenská sporiteľňa, mBank a ďalšie), pričom každá má vlastný parser s drobnými odchýlkami. Unicode v mene príjemcu, dlhé IBAN checksumy, edge cases pri zaokrúhľovaní — všetko treba pokryť.

Po nasadení prichádza údržba. Štandard sa občas mení (napríklad nová verzia rozšírenia pre BIC kódy v roku 2024). Vlastný kód treba aktualizovať, testovať a redeployovať. Cena v hodinách pokračuje.

Čo obnáša REST API

Easy Square REST API vám odstraňuje celú vyššie uvedenú komplexitu. Integrácia je jedno POST volanie:

curl -X POST https://api.easy-square.sk/api/v1/pay-by-square/qr-code \
  -H "X-Api-Email: vas@email.sk" \
  -H "X-Api-Key: esq_vas_kluc" \
  -H "Content-Type: application/json" \
  -d '{"iban":"SK31...","amount":42.50,"variableSymbol":"2026001"}' \
  --output qr.png

Žiadne knižnice, žiadne závislosti na vašej strane. Server sa stará o kompresiu, kódovanie, renderovanie aj o zmeny štandardu. Realistický odhad integrácie: 30 minút na prvý funkčný QR kód vrátane získania API kľúča.

Pre podrobné PHP a Node.js príklady pozrite články Pay by Square QR kód v PHP cez REST API a Pay by Square QR kód v Node.js cez REST API.

Reálny benchmark — latencia REST API

Ak vás zaujíma, ako rýchlo REST API odpovedá, spustite si nasledujúci benchmark. Urobí 10 sekvenčných volaní a vypíše priemerný čas na QR kód.

`benchmark.mjs`

const apiUrl = 'https://api.easy-square.sk/api/v1/pay-by-square/qr-code';
const N = parseInt(process.env.ES_BENCH_N || '10', 10);

async function call(i) {
  const start = performance.now();
  const res = await fetch(apiUrl, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Email': process.env.ES_API_EMAIL,
      'X-Api-Key': process.env.ES_API_KEY,
    },
    body: JSON.stringify({
      beneficiaryName: 'Benchmark Test',
      iban: 'SK3112000000198742637541',
      amount: Math.round(Math.random() * 10000) / 100,
      variableSymbol: String(Date.now() + i).slice(-10),
    }),
  });
  await res.arrayBuffer();
  return { ok: res.ok, elapsed: performance.now() - start };
}

const times = [];
for (let i = 0; i < N; i++) {
  const r = await call(i);
  if (!r.ok) break;
  times.push(r.elapsed);
  console.log(`#${i + 1}  ${r.elapsed.toFixed(0)} ms`);
}

const avg = times.reduce((a, b) => a + b, 0) / times.length;
console.log(`\nPriemer: ${avg.toFixed(0)} ms / QR`);

`Dockerfile`

FROM node:20-alpine
WORKDIR /app
COPY benchmark.mjs .
CMD ["node", "benchmark.mjs"]

Spustenie

docker build -t es-bench .
docker run --rm \
  -e ES_API_EMAIL=vas@email.sk \
  -e ES_API_KEY=esq_vas_kluc \
  es-bench

Typické výsledky z testu: prvé volanie okolo 330 ms (nadviazanie TLS spojenia), ďalšie v rozmedzí 40–60 ms. Priemer z 10 volaní približne 80 ms na QR kód. Pre webovú aplikáciu zanedbateľné. Pre nočný dávkový import tisícov faktúr môžete paralelizovať a dostať sa na desiatky milisekúnd na kód.

Kedy má zmysel vlastná implementácia

Existujú tri situácie, v ktorých je vlastná implementácia rozumnou voľbou:

Offline generovanie. Ak vaša aplikácia musí fungovať bez pripojenia na internet (typicky desktopový fakturačný softvér pre živnostníkov, ktorí pracujú v teréne), vlastná implementácia je jediná možnosť.

Extrémne vysoký objem. Pri desiatkach tisíc QR kódov za deň sa môže oplatiť investovať do vlastnej implementácie kvôli ušetreným API volaniam. Hranicu si spočítajte — pri 10 000 kódov denne a cene 0,003 € za kód sú to 30 € denne, teda 900 € mesačne.

Regulačné obmedzenia. Finančné inštitúcie alebo verejná správa niekedy vyžadujú, aby citlivé dáta neopustili ich infraštruktúru. V takom prípade externá závislosť nie je prípustná.

Kedy má zmysel REST API

Pre väčšinu ostatných prípadov je REST API rýchlejšia a lacnejšia cesta:

Webové aplikácie a e-shopy. Ak už voláte externé API (platobné brány, doručovatelia), jedno ďalšie HTTP volanie nemení architektúru.

Rýchla integrácia. Keď potrebujete hotové riešenie za pár hodín — napríklad preto, že sa blíži termín spustenia — REST API ušetrí dni vývoja.

Žiadna údržba štandardu. Pay by Square sa mení, banky aktualizujú svoje parsre, pribúdajú nové parametre. S REST API sa o to stará Easy Square — vy riešite svoj biznis.

Prispôsobenie bez kódu. Chcete QR kód s vlastnou farbou, rámčekom alebo inou veľkosťou? REST API má na to parametre. Pri vlastnej implementácii by ste museli upravovať svoj renderovací kód.

Kalkulácia — čas vs. peniaze

Zjednodušený výpočet pre typický scenár malého e-shopu s 500 objednávkami mesačne:

	Vlastná implementácia	REST API
Počiatočný vývoj	12 hodín × hodinová sadzba	30 minút × hodinová sadzba
Mesačná cena	0 €	500 × 0,003 € = 1,50 €
Údržba ročne	2–4 hodiny (zmeny štandardu)	0 hodín
Infraštruktúra	Vlastný server + monitoring	Bez nákladov

Pri hodinovej sadzbe developera 40 € stojí vlastná implementácia prvý rok asi 560 € (12 h + 2 h údržba). REST API za ten istý rok: 18 € + pol hodiny vývoja (~20 €) = 38 €. Break-even nastáva až pri objeme zhruba 15 000 kódov mesačne.

Záver — odporúčanie

Pre webové aplikácie, e-shopy a bežné fakturačné systémy REST API vyhráva. Rýchlejšia integrácia, nulová údržba, predvídateľná cena a žiadna zodpovednosť za zmeny štandardu.

Pre offline aplikácie, extrémny objem nad 15 000 kódov mesačne alebo regulačne obmedzené prostredia má vlastná implementácia opodstatnenie. Nie je to zlá voľba — je to iná voľba.

Ak ste sa rozhodli pre API, začnite na easy-square.sk/registracia/ — kredit plán od 0,003 € bez DPH za QR kód. Free generátor na hlavnej stránke (100 QR/deň bez registrácie) stačí na otestovanie. Kompletnú dokumentáciu API nájdete na dokumentacia-api.