API pre vývojárov

REST rozhranie iPoštár pre účtovný softvér a ERP. Odosielate a prijímate e-faktúry cez sieť Peppol (EN 16931 / Peppol BIS Billing 3.0) — podpis AS4 a doručenie rieši náš prístupový bod, vy komunikujete jednoduchým HTTPS/JSON+XML.

Pre zákazníkov: napojenie na iPoštár je otvorené štandardné REST API (Peppol BIS, obyčajné HTTPS) — zvládne ho ktorýkoľvek účtovný softvér či ERP, integrácia je otázka hodín. Ak vám dodávateľ softvéru tvrdí, že „iPoštár nepodporuje", pošlite mu tento odkaz — niet čo nepodporovať, je to pár volaní nižšie. Navyše e-faktúry sú podľa EN 16931 / Peppol, takže to nie je žiadny náš proprietárny formát.

Obsah Autentifikácia Odoslanie faktúry Stav & archív QR platby Príjem (schránka)Účet Chyby Účtovné kancelárie Operátori

Autentifikácia

Každá požiadavka nesie hlavičku X-API-Key s kľúčom účtu (zákazník si ho vygeneruje v zákazníckej zóne). Základ URL: https://ipostar.app/api/v1. Komunikácia výhradne cez HTTPS.

curl https://ipostar.app/api/v1/account \
  -H "X-API-Key: ipk_vas_kluc"

Nový účet je v sandbox režime — doklady sa nedoručujú do siete Peppol, ale simulovane do schránky v iPoštári: pošlite ich na vlastné DIČ (0245:<vaše DIČ> — uvidíte ich v „Prijaté“) alebo na testovacieho príjemcu 0245:9999999999 (iPoštár SANDBOX). Doklad skončí SENT s mls_status AB a dôvodom „SANDBOX: simulované doručenie“; iný príjemca skončí FAILED s vysvetlením v poli error. Nič sa neúčtuje a nič nejde Finančnej správe. Produkčné odosielanie sa odomkne po výbere iPoštára na Finančnej správe a aktivácii účtu.

Odoslanie faktúry

Metóda	Endpoint	Popis
POST	`/invoices`	Odošle UBL Invoice alebo CreditNote (BIS Billing 3.0).

Telo = surové UBL XML, Content-Type: application/xml. Pred odoslaním prebehne plná validácia (XSD + Peppol schematron); nevalidný dokument sa neodošle.

curl -X POST https://ipostar.app/api/v1/invoices \
  -H "X-API-Key: ipk_vas_kluc" \
  -H "Content-Type: application/xml" \
  --data-binary @faktura.xml

Odpoveď:

{ "id": 1234, "status": "QUEUED", "invoiceRef": "FA-2026-0007",
  "sandbox": false, "billing": "bundle", "balanceCents": 9700 }

Autorizačný model: odosielateľ v UBL (AccountingSupplierParty / endpoint) musí byť autorizovaný participant tohto kľúča (vaše DIČ, 0245:DIČ). Faktúru „za iného" systém odmietne (HTTP 403).

Stav a archív odoslaných

Metóda	Endpoint	Popis
GET	`/invoices`	Zoznam odoslaných (stav, MLS, dátumy).
GET	`/invoices/{id}`	Detail jedného dokladu + stav doručenia: `status` (QUEUED / SENDING / SENT / FAILED), pri zlyhaní `error` (dôvod), `mls_status` / `mls_reason` (MLS od príjemcu, v sandboxe simulované), `sandbox`, `doc_type`.
GET	`/stats`	Mesačné štatistiky (počty, spotreba).

Stav prechádza QUEUED → SENDING → SENT; doručenie/odmietnutie nesie MLS (mls_status AP/AB/RE s dôvodom).

QR platby s okamžitou notifikáciou (NOP)

iPoštár je napojený na Notifikátor okamžitých platieb Finančnej správy (NOP). Týka sa platieb iPoštárovi: pri dobití kreditu cez PAY by square QR kód (zóna aj operátorská zóna) nesie QR identifikátor platby QR-…; po úhrade banka pošle notifikáciu a kredit sa pripíše automaticky do pár sekúnd, bez čakania na výpis. Vaše vlastné faktúry a ich QR kódy sa tým nemenia — NOP je viazaný na certifikát a pokladnicu príjemcu platby.

Príjem — doručená schránka

Príjem e-faktúr je neobmedzený a beží vždy. Doklady doručené na vaše participanty sú v schránke.

Metóda	Endpoint	Popis
GET	`/inbox`	Zoznam prijatých (filtre `q`, `from`, `to`, `limit`, `unreadOnly`).
GET	`/inbox/{id}`	Metadáta dokladu (označí prečítané).
GET	`/inbox/{id}/xml`	Originálne UBL XML (pre zaúčtovanie).
GET	`/inbox/{id}/pdf`	Čitateľný PDF náhľad.

Účet a kredit

Metóda	Endpoint	Popis
GET	`/account`	Profil, cena za doklad, stav.
PUT	`/account/notify-threshold`	Prah notifikácie ({"pct": 80}).
GET	`/credit/transactions`	Pohyby kreditu.
GET	`/notifications`	Notifikácie účtu.

Chybové odpovede

HTTP	Kód	Význam
401	—	Chýbajúci alebo neplatný `X-API-Key`.
403	`NOT_AUTHORIZED_PARTICIPANT`	Odosielateľ nie je autorizovaný participant kľúča (faktúra za cudzie DIČ).
403	`NO_SEND_PLAN`	Účet nemá balík na odosielanie (zvoľte iPoštár/službu OSTV). Príjem je zadarmo.
422	validácia	UBL neprešlo XSD/schematron — v tele zoznam chýb.
429	—	Prekročený rate limit.

Účtovné kancelárie — multi-DIČ

Jeden účet/kľúč môže mať priradených viac participantov (klientov). Každý klient prechádza vlastným onboardingom a FS autorizáciou; odosielateľ každej faktúry sa overuje voči zoznamu autorizovaných participantov kľúča. Limity a vyúčtovanie vieme viesť per klient aj súhrnne.

Operátori (veľkoobchod)

ISP a operátori majú samostatné partnerské API (/partner/v1/*, hlavička X-Partner-Key) na hromadnú registráciu firiem a výkazy spotreby. Compliance nemenné — FS autorizáciu robí vždy koncová firma, obsah dokladov operátor nevidí. Prístup zriaďuje iPoštár: support@ipostar.app.

Otázky k integrácii: support@ipostar.app. Sandbox na testy je zadarmo.