REST JSON APIOpenAPI 1.23.0Od balíka BIZ

ePoštár API & Sandbox pre ERP, e-shopy a softvéry

Prepojte svoj firemný softvér, e-shop alebo účtovný systém priamo s ePoštárom. Využite reálny dodávateľský sandbox, otestujte si integráciu bezpečne a pripravte svoje systémy na zákonnú e-fakturáciu včas.

Vyskúšať v Sandboxe OpenAPI špecifikácia ↓Dostupnosť v balíkoch BIZ, PRO, MAX →

Produkčný Base URL:https://api.efakturapro.sk/api/v1/integrations

integration-overview.json

// 1. Overenie pripojenia a oprávnení
GET /capabilities
Authorization: Bearer <API_KEY>

{
  "contractVersion": "1.23.0",
  "companyId": "comp_sk_94812",
  "plan": "BIZ",
  "capabilities": {
    "invoiceDrafts": true,
    "invoiceSubmit": true,
    "epostarSandbox": true,
    "sandboxMessageLevelStatuses": true,
    "automatedB2B": true
  }
}

🔒 Bezpečné kľúče viazané na firmu⚡ Ochrana pred duplicitami

🛠️

Odporúčanie pre softvérové domy & integrátorov

Využite náš ePoštár Sandbox a pripravte svoje systémy včas

Od 1. 1. 2027 sa elektronická fakturácia a štátne TDD hlásenia stanú povinnosťou pre slovenské B2B obchody. Nečakajte na poslednú chvíľu. V našom reálnom dodávateľskom sandboxe môžete svoje ERP, fakturačné systémy či e-shopy integrovať, overiť dátové štruktúry a otestovať celý životný cyklus dokladu bez rizika odoslania testovacích dát do ostrej produkčnej siete.

✓ Oddelená testovacia identita a kľúče✓ Testovacie odoslanie, príjem a import do nákladov✓ Plná simulácia MLS stavov a chybových odpovedí✓ Žiadny zásah do ostrého produkčného účtovníctva

Architektúra integrácie

Jasné oddelenie produkčného API, testovania a archívu

Každé tvrdenie preväzujeme s konkrétnou funkciou, overeným správaním a presnými mantinelmi.

Produkčné vystavovanie & riadená automatizácia

Produkčné API umožňuje vytvárať koncepty faktúr (POST /invoice-drafts) alebo priamo vystavovať doklady (POST /invoices) podľa vašej firemnej a ePoštár politiky.

Režim AUTO_B2B: Ak má odberateľ kompletné a platné B2B údaje, doklad pokračuje do automatického toku.
Režim MANUAL_REVIEW: Pri neúplných údajoch alebo neistote systém faktúru pripraví na kontrolu používateľom v aplikácii.
Režim DISABLED: Vystavenie prebehne v štandardnom režime bez elektronického Peppol odosielania.
Podrobné stavy: Odpoveď obsahuje presný stav dokladu, zoznam chýbajúcich polí a informáciu, či bol doklad odoslaný.

Mantinel pre produkčný príjem:

Príjem došlých e-faktúr v produkcii prebieha cez certifikovanú doručovaciu schránku aplikácie s okamžitým zápisom do archívu dôkazov a notifikáciami. Verejný neoverený API endpoint pre inbound nie je z bezpečnostných dôvodov vystavený (INTEGRATION_PRODUCTION_INBOUND_ENABLED=false).

Technická dokumentácia

Praktický integračný postup pre vývojárov

Jednoduchý 5-krokový tok od registrácie kľúča až po ostré odosielanie.

1Získanie kľúča

Vygenerujte API kľúč v nastaveniach firmy (balík BIZ, PRO alebo MAX) s potrebnými scopes.

2GET /capabilities

Overte dostupnosť funkcií, platnosť tokenu a rozsah priradených oprávnení.

3Test v Sandboxe

Vyskúšajte vytvorenie návrhu, validáciu chýb a spracovanie MLS stavov v testovacom prostredí.

