eFaktúra Developers

Changelog

Datovaný prehľad zmien Agent API a partnerského portálu. Najnovšie hore.

2026-10-13Nové
  • Cudzia mena na faktúrach: POST /v1/agent/invoices prijíma voliteľné polia currency (ISO 4217; bez nej mena firmy) a exchange_rate (jednotky meny na jednu jednotku domácej meny firmy, napr. "1.0842"). Bez kurzu server doplní kurz ECB (slovenská firma) alebo ČNB (česká firma) k dátumu zdaniteľného plnenia; ak ho nezíska, faktúra vznikne s exchange_rate: null. Dobropis a ťarchopis musia mať menu pôvodnej faktúry. Odpoveď aj GET /v1/agent/invoices/{id} nesú exchange_rate.
  • Doklady z API do účtovného programu: POST /v1/agent/expenses/{id}/approve-for-accounting (rozsah receipt:approve) je obdoba tlačidla Zaúčtovať v eDokladoch — označí prijatý doklad ako schválený na zaúčtovanie a odovzdá ho Konektoru (Omega, Pohoda, Money S3, MRP). Opakované volanie nič nerobí; doklad v stave processing, needs_review alebo rejected vráti 409 EXPENSE_NOT_POSTABLE. Hromadne cez POST /v1/agent/expenses/bulk s action: approve_for_accounting.
  • Vzájomný zápočet cez API: POST /v1/agent/offsets (rozsahy invoice:update a receipt:update, Idempotency-Key) započíta vydanú faktúru s prijatou faktúrou tej istej protistrany — zapíše úhradu so spôsobom offset na oba doklady a spáruje ich. GET /v1/agent/offsets (invoice:read) vráti zoznam zápočtov. Pre firmy s Omegou eFaktúra vytvorí interný doklad, keď zrkadlo Omegy obsahuje oba doklady; stav je v accounting_program. Len pre slovenské firmy.
2026-10-10Nové
  • Čiastočné úhrady a zápočet cez API: POST /v1/agent/invoices/{id}/payments (rozsah invoice:update) zaeviduje jednu úhradu dokladu so sumou, dátumom a spôsobom bank_transfer, cash, card alebo offset (vzájomný zápočet). Zostatok po zápočte zaevidujete druhým volaním; odpoveď v meta vráti nový zostatok a stav. Podporuje Idempotency-Key.
