Plugin e1_ws_sapisk
Plugin aj dokumentácia generované pomocou AI
Elektronická fakturácia – SAPI‑SK – Standardised Access Point Interface (Slovakia)
Tento plugin umožňuje ERPIO One komunikovať so SAPI‑SK rozhraním (Peppol Access Point) podľa oficiálnej špecifikácie SAPI‑SK v1.0. Viac info https://www.sapi-sk.sk/docs
Elektronická fakturácia je spôsob výmeny faktúr medzi dodávateľom a odberateľom v štruktúrovanom dátovom formáte, ktorý je určený na automatizované spracovanie v účtovných a informačných systémoch. Používa sa najmä na odstránenie chýb, zrýchlenie spracovania a zníženie nákladov spojených s papierovou agendou.
V Európe sa využíva štandard UBL 2.1 / PEPPOL BIS, ktorý zabezpečuje jednotnú podobu faktúr medzi všetkými systémami. Komunikácia sa vykonáva cez tzv. Access Point, čo je certifikovaný sprostredkovateľ pre doručovanie dokumentov v Peppol sieti.
Výsledkom je bezpečné, rýchle a plne elektronické doručovanie faktúr medzi firmami aj verejnými inštitúciami.
Finančná správa v Slovenskej republike v spolupráci s odborníkmi zo siete Peppol a poprednými technologickými spoločnosťami pripravila jednotné technické riešenie pre elektronickú fakturáciu s názvom SAPI-SK. Hlavným cieľom je zjednotiť spôsob, akým budú firmy na Slovensku posielať a prijímať elektronické faktúry.
🧩 1. Prehľad pluginu
Plugin umožňuje:
✔ Odosielanie UBL dokumentov
- faktúr (Invoice)
- dobropisov (CreditNote)
✔ Prijímanie dokumentov
- zoznam prijatých
- detail dokumentu
- potvrdenie prijatia (Acknowledge)
✔ Správu tokenu
- získanie tokenu
- obnova tokenu
- revokácia tokenu
- kontrola platnosti tokenu
✔ Generovanie UBL XML (novinka)
- nový samostatný model UBL Generator
- generuje UBL podľa parametrov používateľa
- výstup vie automaticky uložiť do databázy
✔ Generate & Send (novinka)
- jedným krokom vygeneruje UBL + odošle do Peppol
🧭 2. Modely v plugine
Plugin obsahuje dva modely:
2.1 SAPI‑SK Web Service
SYSNAME: e1_ws_sapisk
Používa sa na:
- odosielanie dokumentov,
- prijímanie dokumentov,
- získanie detailu,
- potvrdenie,
- práca s tokenom,
- Generate & Send.
2.2 UBL Generator
SYSNAME: e1_ws_sapisk_ublgen
Používa sa na:
- tvorbu UBL dokumentu (Invoice/CreditNote),
- uloženie XML do DB pomocou
SQLcmd, - dávkové generovanie.
🧾 3. Základné parametre modelu SAPI‑SK Web Service
| Parameter | Povinné | Popis |
|---|---|---|
| @BaseUrl | nie | Adresa SAPI. Default: https://www.sapi-sk.sk (viditeľná v UI). |
| @ClientId | áno | Vydaný SAPI‑SK identifikátor. |
| @ClientSecret | áno | Heslo k ClientId. |
| @ParticipantId | pri prijímaní | Peppol ID príjemcu („pre koho dokumenty sťahujem“). |
| @SenderParticipantId | pri odoslaní | Peppol ID odosielateľa. |
| @ReceiverParticipantId | pri odoslaní | Peppol ID príjemcu. |
| @DocumentId | podľa akcie | ID dokumentu (napr. číslo faktúry). |
| @Document | pri send | XML text dokumentu. |
| @Mode | voliteľné | tokenstatus → kontrola stavu tokenu. |
Poznámka:@BaseUrl má default nastavenie → používateľ vidí hneď správnu hodnotu bez nutnosti ju dopĺňať.
4. Akcie modelu SAPI‑SK
4.1 SendDocument (odoslanie UBL)
Používa sa pri odosielaní faktúry/dobropisu.
Potrebné parametre:
@ClientId,@ClientSecret@SenderParticipantId,@ReceiverParticipantId@DocumentId@Document(XML)
Výsledok:
– úspech → 202 ACCEPTED
– chyba → plugin zobrazí text chyby
4.2 AcknowledgeDocument (potvrdenie prijatia)
Po stiahnutí dokumentu cez Receive.
Potrebné parametre:
@ClientId,@ClientSecret@ParticipantId@DocumentId
4.3 RenewToken
Vstup:
@RefreshToken
Výstup:
- tabuľka s novým access tokenom
4.4 RevokeToken
Vstup:
@RevokeToken
Výstup:
- potvrdenie revokácie (success/message)
4.5 TokenStatus
Režim sa aktivuje nastavením:
@Mode = tokenstatus
Buď:
@AccessToken,
alebo@ClientId,@ClientSecret.
Výstup: platnosť tokenu, zostávajúci čas, odporúčaný refresh.
4.6 Generate & Send
Robí 2 veci:
- Vygeneruje UBL dokument (Invoice/CreditNote) podľa parametrov.
- Okamžite ho odošle cez Peppol.
Parametre
Obsahuje všetky parametre UBL generátora (viď nižšie) + parametre send akcie.
Výhodné pre:
- odosielanie faktúr priamo z ERP interakcie,
- keď nechcete pracovať s XML,
- rýchly import → rýchly export.
Výstup:
Tabuľka:
| Pole | Popis |
|---|---|
| action | "GenerateAndSend" |
| status | "ACCEPTED" |
| documentId | ID odoslaného dokumentu |
| baseUrl | použitá adresa AP |
| senderParticipantId | Peppol ID odosielateľa |
| receiverParticipantId | Peppol ID príjemcu |
5. Čítacie operácie
5.1 Receive list – zoznam prijatých
Stačí:
@ClientId
@ClientSecret
@ParticipantId
Výstup: tabuľka dokumentov + nextPageToken
5.2 Receive detail – detaily dokumentu
Ak zadáš @DocumentId, plugin automaticky zavolá detail.
Výstup obsahuje:
- metadáta dokumentu
- XML obsah (payload)
🧩 6. Model UBL Generator
Samostatný model pre generovanie UBL XML.
6.1 Použitie
- generovanie faktúr/dobropisov
- príprava dát pre plugin Generate & Send
- dávková tvorba UBL z dát
- automatické uloženie UBL do DB cez SQLcmd
6.2 Parametre UBL generátora
Základné údaje:
| Parameter | Povinné | Popis |
|---|---|---|
| @DocumentKind | áno | "Invoice" alebo "CreditNote" |
| @DocumentId | áno | ID dokumentu |
| @IssueDate | áno | Dátum vystavenia |
| @Currency | áno | Mena (napr. EUR) |
Dodávateľ:
| Parameter | Povinné |
|---|---|
| @SupplierName | áno |
| @SupplierPeppolId | nie |
| @SupplierCompanyId | nie |
| @SupplierVatId | nie |
Odberateľ:
| Parameter | Povinné |
|---|---|
| @CustomerName | áno |
| @CustomerPeppolId | nie |
| @CustomerCompanyId | nie |
| @CustomerVatId | nie |
Profilové parametre (predvolené BIS 3.0):
| Parameter | Povinné | Default |
|---|---|---|
| @CustomizationId | nie | BIS 3.0 |
| @ProfileId | nie | BIS 3.0 |
| @DocumentTypeId | nie | podľa DocumentKind |
| @ProcessId | nie | = ProfileId |
Položky (JSON):
@LinesJson
Príklad:
JSON
[
{ “id”:”1″, “name”:”Licencia”, “quantity”:1, “unitPrice”:500, “vatRate”:20 },
{ “id”:”2″, “name”:”Podpora”, “quantity”:2, “unitPrice”:100, “vatRate”:20 }
]
6.3 Výstup generátora
Tabuľka: ubl_document
| Stĺpec | Popis |
|---|---|
| documentId | ID dokumentu |
| documentTypeId | Peppol Document Type ID |
| processId | Peppol Process ID |
| payloadFormat | XML |
| payloadEncoding | UTF‑8 |
| payload | UBL XML |
+ parameter @UBLResult
Po vygenerovaní plugin automaticky doplní do requestu:
@UBLResult = (obsah XML)
6.4 SQLcmd – automatické uloženie UBL
Stačí pridať do datasource SQLcmd, napr.:
SQL
INSERT INTO UblArchive (DocId, XmlPayload, CreatedOn)
VALUES (@DocumentId, @UBLResult, CURRENT_TIMESTAMP)
- SQLcmd sa vykoná po vygenerovaní UBL
- funguje aj v dávke (SetLarge)
- ak chceš použiť internú SQLite DB, pridaj parameter
__gwsqlinternal
🚀 7. Generate & Send — odporúčaný workflow
- Vyplníš parametre UBL (dodávateľ, odberateľ, položky).
- Vyplníš Peppol údaje (Sender/Receiver).
- Spustíš akciu Generate & Send.
- Plugin:
- vytvorí UBL,
- odošle ho cez SAPI,
- vráti status.
Používa sa v praxi najčastejšie — bez práce s XML.
🔄 8. Dávkové spracovanie (SetLargeDataTable)
Funguje na oba modely:
8.1 SAPI‑SK model
(dávkové odosielanie, dávkové acknowledge, dávkové Generate & Send)
8.2 UBL Generator
(dávková tvorba UBL + voliteľné dávkové uloženie do DB)
V každom riadku vstupnej tabuľky vyplníš parametre → plugin vykoná akciu pre daný riadok.
📚 9. Technická príloha (stručne)
Tabuľky, ktoré plugin vracia:
sapi_receive_listsapi_receive_detailauth_tokenauth_token_statusauth_revokegenerate_and_send_statusubl_document
Token volania:
- všetky chránené operácie →
Bearer <access_token> - send →
Idempotency-Key: GUID - každé receive/ack →
X-Peppol-Participant-Id
BaseUrl skladanie:
@BaseUrl + /sapi/auth/token
@BaseUrl + /sapi/document/send
...
Interný log:
Plugin má vlastnú log tabuľku v internej SQLite DB – pe1_ws_sapisk_log.
🎯 10. Zhrnutie
- Plugin obsahuje plnú implementáciu SAPI‑SK podľa špecifikácie.
- K tomu má samostatný UBL Generator — pre generovanie XML.
- A praktickú akciu Generate & Send — pre rýchle odoslanie.
@BaseUrlmá predvolenú hodnotu viditeľnú v UI.@UBLResultumožňuje jednoducho uložiť XML do DB.- Všetko funguje aj v dávkach cez akciu typu Datarepeater (pump).