SAPI-SK pre vývojárov

Čo je SAPI-SK

SAPI-SK je národné REST rozhranie medzi klientskym systémom (ERP, e-shop, účtovný softvér) a Access Pointom. Cieľom je jednotný, dodávateľsky nezávislý spôsob, ako cez „digitálneho poštára“ odosielať a prijímať doklady — namiesto proprietárneho API každého poskytovateľa. Podporu SAPI-SK preto vnímajte ako poistku proti vendor lock-inu.

Autentifikácia

Používa sa OAuth2 client_credentials. Z portálu si vytvoríte API token — jeho UUID slúži ako client_id a hodnota vpt_… akoclient_secret. Cez POST /sapi/auth/token získate krátkodobý access token a refresh token; access token potom posielate v hlavičke Authorization: Bearer …. Zrušenie API tokenu v portáli okamžite zneplatní aj vydané tokeny.

Odoslanie a príjem

• Odoslanie: POST /sapi/document/send s hlavičkami pre cieľové Peppol ID a Idempotency-Key (bezpečné opakovanie bez duplicít).
• Príjem: GET /sapi/document/receive (stránkovanie, filter podľa stavu) a potvrdenie spracovania cez acknowledge.
• Stav tokenu / obnova / zrušenie: samostatné endpointy pod /sapi/auth/*.

Sandbox a idempotencia

Kontrakt si viete odskúšať v sandboxe bez rizika reálneho doručenia — sandbox validuje požiadavky a vracia mock odpovede. Pri odosielaní vždy používajte Idempotency-Key: pri opakovaní tej istej požiadavky (napr. po timeoute) nevznikne duplicitný doklad.

Kde nájdete detaily

Úplný zoznam endpointov, príklady požiadaviek/odpovedí a chybové kódy sú v našej technickej dokumentácii (sekcia SAPI-SK) vrátane strojovej OpenAPI 3.1 špecifikácie. Odporúčame začať v sandboxe a až potom prejsť na produkciu.