4Idempotencia & retry

Nasaďte hlavičku Idempotency-Key a pravidlo: po timeoute najskôr overiť pokus cez GET.

5Produkčné nasadenie

Prepnite endpoint na produkčnú URL s produkčným kľúčom a sledujte doručenia.

// Požiadavka na vytvorenie návrhu faktúry (bez okamžitého odoslania)
POST https://api.efakturapro.sk/api/v1/integrations/invoice-drafts
Authorization: Bearer <API_KEY>
Idempotency-Key: 7b9a4c82-3d1e-45fa-a9f8-b83c21a48c91
Content-Type: application/json

{
  "client": {
    "name": "Partner Systems s.r.o.",
    "ico": "12345678",
    "dic": "2023456789",
    "icDph": "SK2023456789",
    "street": "Hlavná 45",
    "city": "Bratislava",
    "zip": "81101",
    "countryCode": "SK"
  },
  "items": [
    {
      "description": "Implementácia ERP mostíka ePoštár",
      "quantity": 1,
      "unit": "ks",
      "unitPrice": 450.00,
      "vatRate": 23
    }
  ],
  "paymentMethod": "TRANSFER",
  "currency": "EUR"
}

// Odpoveď HTTP 201 Created:
{
  "draftId": "drf_89214a",
  "status": "DRAFT",
  "effectiveState": "DRAFT",
  "totalAmount": 553.50,
  "vatAmount": 103.50,
  "validation": {
    "validForIssue": true,
    "missingFields": []
  }
}

Katalóg operácií

Prehľad verejných integračných endpointov

Všetky operácie sú autorizované cez Bearer token alebo X-API-Key a viazané na konkrétnu firmu.

Metóda	Cesta (Endpoint)	Popis	Potrebný Scope	Dostupnosť
GET	`/capabilities`	Overenie oprávnení, verzie kontraktu a stavu kľúča	Verejné pre platný kľúč	Produkcia
GET	`/company`	Načítanie firemných a bankových údajov	`company:read`	Produkcia
GET	`/number-formats`	Dostupné číselné rady a formáty dokladov	`company:read`	Produkcia
POST	`/invoice-drafts`	Vytvorenie konceptu faktúry bez vystavenia a zaúčtovania	`invoice:draft:create`	Produkcia
POST	`/invoices`	Vystavenie faktúry (režim Draft-to-Issue / v uvoľňovaní pre externý zápis)	`invoice:create`	V uvoľňovaní
GET	`/invoices/{id}`	Detail vystavenej faktúry a stavy doručenia	`invoice:read`	Produkcia
GET	`/invoices/{id}/pdf`	Stiahnutie uloženého aktuálneho PDF dokladu	`invoice:read`	Produkcia
POST	`/invoices/{id}/sk-epostar/submissions`	Odoslanie testovacej e-faktúry do Peppol sandboxu	`invoice:submit:sandbox`	Sandbox
GET	`/invoices/{id}/sk-epostar/submissions/{reqId}`	Overenie stavu odoslania u dodávateľa sandboxu	`invoice:submit:sandbox`	Sandbox
GET	`/invoices/{id}/sk-epostar/submissions/{reqId}/message-level-statuses`	Zoznam prijatých MLS stavov a chybových hlásení	`invoice:submit:sandbox`	Sandbox
GET	`/sk-epostar/inbox`	Načítanie prijatých testovacích dokladov v sandboxe	`document:receive:sandbox`	Sandbox
POST	`/sk-epostar/inbox/{aliasId}/acknowledge`	Potvrdenie prevzatia (ACK) prijatej testovacej faktúry	`document:ack:sandbox`	Sandbox

CENNÍK & KVÓTY PRE VÝVOJÁROV

Ceny balíkov s ePoštár API & počty e-faktúr v cene

API rozhranie a Sandbox sú bezplatnou súčasťou balíkov BIZ, PRO a MAX bez akýchkoľvek licenčných príplatkov. Každý balík zahŕňa neobmedzený príjem e-faktúr a transparentnú kvótu vystavených dokladov:

