SAPI dokumentácia — Postar-Cloud

E-Works s.r.o., akreditovaný poskytovateľ doručovacej služby eFaktúra · základná adresa https://zk.postar-cloud.sk/sapi

Implementačné poznámky Postar-Cloud

Zá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.

Adresy

PlochaZákladná adresaOpenAPI
SAPI-SK 1.0.0 (štandard)https://zk.postar-cloud.sk/sapiopenapi.json
SAPIPlus v1.0.0 (rozšírenia)https://zk.postar-cloud.sk/sapi/plus/v1openapi.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.

Prostredia

ProstredieAdresaPeppol sieťKľúč
Produkciahttps://zk.postar-cloud.skprodukč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.

Kľúč a jeho životný cyklus

  1. Kľúč si vytvorí používateľ Postar-Cloud v portáli (Nastavenia → API kľúče): názov, rozsah oprávnení (scopes) a allow-list IP adries alebo CIDR rozsahov. client_secret sa zobrazí jediný raz.
  2. Nový kľúč je v stave 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.
  3. Kľúč koná za jednu pevne určenú firmu. Jeden token = jedna firma; hlavička na prepínanie firmy neexistuje. Pre ďalšiu firmu vzniká ďalší kľúč.
  4. Pozastavenie alebo zrušenie kľúča okamžite zneplatní aj vydané tokeny a umlčí jeho webhooky.

Registračný endpoint v SAPI zámerne nie je — špecifikácia ho nemá.

Tokeny a odmietnutia

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.

Chyby

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ódHTTPSituácia
SAPI-AUTH-001401chýbajúci, neplatný, exspirovaný alebo zneplatnený token; neplatné prihlasovacie údaje
SAPI-AUTH-002401kľúč nie je schválený, je pozastavený alebo zrušený
SAPI-AUTH-003403IP mimo allow-listu kľúča alebo token vydaný pre inú IP
SAPI-AUTH-004403kľúč nemá scope pre operáciu
SAPI-AUTH-005403participant nepatrí firme kľúča
SAPI-AUTH-0064235 neúspešných pokusov o prihlásenie, zámok na 15 minút
SAPI-AUTH-007403firma neprijala podmienky siete Peppol
SAPI-AUTH-008403firma nie je overená pre odosielanie alebo chýba senderPerson
SAPI-VAL-001400/422telo alebo parametre nezodpovedajú schéme — details menuje každé chybné pole
SAPI-VAL-002400chýba Idempotency-Key
SAPI-VAL-003400X-Peppol-Participant-Id sa nezhoduje s metadata.senderParticipantId
SAPI-VAL-004400checksum nesedí s obsahom payload
SAPI-VAL-005400payload nad 10 MB
SAPI-VAL-006400payload nie je dobre formované UTF-8 XML
SAPI-VAL-007400neplatný pageToken
SAPI-VAL-404404doklad neexistuje alebo nepatrí firme kľúča
SAPI-PROC-001409Idempotency-Key už bol použitý s iným obsahom
SAPI-PROC-500500neočakávaná chyba servera (retryable: true)
SAPI-TEMP-001429viac než 60 požiadaviek za minútu z jednej IP (Retry-After: 60)
SAPI-TEMP-002503Access Point dočasne nedostupný; doklad je uložený — zopakujte s tým istým Idempotency-Key

Odosielanie dokladov

Príjem dokladov

Odchýlky od špecifikácie

TémaŠpecifikáciaTáto inštancia
X-Peppol-Participant-Idpovinná hlavička určujúca firmufirmu určuje kľúč (jeden kľúč = jedna firma); ak hlavička príde, musí patriť firme kľúča, inak 403/400
metadata.documentId prijatého dokladuidentifikátor dokladunáš providerDocumentId — dá sa priamo použiť v ceste detailu a potvrdenia; číslo faktúry je v poli documentNumber
Doklad inej firmy403404 — neprezrádza, že doklad existuje
scope pri POST /auth/tokenvoliteľné pole na vyžiadanie užšieho rozsahuignoruje 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ľanepozná — token identifikuje softvér, nie človekapovinné 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ť.

SAPIPlus v1 v skratke

OperáciaScopeNa čo
GET /sapi/plus/v1/inboxplus:inboxstránkovaný prehľad prenosov s filtrami direction, status, kind, from, to
GET/POST /sapi/plus/v1/webhooks, DELETE …/{id}plus:webhooksudalosti 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}/statusdocument:sendstav 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/validationdocument:sendvalidá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:sendje 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.

Čo tu nenájdete

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.

História

DátumZmena
2026-10-22SAPIPlus 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-22SAPIPlus 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-22Zosú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-12SAPIPlus 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.