2026-10-02Vylepšenie
  • Sandbox sa správa ako produkcia: POST /v1/agent/organizations organizáciu do Peppol TEST siete nezapíše, POST /v1/agent/peppol/enroll vyžaduje verifikačný token (v sandboxe stačí ľubovoľný hex) a odoslanie bez aktívneho Peppol účtu sa odmietne. Platí hneď pre účty registrované od 02.10.2026 a pre staršie účty po zapnutí „Sandbox ako produkcia“ v portáli (Tím a oprávnenia), pre ostatné od 01.11.2026; dovtedy ich odpovede nesú pole warnings a hlavičky Deprecation, Sunset a Link. Testovacie tokeny a rozdiely sú na stránke Sandbox vs. produkcia.
  • Preflight faktúry: POST /v1/agent/invoices/{id}/preflight (rozsah invoice:read) jedným volaním zvaliduje presne ten dokument, ktorý sa odošle (vrátane príloh a Peppol ID), a overí príjemcu z DIČ odberateľa; nič nezapisuje ani neúčtuje. GET /v1/agent/invoices/{id}/xml pred odoslaním vracia ten istý dokument (hlavička X-Efaktura-Ubl-Source: preview). Každá odpoveď /v1/agent/* nesie hlavičku Server-Timing. Viac v Odporúčaný tok.
2026-10-01Nové
  • Webhooky pre firmy s vlastným API kľúčom: POST /v1/agent/webhooks (rozsah settings:update, plán Pro a vyšší) zaregistruje HTTPS endpoint pre udalosti faktúr (invoice.created/updated/deleted/sent/viewed/paid/overdue — z akéhokoľvek kanála vrátane importu a opakovaných faktúr), platieb, upomienok, skladu a Peppol dokladov (peppol.document.sent/delivered/failed/received). Doručenie má rovnaký podpis a opakovania ako partnerské webhooky (11 pokusov počas ~2,7 dňa), históriu a opätovné odoslanie cez /v1/agent/webhooks/{id}/deliveries. Na tieto endpointy sa napájajú aj okamžité spúšťače v Make a n8n. Viac vo Webhooky → Webhooky pre firmy.
  • OAuth „Pripojiť cez eFaktúru“: aplikácie tretích strán (e-shop, CRM, ERP) sa zaregistrujú cez Dynamic Client Registration s resources ["https://api.efaktura.sk/v1/agent"], používateľ sa prihlási, vyberie firmu a odsúhlasí rozsahy a aplikácia volá Agent API s Authorization: Bearer. Token je viazaný na jednu firmu (X-Organization-Id netreba), rozsahy sú priesečníkom súhlasu a role používateľa a používateľ ho kedykoľvek zruší v Nastavenia → Integrácie. Tokeny pre MCP a Agent API sú oddelené. Viac v OAuth — Pripojiť cez eFaktúru.
  • Schránka udalostí: GET /v1/agent/events (partnerský kľúč, rozsah invoice:read) vráti všetky partnerské udalosti od najstaršej, stránkované kurzorom after/next_after, s rovnakým telom ako webhook. Udalosti sa zapisujú aj bez zaregistrovaného webhook endpointu a uchovávame ich 90 dní — zmeškané udalosti si tak stiahnete aj za firewallom alebo po dlhšom výpadku. Viac vo Webhooky → Schránka udalostí.
2026-09-30Vylepšenie
  • Partnerské webhooky sa pri zlyhaní opakujú dlhšie: 11 pokusov počas približne 2,7 dňa (5 s, 1 min, 5 min, 30 min, 2 h, 5 h, 10 h, 10 h, 14 h, 24 h) namiesto 6 pokusov za 2,5 minúty. Endpoint, ktorý je dočasne nedostupný, tak dostane všetky udalosti bez ručného replayu. Deduplikácia podľa X-Webhook-Id platí ďalej.
2026-09-28Vylepšenie
  • Do 31.12.2026 live odoslanie faktúry cez Peppol (agentom, dávkou, raw-UBL konektorom, SAPI-SK aj SFTP) zlyhá s INVOICE_ISSUE_DATE_TOO_OLD, ak bola faktúra vyhotovená pred viac ako 10 dňami. Ide o interný bezpečnostný limit eFaktura, nie zákonnú lehotu; testovacie odoslania ho nemajú. Od 1.1.2027 ho nahradí pravidlo INVOICE_ISSUE_DATE_NOT_SEND_DATE.
2026-09-23Nové
  • Plánované a hromadné odosielanie cez Peppol: GET/PUT /v1/agent/peppol/send-settings volí režim odosielania (immediate/scheduled/manual), POST /v1/agent/peppol/batches/send uvoľní podržané odoslania na požiadanie a GET /v1/agent/peppol/queue vracia fronty organizácie a platformové odhady dokončenia. Podržané odoslania uvoľňuje aj automatický bezpečnostný uzáver, aby vždy stihli odísť do 21:00. Viac v Plánované a hromadné odosielanie.
  • Od 1.1.2027 odoslanie faktúry cez Peppol (agentom, dávkou, raw-UBL konektorom, SAPI-SK aj SFTP) zlyhá s INVOICE_ISSUE_DATE_NOT_SEND_DATE, ak sa dátum vyhotovenia (BT-2) nezhoduje s dnešným dňom — podľa FAQ Finančnej správy k e-Faktúre a § 85o zákona o DPH.
2026-09-19Nové
  • GET /v1/agent/dashboard/onboarding (rozsah report:read): stav zavedenia firmy jedným volaním — Peppol účet (participant_id, status, claim_status, pending_mandate), plán a predplatné (status vrátane past_due, current_period_end, edoklady_active), bankové pripojenia s platnosťou súhlasu consent_expires_at a prepojenie s účtovným programom cez Konektor (spárovanie, verzia, posledný úspešný zápis, počty pending / failed / needs_review). Určené pre účtovné kancelárie, ktoré sledujú zavádzanie viacerých firiem; firmu určuje X-Organization-Id. Volanie nič nezapisuje. Stav platby vidí len zakladateľ firmy alebo partnerský kľúč, blok bank vyžaduje aj rozsah bank:read a pending_mandate sa vyhodnocuje len pre partnerský kľúč — inak sú tieto hodnoty null.
2026-09-18Nové
  • POST /v1/agent/invoices: nové pole due_date (YYYY-MM-DD) ako priama alternatíva k due_days (obe naraz vrátia 400; due_date nesmie byť pred issue_date). Nová hodnota payment_method "online" (online platobná služba, napr. PayPal). Spôsob platby sa odteraz prenáša do Peppol UBL ako PaymentMeansCode podľa UNCL4461 (bank_transfer 30, cash 10, card 48, online 68, offset 97) — predtým išiel vždy kód 30. Bankový účet (IBAN/BIC) ostáva v PaymentMeans pri každom kóde, ak je na doklade uvedený.
  • Prílohy faktúr (attachments pri POST /v1/agent/invoices, POST /v1/agent/invoices/:id/attachments aj nahrávanie v aplikácii): okrem PDF/JPG/PNG sú povolené aj CSV, XLSX a ODS — presne zoznam MIME typov, ktoré Peppol BIS 3.0 dovoľuje vložiť do e-faktúry. DOC/DOCX/XLS/GIF sieť Peppol nedoručí, konvertujte ich na PDF.
2026-09-17Vylepšenie
  • GET /v1/agent/peppol/events: natívne doklady (aplikácia, POST /send), ktoré zlyhali ešte pred odoslaním do siete Peppol (schematron, oprávnenosť, kredit, príjemca), sú v auditnej stope ako sent.failed s časom zlyhania a číslom dokladu v detaile. Každý export dát (táto auditná stopa, export faktúr, dokladov, Peppol XML, účtu a CSV audit logu organizácie) sa navyše sám zapisuje do auditného logu organizácie ako data.export; audit log organizácie má v eDoklade export do CSV.
2026-09-13Vylepšenie
  • GET /v1/agent/dashboard/summary: nový parameter period prijíma okrem mesiaca YYYY-MM aj typ obdobia week | month | quarter | year (ISO týždne od pondelka) a anchor (YYYY-MM-DD, predvolene dnešok v Europe/Bratislava); bez period = aktuálny mesiac. Odpoveď pridáva period_range { type, start, end, label } a sumy bez DPH revenue_total_net, revenue_outstanding_net a outstanding_amount_net (čistá suma per doklad, dobropisy so znamienkom). Existujúce polia sa nemenia.
2026-09-08Nové
  • Prijaté doklady v Agent API: GET /v1/agent/peppol/received/:id (metadáta vrátane SBDH identifikátorov, SHA-256 UBL, zoznam príloh, odkazy), POST …/acknowledge (idempotentné potvrdenie prevzatia, filter ?acknowledged=false proti dvojitému spracovaniu) a GET …/evidence (dôkaz o prijatí s odoslaným MLS a jeho AS4 message id). Zoznam GET /received navyše vracia acknowledged_at, sbdh_instance_id, attachments_count a is_test.
  • GET /v1/agent/peppol/events: exportovateľná auditná stopa odoslaných aj prijatých dokladov (zaradenie, AS4 potvrdenie, odloženie, zlyhanie, MLS doručené/odmietnuté, prijatie, odoslaný MLS, potvrdenie prevzatia) s časom, výsledkom, AS4 message id, SBDH InstanceIdentifier a SHA-256 UBL; JSON alebo CSV, okno from/to.
2026-08-20Nové
  • Modul Zmluvy v Agent API (/v1/agent/contracts): zoznam, detail, vytvorenie, úprava, zmazanie, harmonogram platieb (vrátane označenia platby ako uhradenej), naviazané faktúry a opakované faktúry, štatistiky, AI extrakcia z PDF a prílohy. Scopes contract:read/create/update/delete; nové partnerské kľúče dostávajú read/create/update automaticky, staršie kľúče treba pregenerovať.
  • PATCH /v1/agent/invoices/:id: úprava obsahu faktúry (položky, dátumy, poznámky, bankový účet, linkovanie zmluvy…). Rovnaké pravidlá ako v aplikácii: stornované/archivované/zamknuté doklady sa upraviť nedajú, Peppol-odoslané len účtovné metadáta. Payload je camelCase (session tvar), voliteľný optimistický zámok cez pole version. Vyžaduje scope invoice:update.
  • Sprísnenie: USER-scoped API kľúče (efk_live_/efk_test_) sa teraz autorizujú prienikom scopes kľúča a oprávnení používateľa. Kľúč s obmedzenými scopes (napr. len invoice:read) už nedokáže vykonať zápisové operácie cez oprávnenia svojho vlastníka; least-privilege kľúče platia naozaj.
  • Zákazky (projekty) v Agent API: /v1/agent/projects (zoznam, vytvorenie s farbou, detail, úprava) a nové polia case_id na výdavkoch (vytvorenie, upload, úprava, filter zoznamu) + caseId na zmluvách. Doklady aj zmluvy tak viete tagovať zákazkou už pri vzniku. Pribudol aj branch_id na výdavkoch (predtým len branch_code pri uploade).
2026-08-01Nové
  • Idempotencia pri vytváraní dokladov: POST /v1/agent/invoices a POST /v1/agent/expenses prijímajú voliteľnú hlavičku Idempotency-Key. Opakovanie s rovnakým kľúčom aj telom vráti uloženú odpoveď (doklad sa nevytvorí druhýkrát, číslo radu sa neminie); rovnaký kľúč s iným telom vráti 409. Dôrazne odporúčané pre všetky retry mechanizmy.
  • POST /v1/agent/invoices/:id/send-reminder: opakované volanie do 10 minút už pripomienku neodošle znova, vráti 200 so sent:false namiesto duplicitného e-mailu zákazníkovi.
  • Opravy e-invoice validácie: opravný doklad (§25, UNTDID 384) si zachováva skutočné znamienko súm (predtým sa absolútnou hodnotou správal ako dobropis); dobropis bez DPH kategórie na riadku teraz správne padá na SK-BT-148; dedup prijatých dokladov zahŕňa typ dokladu (dobropis s rovnakým číslom ako faktúra sa už nezahodí ako duplikát).
2026-07-27Oprava
  • POST /v1/agent/expenses/scan-qr: parsovanie eKasa bločkov sa vzťahuje len na organizácie s fiskalizáciou SK (eKasa). Organizácie z iných krajín (napr. CZ) dostanú aj pre eKasa QR generický výsledok { type: "text", raw }.
2026-07-23Oprava
  • GET /v1/agent/expenses/:id/qr: generovaný Pay by Square QR kód už neobsahuje dátum splatnosti (bankové aplikácie ho predvypĺňali alebo platbu odmietali).
2026-07-22Vylepšenie
  • Telefónne číslo v inline customer objekte (POST /v1/agent/invoices) sa validuje ako E.164: oddeľovače a prefix 00 sa normalizujú, neplatné číslo vráti zrozumiteľnú 400 VALIDATION_ERROR (predtým neprehľadná 500 z DB constraintu).
2026-07-21Nové
  • Nová hodnota payment_method: "offset" (vzájomný zápočet) pri vytváraní faktúry, označení výdavku ako uhradeného aj zázname platby. Dobropisy sa dajú vysporiadať so zápornou sumou k úhrade (predtým sa orezávala na nulu).
  • POST /v1/agent/invoices/:id/send-reminder: podporovaný jazyk pripomienky "cs" (čeština), popri sk/en/de/hu.
2026-07-18Vylepšenie
  • Faktúry v stave pending_approval (čakajú na schválenie) sú blokované rovnako ako drafty: nemožno na ne poslať pripomienku ani ich označiť ako paid/cancelled; API vráti 400 s pokynom faktúru najprv vydať.
2026-07-14Vylepšenie
  • Vystavenie a úprava faktúry (POST/PATCH /v1/invoices): nové pole numberSeriesAction (voliteľné, "exception" | "advance") riadi počítadlo radu, keď customNumber (pri vystavení) alebo number (pri úprave) preskočí dopredu oproti radu. Neinteraktívne požiadavky bez numberSeriesAction spracuje API defaultne ako "exception": doklad si ponechá zadané číslo, ale počítadlo radu sa už automaticky neposunie (zmena správania, 2026-07). Agent API zatiaľ vlastné čísla dokladov nepodporuje. Pošlite "advance" pre obnovenie pôvodného správania (pokračovanie od zadaného čísla). Interaktívni (session) klienti namiesto defaultu dostanú 409 NUMBER_OUT_OF_SERIES s detailmi { typedNumber, expectedNext, nextIfException, nextIfAdvance, sequenceId, sequenceName, prefix }.
  • Doklady uložené so správaním "exception" nie sú naviazané na žiadny rad číslovania a nevytvárajú záznam v sequence_log: v diagnostike radov sa zobrazujú ako „čísla mimo radov" a je možné ich neskôr dodatočne prevziať do radu.
2026-06-26Nové
  • Onboarding na produkciu (FS webhook → potvrdenie e-mailom): firma si na portáli Finančnej správy zvolí eFaktúru ako poskytovateľa doručovania (PDS), FS pošle mandát webhookom a eFaktúra automaticky pošle firme potvrdzovací e-mail. Firma príjem e-faktúr potvrdí klikom na verejnej stránke (bez prihlásenia), tým sa naviaže na vašu child org na ostrom Peppole.
  • POST /agent/organizations/:id/peppol-claim: (re)poslanie FS potvrdzovacieho e-mailu pre org, ktorú kľúč už vlastní (scope invoice:send, NIE org:provision).
  • Verejná potvrdzovacia stránka pre partner-claim: token-only, bez prihlásenia firmy (anti-misrouting: potvrdzuje schránka firmy cez jej FS company_email).
  • Nová dokumentácia: Onboarding na produkciu a API kľúče a scopes.
2026-06-20Nové
  • Hromadné odoslanie cez Peppol: POST /agent/peppol/send/batch s telom { invoiceIds: [...] } (1–200 ID v jednom volaní).
  • Prílohy k faktúram cez API: pridanie, zoznam a odstránenie príloh (scope invoice:update).
  • Prijaté doklady cez API: stiahnutie originálneho PDF aj UBL XML faktúry (scope invoice:download).
2026-06-15Nové
  • Self-billing (samofakturácia): podpora profilu poacc:selfbilling:3.0 pre faktúry aj dobropisy.
2026-06-10Vylepšenie
  • Sandbox beží na reálnom phoss-ap-TEST na OpenPeppol TEST sieti: efk_pk_test_ odoslania idú reálnou Peppol TEST sieťou (nahradilo pôvodný in-process simulovaný Access Point). Stále bez kreditov a bez FS.
2026-05-31Nové
  • Partnerský portál: prehľad dokumentov (Dokumenty), odoslané a prijaté faktúry cez Peppol so stavmi dokladu aj prenosu, filtre a súhrn.
  • Partnerský portál: self-service sandbox API kľúče, prehľad API volaní (logy), zoznam klientskych organizácií.
  • Partnerský portál: prihlásenie partnera (e-mail + heslo) cez pozvánku od administrátora.
  • Developer portál spustený na developers.efaktura.sk vrátane API referencie (Scalar) a dokumentácie.
2026-05-30Nové
  • Sandbox: efk_pk_test_ odoslania fungujú okamžite bez konfigurácie na Peppol TEST prostredí, žiadne kredity ani FS.
  • Sandbox routing podľa tieru kľúča (test/live) na rovnakej base URL (Stripe model).