Základné API & Sklad

BIZ

10 €/ mesiac bez DPH

30 e-faktúr mesačne360 e-faktúr ročne v cene predplatného

✓ Neobmedzený príjem e-faktúr bez doplatku
✓ Plný prístup k ePoštár REST API & Sandboxu
✓ DPH evidencia, výpočet a priame podanie na FS SR
✓ Sklad, e-shop integrácie, eKasa a pokladňa
✓ OCR vyťažovanie faktúr a bločkov

Podrobnosti balíka BIZ →

Najobľúbenejšie pre integrátorov

PRO

15 €/ mesiac bez DPH

50 e-faktúr mesačne600 e-faktúr ročne v cene predplatného

✓ Neobmedzený príjem e-faktúr bez doplatku
✓ Všetko z BIZ + Jednoduché účtovníctvo (JÚ)
✓ Peňažný denník, evidencia majetku a záväzkov
✓ Smart položky, automatické párovanie platieb
✓ Sandbox Studio a pokročilé webhooky

Aktivovať balík PRO →

Podvojné účtovníctvo & ERP

MAX

20 €/ mesiac bez DPH

100 e-faktúr mesačne1 200 e-faktúr ročne v cene predplatného

✓ Neobmedzený príjem e-faktúr bez doplatku
✓ Všetko z PRO + Kompletné podvojné účtovníctvo (PÚ)
✓ Hlavná kniha, denník, súvaha, výsledovka a DP
✓ Najvyššia Fair Use kapacita pre API volania
✓ Prioritné spracovanie a archív dokladov

Podrobnosti balíka MAX →

💡 Účtovná kancelária alebo holding? Pre správu 100 až 500 firiem využite predplatné XXL pre účtovníkov (od 30 € bez DPH / mes.) so zdieľaným fondom. Ak vyčerpáte mesačné e-faktúry, kedykoľvek si môžete dokúpiť kreditový balíček (napr. 15 e-faktúr za 9,90 € na 12 mesiacov).

🛡️

Presné mantinely & SLA

Neuvádzame fiktívne neobmedzené volania. Každá požiadavka podlieha štandardným rate limitom, kontrole platnosti kľúča a oprávneniam podľa programu firmy.

Platnosť kľúča nastaviteľná s možnosťou okamžitého odvolania
Stránkovanie zoznamov s fixným limitom na požiadavku
Bezpečný timeout a striktná idempotencia

📦

Dostupnosť od balíka BIZ & Fair Use

API a Sandbox sú bezplatnou súčasťou balíkov BIZ, PRO a MAX bez dodatočných licenčných poplatkov. Rozsah testovania a volaní je viazaný na počet vystavených e-faktúr v balíku:

BIZ (10 € / mes.): 30 e-faktúr mesačne (360 ročne) + neobmedzený príjem
PRO (15 € / mes.): 50 e-faktúr mesačne (600 ročne) + JÚ účtovníctvo
MAX (20 € / mes.): 100 e-faktúr mesačne (1 200 ročne) + PÚ účtovníctvo
Viac testovania: Možnosť kedykoľvek dokúpiť kreditový balíček (napr. 15 e-faktúr za 9,90 € na 12 mesiacov)

🔄

Podpora a verzionovanie

Kontrakt dodržiava sémantické verzionovanie OpenAPI. Zmeny sú dopredu komunikované a spätná kompatibilita je prioritou.

Aktuálny stabilný kontrakt: 1.23.0
Podpora pre vývojárov: info@efakturapro.sk
Zdieľané príklady integrácie pre PHP, Node.js a Python

Časté otázky vývojárov

Všetko, čo potrebujete vedieť pred integráciou

V akých balíkoch je ePoštár Integration API dostupné a koľko stojí?

