https://zk.postar-cloud.sk/sapiZáväzným popisom štandardnej plochy je zverejnená špecifikácia SAPI-SK 1.0.0; záložka „SAPI-SK" ju zobrazuje bez zmeny obsahu, len s našou adresou servera. Táto stránka dopĺňa to, čo štandard neurčuje: ako u nás vzniká kľúč, aké sú limity a aké rozšírenia ponúkame nad rámec štandardu.
| Plocha | Základná adresa | OpenAPI |
|---|---|---|
| SAPI-SK 1.0.0 (štandard) | https://zk.postar-cloud.sk/sapi | openapi.json |
| SAPIPlus v1.0.0 (rozšírenia) | https://zk.postar-cloud.sk/sapi/plus/v1 | openapi.json |
Adresa servera zahŕňa prefix /sapi. Cesty zo špecifikácie
(/auth/token, /document/send, …) sa pripájajú za
https://zk.postar-cloud.sk/sapi, napríklad https://zk.postar-cloud.sk/sapi/auth/token.
Prefix sa medzi poskytovateľmi líši (/sapi, /sapi/v1, /api/sapi, …),
preto ho v ERP nastavujte ako súčasť základnej adresy, nie ako pevnú časť kódu.
Štandardná plocha /sapi/ nedostáva nové cesty. Všetko nad rámec
špecifikácie žije v /sapi/plus/v1/ s vlastným verzovaním v ceste.
| Prostredie | Adresa | Peppol sieť | Kľúč |
|---|---|---|---|
| Produkcia | https://zk.postar-cloud.sk | produkčná (SML) | kľúč založený v produkčnom portáli |
Testovacie a produkčné prostredie sú oddelené inštancie s vlastným Access Pointom a vlastnou databázou. Kľúč, token aj webhooky platia len v inštancii, kde vznikli; rovnaké rozhranie, iná adresa a iný kľúč. Doklad odoslaný v teste nikdy neopustí testovaciu sieť. O prístup do testovacieho prostredia požiadajte na podpora@postar-cloud.sk.
client_secret sa zobrazí jediný raz.pending a POST /sapi/auth/token ho odmieta
(401, SAPI-AUTH-002), kým ho neschváli správca Postar-Cloud.
Schváliť sa dá len kľúč s vyplneným allow-listom.Registračný endpoint v SAPI zámerne nie je — špecifikácia ho nemá.
OAuth 2.0 client_credentials: JWT access token s platnosťou 15 minút, refresh token
na 30 dní. Refresh je jednorazový — pri obnove sa starý pár zneplatní. Token nesie všetky oprávnenia
kľúča; pole scope v požiadavke sa ignoruje (rozsah je uvedený v odpovedi). Ak potrebujete
obmedziť, čo smie konkrétny systém alebo proces, založte mu samostatný kľúč.
IP sa overuje na dvoch úrovniach: allow-list kľúča pri vydaní tokenu a väzba samotného
access tokenu na IP, z ktorej bol vydaný. Zmena adresy znamená nový access token cez
/sapi/auth/renew, nie nové prihlásenie — pokiaľ je nová adresa v allow-liste.
Každá chybová odpoveď SAPI aj SAPIPlus má tvar { "error": SAPIError } zo špecifikácie:
category, stabilný code, message, voliteľné details
s konkrétnym poľom, retryable a correlation_id. To isté ID je v hlavičke
X-Correlation-Id každej odpovede — pri kontaktovaní podpory ho uveďte. Opakujte len pri
retryable: true, s exponenciálnym odstupom.
| Kód | HTTP | Situácia |
|---|---|---|
SAPI-AUTH-001 | 401 | chýbajúci, neplatný, exspirovaný alebo zneplatnený token; neplatné prihlasovacie údaje |
SAPI-AUTH-002 | 401 | kľúč nie je schválený, je pozastavený alebo zrušený |
SAPI-AUTH-003 | 403 | IP mimo allow-listu kľúča alebo token vydaný pre inú IP |
SAPI-AUTH-004 | 403 | kľúč nemá scope pre operáciu |
SAPI-AUTH-005 | 403 | participant nepatrí firme kľúča |
SAPI-AUTH-006 | 423 | 5 neúspešných pokusov o prihlásenie, zámok na 15 minút |
SAPI-AUTH-007 | 403 | firma neprijala podmienky siete Peppol |
SAPI-AUTH-008 | 403 | firma nie je overená pre odosielanie alebo chýba senderPerson |
SAPI-VAL-001 | 400/422 | telo alebo parametre nezodpovedajú schéme — details menuje každé chybné pole |
SAPI-VAL-002 | 400 | chýba Idempotency-Key |
SAPI-VAL-003 | 400 | X-Peppol-Participant-Id sa nezhoduje s metadata.senderParticipantId |
SAPI-VAL-004 | 400 | checksum nesedí s obsahom payload |
SAPI-VAL-005 | 400 | payload nad 10 MB |
SAPI-VAL-006 | 400 | payload nie je dobre formované UTF-8 XML |
SAPI-VAL-007 | 400 | neplatný pageToken |
SAPI-VAL-404 | 404 | doklad neexistuje alebo nepatrí firme kľúča |
SAPI-PROC-001 | 409 | Idempotency-Key už bol použitý s iným obsahom |
SAPI-PROC-500 | 500 | neočakávaná chyba servera (retryable: true) |
SAPI-TEMP-001 | 429 | viac než 60 požiadaviek za minútu z jednej IP (Retry-After: 60) |
SAPI-TEMP-002 | 503 | Access Point dočasne nedostupný; doklad je uložený — zopakujte s tým istým Idempotency-Key |
SendDocumentRequest: metadata so šiestimi povinnými poľami,
payload ako UBL XML v UTF-8 (nie base64), payloadFormat: "XML", voliteľne
checksum (SHA-256 bajtov payload, malými písmenami).senderPerson (rozšírenie SAPIPlus): meno a priezvisko
osoby, ktorá doklad vo vašom systéme odosiela, napr. "senderPerson": "Jana Nováková".
Štandard SAPI-SK identifikáciu osoby nemá; bez nej doklad neodíde.202: ACCEPTED znamená technické prevzatie a odovzdanie Access Pointu,
nie doručenie príjemcovi. REJECTED nesie navyše reason
(layer, message) — napríklad príjemca nie je v sieti Peppol; doklad treba opraviť
a poslať s novým kľúčom.Idempotency-Key je povinný a platí 24 hodín. Rovnaký kľúč s rovnakým obsahom vráti pôvodnú
odpoveď, s iným obsahom 409. Po 24 hodinách je kľúč voľný.503 s retryable: true. Doklad je
uložený; zopakovanie s tým istým kľúčom ho odošle bez duplicity.metadata.senderParticipantId musí byť participant firmy kľúča. Slovenská firma je
0245:DIČ; starší tvar 9950:SK{DIČ} sa berie ako ten istý subjekt.CustomizationID), nie z
documentTypeId/processId v metadátach — self-billing teda netreba osobitne označovať.GET /sapi/document/receive vracia prijaté faktúry a dobropisy od najstaršieho,
stránkované kurzorom pageToken (limit 1–100, predvolene 20). Odoslané prenosy,
MLS ani SK TDD hlásenia v ňom nie sú — tie sú v SAPIPlus inboxe.RECEIVED/ACKNOWLEDGED a filter status platia za
kľúč: dva systémy jednej firmy (napr. ERP a sklad) si doklad preberajú nezávisle.payload tak, ako prišiel zo siete. Čítanie doklad nepotvrdzuje;
potvrdenie je idempotentné a opakované vráti čas prvého.| Téma | Špecifikácia | Táto inštancia |
|---|---|---|
X-Peppol-Participant-Id | povinná hlavička určujúca firmu | firmu určuje kľúč (jeden kľúč = jedna firma); ak hlavička príde, musí patriť firme kľúča, inak 403/400 |
metadata.documentId prijatého dokladu | identifikátor dokladu | náš providerDocumentId — dá sa priamo použiť v ceste detailu a potvrdenia; číslo faktúry je v poli documentNumber |
| Doklad inej firmy | 403 | 404 — neprezrádza, že doklad existuje |
scope pri POST /auth/token | voliteľné pole na vyžiadanie užšieho rozsahu | ignoruje sa; token dostane vždy všetky oprávnenia kľúča a vypíše ich v poli scope odpovede. Na oddelenie systémov alebo procesov použite samostatné kľúče — každý má vlastné oprávnenia, allow-list IP, log volaní a stav potvrdenia prijatých dokladov a dá sa samostatne pozastaviť |
| Osoba odosielateľa | nepozná — token identifikuje softvér, nie človeka | povinné rozšírenie SAPIPlus senderPerson v tele document/send: meno a priezvisko osoby, ktorá doklad vo vašom systéme odosiela. Vyžaduje ho overenie odosielateľa (FAQ Finančnej správy č. 73). Bez neho je odoslanie 403, SAPI-AUTH-008. |
| Polia navyše | — | zoznam a detail prijatého dokladu nesú aj providerDocumentId, status, receivedAt, documentNumber, acknowledgedDateTime; REJECTED nesie reason; token aj refresh_token. Klient, ktorý ich nepozná, ich môže ignorovať. |
| Operácia | Scope | Na čo |
|---|---|---|
GET /sapi/plus/v1/inbox | plus:inbox | stránkovaný prehľad prenosov s filtrami direction, status, kind, from, to |
GET/POST /sapi/plus/v1/webhooks, DELETE …/{id} | plus:webhooks | udalosti document.received, transmission.status_changed a invoice_response.received (odberateľ prijal, odmietol alebo uhradil váš doklad) na vašu HTTPS adresu |
GET /sapi/plus/v1/document/send/{providerDocumentId}/status | document:send | stav odoslaného dokladu: ACCEPTED, SENT, DELIVERED, REJECTED, VALIDATION_FAILED, SEND_FAILED, DELIVERY_UNCERTAIN; s MLS od príjemcu, stavom SK TDD hlásenia a odpoveďou odberateľa (Invoice Response: prijaté, odmietnuté, uhradené…) |
POST /sapi/plus/v1/document/validation | document:send | validácia UBL bez odoslania — tá istá Peppol BIS validácia ako pri odoslaní, chyby s ruleId a XPath |
GET /sapi/plus/v1/participants/{participantId} | document:send | je príjemca v sieti Peppol a čo vie prijať (faktúra, dobropis, self-billing, Invoice Response, MLS) |
Cesty stavu, validácie a lookupu majú názvy z návrhu rozšírení SAPI-SK, ktorý pripomienkujú
slovenskí poskytovatelia. Ak ich štandard prijme, presunú sa pod /sapi/ bez zmeny tvaru.
Doručenie webhooku je HTTP POST s JSON telom a hlavičkami X-Postar-Event,
X-Postar-Delivery a X-Postar-Signature: sha256=<hex> — HMAC-SHA256
tela kľúčom secret z registrácie. Overenie podpisu v PHP:
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_POSTAR_SIGNATURE'] ?? '')) {
http_response_code(400);
exit;
}
Neúspešné doručenie sa opakuje s rozostupmi 1 min → 5 min → 30 min → 2 h → 12 h, potom končí; posledná chyba je viditeľná v zozname webhookov.
Rozpracované funkcie a navrhované zmeny štandardu SAPI-SK, ktoré u nás ešte nebežia. Dokumentujeme len to, čo beží. Keď štandard vyjde v novej verzii, táto stránka ju zobrazí a zmena bude v histórii nižšie.
| Dátum | Zmena |
|---|---|
| 2026-10-22 | SAPIPlus v1: Invoice Response od odberateľa sa páruje na odoslaný doklad — v stave dokladu (invoiceResponse, invoiceResponseHistory) a ako webhook invoice_response.received. |
| 2026-10-22 | SAPIPlus v1: stav odoslaného dokladu (GET /document/send/{providerDocumentId}/status), validácia bez odoslania (POST /document/validation) a lookup účastníka (GET /participants/{participantId}), všetky so scope document:send. |
| 2026-10-22 | Zosúladenie so SAPI-SK 1.0.0: document/send prijíma SendDocumentRequest a vracia 202 SendDocumentResponse; príjem s kurzorom pageToken a stavom za kľúč; idempotentné potvrdenie; chyby ako {error: SAPIError} aj v SAPIPlus; 409 pri opakovanom kľúči s iným obsahom; 503 s opakovaním pri nedostupnom AP. Predchádzajúce vlastné tvary (sender_id, payload_xml_base64, document_id) už neplatia. Verejná dokumentácia na /sapi/docs. |
| 2026-08-12 | SAPIPlus v1: webhooky document.received, transmission.status_changed; stránkovaný inbox. |
| 2026-08-10 | Štandardná plocha /sapi/ podľa SAPI-SK 1.0.0; prehľad volaní SAPI pre zákazníka v portáli. |
Otázky k integrácii: podpora@postar-cloud.sk.