SaveÚčto API

Začíname

1. V SaveÚčte otvorte Nastavenia → API a vytvorte kľúč. Vyberte len oprávnenia, ktoré váš systém potrebuje. Kľúč sa zobrazí jediný raz.
2. Kľúč posielajte v hlavičke X-Api-Key (alebo Authorization: Bearer). V adrese ho API odmietne.
3. Prvé volanie:

curl https://saveucto.sk/api/v1/firma -H "X-Api-Key: $KLUC"

API je súčasťou balíka Biznis (10,00 € mesačne) bez príplatku.

Oprávnenia

Každý kľúč patrí jednej firme a vidí len jej dáta. Oprávnenie :write zahŕňa aj čítanie.

Kľúču môžete nastaviť platnosť a povolené IP adresy. Zrušený kľúč prestane fungovať okamžite. O vytvorení aj zrušení kľúča pošleme e-mail administrátorom firmy.

Stránkovanie a synchronizácia

Zoznamy sa listujú podľa ID, nie podľa čísla strany, takže nové záznamy nepokazia poradie. Ďalšiu stranu získate s od_id = next_od_id z predošlej odpovede. Keď je next_od_id null, ste na konci. limit je predvolene 50, najviac 200.

curl "https://saveucto.sk/api/v1/odberatelia?limit=200" -H "X-Api-Key: $KLUC"
curl "https://saveucto.sk/api/v1/odberatelia?limit=200&od_id=843" -H "X-Api-Key: $KLUC"

# len to, čo sa zmenilo od poslednej synchronizácie
curl "https://saveucto.sk/api/v1/produkty?zmenene_od=2026-10-29T08:00:00%2B01:00" -H "X-Api-Key: $KLUC"

Vaše ID

Pri vytvorení alebo úprave pošlite ext_source (názov vášho systému) a ext_id. Záznam potom nájdete podľa svojho ID a naše ID si nemusíte ukladať.

curl -X POST https://saveucto.sk/api/v1/odberatelia \
  -H "X-Api-Key: $KLUC" -H "Content-Type: application/json" \
  -d '{"name": "Nová firma s.r.o.", "ico": "55991271", "email": "objednavky@novafirma.sk",
       "city": "Žilina", "ext_source": "eshop", "ext_id": "A-123"}'

curl https://saveucto.sk/api/v1/odberatelia/externe/eshop/A-123 -H "X-Api-Key: $KLUC"

Odberateľa s IČO, ktoré už vo firme existuje, API znova nezaloží. Vráti 409 s existing_id. Úprava (PUT) mení len polia, ktoré pošlete. Polia, ktoré API nepozná, ignoruje a vypíše ich vo warnings.

Faktúry

Doklad sa vystaví hneď. Číslo pridelí číselný rad firmy, sumy dopočíta SaveÚčto. Typ určuje doc_type: faktúra, zálohová faktúra, dobropis, ťarchopis, cenová ponuka, objednávka, dodací list. Platia tie isté pravidlá ako vo formulári, napríklad platca DPH musí uviesť dátum dodania.

curl -X POST https://saveucto.sk/api/v1/faktury \
  -H "X-Api-Key: $KLUC" -H "Content-Type: application/json" -H "Idempotency-Key: obj-2026-0815" \
  -d '{"issue_date": "2026-10-29", "delivery_date": "2026-10-29", "due_date": "2026-11-12",
       "payment_method": "Prevodom", "customer_name": "Nová firma s.r.o.", "customer_ico": "55991271",
       "customer_email": "uctaren@novafirma.sk", "ext_source": "eshop", "ext_id": "OBJ-2026-0815",
       "items": [{"description": "Montáž", "quantity": 2, "unit": "hod", "unit_price_cents": 3500, "vat_rate": 23}]}'

curl https://saveucto.sk/api/v1/faktury/1234/pdf -H "X-Api-Key: $KLUC" -o faktura.pdf
curl -X POST https://saveucto.sk/api/v1/faktury/1234/odoslat -H "X-Api-Key: $KLUC"
curl -X POST https://saveucto.sk/api/v1/faktury/1234/uhrady -H "X-Api-Key: $KLUC" -H "Content-Type: application/json" \
  -d '{"amount_cents": 8610, "paid_on": "2026-11-05"}'

