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, alebo undeliverable, keď príjemca nemá adresu v sieti Peppol), s ?since= na inkrementálne sťahovanie.
• Príjem: GET /sapi/document/receive (stránkovanie, filter podľa stavu) a potvrdenie spracovania cez acknowledge.
• Dôkazy a hlásenia FS (od 1.8.14): každý doklad nesie objekt fsReport (reported / pending / not_required s dôvodom, id hlásenia a verdikt C5), odoslané aj statusReason a xmlSha256; stav až 200 dokladov naraz cez POST /sapi/document/sent/status, časová os cez GET /sapi/document/sent/{id}/events. Webhooky nesú fsReport a nové udalosti invoice.report_pending a invoice.report_rejected.
• 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. Kľúč odvoďte z niečoho stáleho pre faktúru (napr. ID alebo číslo faktúry vo vašom systéme); nový kľúč pre tú istú faktúru túto ochranu obíde. Ak doklad odmietla naša kontrola pred odoslaním (napr. chyba validácie), do siete nič neodišlo a nič sa nehlási Finančnej správe: opravte ho a pošlite znova s rovnakým kľúčom, s dátumom vystavenia podľa dňa, keď naozaj odíde. Doručená faktúra sa znova neposiela, opravuje sa dobropisom alebo ťarchopisom. Chybám predídete cez POST /sapi/document/validate (overí doklad bez odoslania) a GET /sapi/discovery (je príjemca v sieti Peppol).

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.