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čkou X-Peppol-Participant-Id (účastník, ZA ktorého odosielate: vaša firma alebo klient pod vaším tokenom; príjemca sa uvádza v metadátach dokumentu) a Idempotency-Key (bezpečné opakovanie bez duplicít). Hromadne cez POST /sapi/document/batch (až 100 dokladov na volanie).
• Stav doručenia: GET /sapi/document/sent vracia stavy odoslaných dokladov (pending → delivered / rejected z doručenky MLS), s ?since= na inkrementálne sťahovanie.
• 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.