API rozhranie a Sandbox sú bezplatnou súčasťou predplatných BIZ (10 € / mes. – 30 e-faktúr mesačne / 360 ročne), PRO (15 € / mes. – 50 e-faktúr mesačne / 600 ročne) a MAX (20 € / mes. – 100 e-faktúr mesačne / 1 200 ročne). Príjem e-faktúr je vo všetkých týchto balíkoch úplne neobmedzený (0 €). Pre účtovné kancelárie a softvérové domy so správou desiatok firiem je k dispozícii predplatné XXL (od 30 € bez DPH / mes.).

Ako funguje ePoštár Sandbox a prečo ho odporúčame integrátorom?

Sandbox poskytuje samostatnú testovaciu identitu, oddelené testovacie API kľúče a dedikované prostredie. Žiadne testovacie faktúry neopustia sandbox do ostrej produkčnej siete Peppol ani Finančnej správy. V sandboxe si overíte vytvorenie dokladu, testovacie odoslanie, príjem, archiváciu, import do nákladov, ACK potvrdenie aj MLS (Message Level Status) stavy. Sandbox poskytujeme zadarmo od balíka BIZ (10 € / mes.), pričom testovací objem sa riadi pravidlom Fair Use naviazaným na počet vystavených e-faktúr v balíku (30 mes. / 360 rok v BIZ, 50 mes. / 600 rok v PRO, 100 mes. / 1 200 rok v MAX) alebo na zakúpené kredity.

Aký je rozdiel medzi vytvorením návrhu (draft) a vystavením faktúry?

Endpoint POST /invoice-drafts vytvorí bezpečný koncept bez okamžitého vystavenia, odoslania, zaúčtovania či pohybu na sklade. Slúži na validáciu a predprípravu údajov. Endpoint POST /invoices následne riadi vystavenie podľa zvoleného režimu automatizácie (AUTO_B2B, MANUAL_REVIEW, DISABLED).

Ako funguje ochrana pred duplicitami (idempotencia) a čo robiť pri timeoute?

Každá požiadavka na vytvorenie alebo odoslanie dokladu podporuje hlavičku Idempotency-Key. Dôležité pravidlo: sieťový timeout automaticky neznamená neúspech operácie! Po vypršaní časového limitu je potrebné najskôr overiť stav pôvodného pokusu cez GET endpoint, namiesto bezhlavého opakovaného odosielania novej požiadavky.

Prečo rozlišujeme stavy spracovania a nespájame ich do jedného „úspešné“?

Elektronická fakturácia má niekoľko samostatných fáz: 1. Prijatie požiadavky serverom (HTTP 202/200), 2. Odovzdanie doručovacej službe, 3. Doručenie do schránky príjemcu, 4. Aplikačné potvrdenie MLS a 5. Reportovanie daňových dát TDD na Finančnú správu SR. Naše API tieto stavy striktne oddeľuje a vracia konkrétne overiteľné údaje.

Ako sa zmení správanie TDD od 1. 1. 2027?

V roku 2026 prebieha dobrovoľné prechodné obdobie. Povinné hlásenie daňových údajov (TDD) Finančnej správe SR štartuje 1. 1. 2027. Potvrdenie štátneho TDD sa sleduje na nezávislej linke a nie je podmienkou splnenia povinnosti vystavenia a odoslania faktúry odberateľovi.

Sú cez API kľúč dostupné priame webhooky pre každú udalosť?

V produkčnom rozhraní sú podporované overené udalosti: client.created, client.updated, invoice.created, invoice.draft.created a payment.created. Stav ePoštár doručenia a spracovania sa sleduje cez autorizované stavové endpointy. Taktiež príjem došlých e-faktúr v produkcii prebieha cez zabezpečené interné toky aplikácie s ochranou archívu, nie cez verejný neoverený webhook.

Pripravte svoj softvér na e-fakturáciu už dnes

Zaregistrujte si účet, vyskúšajte interaktívne Sandbox Studio a integrujte svoje systémy bez stresu pred rokom 2027.

Otvoriť Sandbox Studio zadarmo Sprievodca ePoštárom a Peppolom