SAPI-SK pro vývojáře

Co je SAPI-SK

SAPI-SK je národní REST rozhraní mezi klientským systémem (ERP, e-shop, účetní software) a Access Pointem. Cílem je jednotný, dodavatelsky nezávislý způsob, jak přes „digitálního pošťáka“ odesílat a přijímat doklady, místo proprietárního API každého poskytovatele. Podporu SAPI-SK proto vnímejte jako pojistku proti vendor lock-inu.

Autentizace

Používá se OAuth2 client_credentials. Z portálu si vytvoříte API token: jeho UUID slouží jako client_id a hodnota vpt_… jakoclient_secret. Přes POST /sapi/auth/token získáte krátkodobý access token a refresh token; access token pak posíláte v hlavičce Authorization: Bearer …. Zrušení API tokenu v portálu okamžitě zneplatní i vydané tokeny.

Odeslání a příjem

• Odeslání: POST /sapi/document/send s hlavičkou X-Peppol-Participant-Id (účastník, ZA kterého odesíláte: vaše firma nebo klient pod vaším tokenem; příjemce se uvádí v metadatech dokumentu) a Idempotency-Key (bezpečné opakování bez duplicit). Hromadně přes POST /sapi/document/batch (až 100 dokladů na volání).
• Stav doručení: GET /sapi/document/sent vrací stavy odeslaných dokladů (pending → delivered / rejected z doručenky MLS, nebo undeliverable, když příjemce nemá adresu v síti Peppol), s ?since= pro inkrementální stahování.
• Příjem: GET /sapi/document/receive (stránkování, filtr podle stavu) a potvrzení zpracování přes acknowledge.
• Důkazy a hlášení FS (od 1.8.14): každý doklad nese objekt fsReport (reported / pending / not_required s důvodem, id hlášení a verdikt C5), odeslané i statusReason a xmlSha256; stav až 200 dokladů najednou přes POST /sapi/document/sent/status, časová osa přes GET /sapi/document/sent/{id}/events. Webhooky nesou fsReport a nové události invoice.report_pending a invoice.report_rejected.
• Stav tokenu / obnova / zrušení: samostatné endpointy pod /sapi/auth/*.

Sandbox a idempotence

Kontrakt si můžete vyzkoušet v sandboxu bez rizika reálného doručení: sandbox validuje požadavky a vrací mock odpovědi. Při odesílání vždy používejte Idempotency-Key: při opakování téhož požadavku (např. po timeoutu) nevznikne duplicitní doklad. Klíč odvoďte z něčeho stálého pro fakturu (např. ID nebo číslo faktury ve vašem systému); nový klíč pro tutéž fakturu tuto ochranu obejde. Pokud doklad odmítla naše kontrola před odesláním (např. chyba validace), do sítě nic neodešlo a nic se nehlásí Finanční správě: opravte ho a pošlete znovu se stejným klíčem, s datem vystavení podle dne, kdy opravdu odejde. Doručená faktura se znovu neposílá, opravuje se dobropisem nebo vrubopisem. Chybám předejdete přes POST /sapi/document/validate (ověří doklad bez odeslání) a GET /sapi/discovery (je příjemce v síti Peppol).

Kde najdete detaily

Úplný seznam endpointů, příklady požadavků/odpovědí a chybové kódy jsou v naší technické dokumentaci (sekce SAPI-SK) včetně strojové OpenAPI 3.1 specifikace. Doporučujeme začít v sandboxu a až potom přejít na produkci.