odoslat pošle PDF e-mailom z mailového účtu firmy na customer_email, s "channel": "efaktura" cez digitálneho poštára. Úprava (PUT) nahradí celý doklad vrátane položiek. Stornovaný doklad, uzavreté obdobie DPH a zamknutý účtovný rok vrátia 409 locked. Vystavený doklad sa nemaže, len stornuje. API zapisuje len bezhotovostné úhrady.

Nákup, pokladňa a sklad

POST /prijate-faktury zaeviduje prijatú faktúru, bloček alebo zálohovú faktúru s rovnakými pravidlami ako formulár. Sken alebo ISDOC nahráte zvlášť ako multipart/form-data (pole file, najviac 10 MB):

curl -X POST https://saveucto.sk/api/v1/prijate-faktury/77/priloha -H "X-Api-Key: $KLUC" -F "file=@faktura.pdf"

POST /pokladnicne-doklady vystaví príjmový alebo výdavkový doklad (suma vrátane DPH v centoch). Sklad je len na čítanie: GET /sklad/pohyby a GET /sklad/zasoby. Ak firma nemá modul Pokladňa alebo Sklad zapnutý alebo v balíku, API vráti 403 module_not_available.

Opakované požiadavky

Každý POST prijme hlavičku Idempotency-Key, napríklad ID objednávky. Keď spojenie spadne a požiadavku pošlete znova s tým istým kľúčom, do 24 hodín dostanete pôvodnú odpoveď (s hlavičkou Idempotent-Replayed: true) a druhá faktúra nevznikne. Rovnaký kľúč s iným telom vráti 422 idempotency_mismatch. Odpoveď s chybou sa neukladá, opravenú požiadavku môžete poslať s tým istým kľúčom.

Webhooky

V Nastavenia → API a integrácie → Webhooky zadáte https adresu a udalosti. SaveÚčto na ňu pošle POST hneď, ako udalosť nastane:

• faktura.vystavena: Faktúra vystavená
• faktura.uhradena: Faktúra uhradená
• faktura.stornovana: Faktúra stornovaná
• prijata_faktura.prijata: Prijatá faktúra zaevidovaná
• odberatel.zmeneny: Odberateľ založený alebo zmenený

{"id": "8c1d0c4e-…", "event": "faktura.uhradena", "created_at": "2026-10-29T10:15:00+01:00", "data": {"id": 1234}}

Telo nesie len ID, aktuálny stav si načítajte cez API (GET /faktury/1234). Odpovedzte kódom 2xx do 10 sekúnd. Inak pokus zopakujeme o 1, 5, 15 minút, 1, 3, 6, 12 a 24 hodín. Po 20 neúspechoch za sebou webhook pozastavíme a pošleme e-mail administrátorom firmy. Udalosť môže prísť aj dvakrát, rozlíšite ju podľa id. Na adresy v lokálnych a privátnych sieťach ani na presmerovania neposielame.

Overte podpis: X-SaveUcto-Signature = sha256= + HMAC-SHA256 z reťazca {X-SaveUcto-Timestamp}.{telo} tajomstvom webhooku. Odmietnite požiadavku, ktorej čas je starší ako 5 minút (ochrana proti zopakovaniu).

// PHP
$telo = file_get_contents('php://input');
$cas = $_SERVER['HTTP_X_SAVEUCTO_TIMESTAMP'] ?? '';
$ocakavany = 'sha256='.hash_hmac('sha256', $cas.'.'.$telo, getenv('SAVEUCTO_WEBHOOK_SECRET'));

if (! hash_equals($ocakavany, $_SERVER['HTTP_X_SAVEUCTO_SIGNATURE'] ?? '') || abs(time() - (int) $cas) > 300) {
    http_response_code(401);
    exit;
}

# Python
import hmac, hashlib, time
ocakavany = "sha256=" + hmac.new(secret.encode(), f"{cas}.".encode() + telo, hashlib.sha256).hexdigest()
ok = hmac.compare_digest(ocakavany, podpis) and abs(time.time() - int(cas)) <= 300

Peniaze, dátumy, sadzby

Sumy sú v centoch (unit_price_cents: 1250 = 12,50 €), dátumy v ISO 8601 (2026-10-29), sadzba DPH ako číslo (23).

Chyby

Každá chyba má rovnaký tvar: text pre človeka a stabilný kód pre program. Pri neplatných dátach pribudne fields.

{"error": "Neplatné dáta.", "code": "validation_failed", "fields": {"email": ["Pole email musí byť platná e-mailová adresa."]}}

Každá odpoveď má hlavičku X-Request-Id. Ak nám hlásite problém, pošlite ju.

Limity

• 60 požiadaviek za minútu na kľúč (hlavičky X-RateLimit-Limit, X-RateLimit-Remaining),
• 0 volaní denne na firmu,
• telo požiadavky najviac 1 MB, príloha prijatej faktúry 10 MB, doklad najviac 500 položiek.

Príklady

PHP

$api = fn (string $method, string $path, ?array $body = null) => json_decode(file_get_contents('https://saveucto.sk/api/v1'.$path, false, stream_context_create(['http' => [
    'method' => $method,
    'header' => "X-Api-Key: ".getenv('SAVEUCTO_KEY')."\r\nContent-Type: application/json\r\nAccept: application/json",
    'content' => $body ? json_encode($body) : null,
    'ignore_errors' => true,
]])), true);

$odberatel = $api('POST', '/odberatelia', ['name' => 'Nová firma s.r.o.', 'ico' => '55991271', 'email' => 'uctaren@novafirma.sk']);

$faktura = $api('POST', '/faktury', [
    'issue_date' => date('Y-m-d'), 'delivery_date' => date('Y-m-d'), 'due_date' => date('Y-m-d', strtotime('+14 days')),
    'payment_method' => 'Prevodom', 'customer_name' => 'Nová firma s.r.o.', 'customer_ico' => '55991271',
    'customer_email' => 'uctaren@novafirma.sk',
    'items' => [['description' => 'Montáž', 'quantity' => 2, 'unit' => 'hod', 'unit_price_cents' => 3500]],
])['data'];

$api('POST', "/faktury/{$faktura['id']}/odoslat");

Python

import os, requests

api = requests.Session()
api.headers["X-Api-Key"] = os.environ["SAVEUCTO_KEY"]

od_id = None
while True:
    strana = api.get("https://saveucto.sk/api/v1/odberatelia", params={"limit": 200, "od_id": od_id}).json()
    for odberatel in strana["data"]:
        print(odberatel["id"], odberatel["name"])
    od_id = strana["next_od_id"]
    if od_id is None:
        break

Testovanie

Integráciu si vyskúšajte v sandboxe na https://sandbox.saveucto.sk. Po registrácii dostanete testovaciu firmu s odberateľmi, cenníkom, faktúrami a kľúčom su_test_…. API je rovnaké, mení sa len adresa (https://sandbox.saveucto.sk/api/v1).

• E-maily sa neposielajú. Nájdete ich v sandboxe v Nastavenia → Zachytené e-maily.
• Digitálny poštár je simulovaný. Faktúra sa o chvíľu označí ako doručená, odberateľ s DIČ končiacim na 99 ju odmietne.
• Úhradu ako z banky vyvoláte cez POST /sandbox/simuluj-uhradu.
• Testovací kľúč v produkcii a ostrý kľúč v sandboxe vrátia 401 wrong_environment.
• Firmy, ktoré 30 dní nikto nepoužije, sa zmažú.

S integráciou radi pomôžeme: vyfakturuj@savetrack.sk.

Zmeny

Vo verzii v1 robíme len spätne kompatibilné zmeny (nové polia a endpointy). Nekompatibilná zmena dostane novú verziu a v1 bude mať vopred ohlásený koniec.

• 1.0.0: vydané a prijaté faktúry, úhrady, PDF a odoslanie, pokladničné doklady, sklad, odberatelia, produkty, údaje firmy a číselníky, Idempotency-Key, webhooky, sandbox.