CPDS API integrácia — sprievodca pre vývojárov

Najdôležitejšie upozornenie

Neexistuje jedno spoločné štátne ani OpenPeppol „CPDS REST API“. Zákon a technické špecifikácie určujú dokumenty, adresovanie, doručovací rámec a oznamovanie údajov. Rozhranie medzi vaším ERP a certifikovaným poskytovateľom je produktový kontrakt konkrétnej služby.

Názvy endpointov, OAuth scope, hlavičky, webhookové udalosti a stavy v tomto článku preto nie sú prezentované ako štandard. Nasledujúce vzory slúžia na návrh integrácie; implementujte ich podľa aktuálnej OpenAPI dokumentácie, zmluvy a testov vybraného poskytovateľa.

Architektonické vrstvy

ERP tím zvyčajne neimplementuje AS4, SMP ani SML priamo. Ak firma nie je sama certifikovaným poskytovateľom, tieto vrstvy má obslúžiť vybraný poskytovateľ.

Najprv si vyžiadajte API kontrakt

Pred návrhom konektora získajte:

• verziovanú OpenAPI alebo inú strojovo čitateľnú špecifikáciu,
• sandbox a produkčné základné adresy,
• podporovaný spôsob autentizácie a rotácie poverení,
• model odoslania dokumentu a ochranu pred duplicitou,
• úplný stavový model vrátane konečných a dočasných stavov,
• spôsob príjmu dokumentov a príloh,
• webhookový alebo pollingový kontrakt,
• podpisovanie udalostí a ochranu proti opakovaniu,
• limity, timeouty, retry pravidlá a SLA,
• pravidlá spätnej kompatibility a oznamovanie zmien,
• export pri ukončení služby a riešenie incidentu.

Marketingová stránka alebo ukážka jedného endpointu nie je API kontrakt.

Odoslanie dokumentu

Robustný tok má oddeliť prijatie požiadavky od konečného výsledku:

1. ERP uzavrie obchodný doklad a pridelí mu nemenný interný identifikátor.
2. Mapovacia vrstva vytvorí podporované XML.
3. Dokument prejde lokálnou validáciou proti presnej verzii pravidiel.
4. Konektor odošle dokument poskytovateľovi s idempotentným identifikátorom.
5. Poskytovateľ prijatie požiadavky potvrdí vlastným identifikátorom.
6. Konektor asynchrónne zistí konečný stav doručenia alebo chyby.
7. ERP uloží výsledok, no nezamieňa „prijaté API“ s „doručené príjemcovi“.

Ilustračný pseudokód, nie reálne API:

document = mapToSupportedInvoice(erpInvoice)
validation = validate(document, rulesetVersion)

if validation.hasFatalErrors:
    stopAndAssignToOwner(validation.errors)

result = provider.submit(
    document,
    idempotencyKey = erpInvoice.immutableId
)

storeProviderReference(result.reference)
waitForTerminalDeliveryState(result.reference)

Ak konkrétny poskytovateľ nemá samostatnú validačnú operáciu, validáciu urobte lokálne a výsledok aj tak overte v jeho testovacom prostredí. Lokálna validácia a akceptácia poskytovateľom môžu používať odlišné vydanie pravidiel; verziu preto logujte.

Idempotencia a duplicity

Sieťové volanie môže skončiť timeoutom aj vtedy, keď poskytovateľ dokument prijal. Bez idempotencie môže slepý retry vytvoriť duplicitné odoslanie.

Použite:

• stabilný identifikátor obchodného dokladu,
• idempotency key podľa kontraktu poskytovateľa,
• databázový unique constraint na kombináciu subjektu, dokumentu a verzie,
• bezpečné opakovanie iba dočasných chýb,
• explicitnú operáciu na zistenie stavu po nejednoznačnom timeoute.

Nezamieňajte technické opakovanie požiadavky s vyhotovením novej alebo opravnej faktúry. Oprava obsahu musí mať účtovný a daňový dôvod aj správnu referenciu.

Príjem dokumentov

Poskytovateľ môže ponúknuť webhook, frontu, sťahovanie cez API alebo kombináciu. Bez ohľadu na mechanizmus zabezpečte:

• overenie identity odosielajúcej služby,
• kontrolu podpisu podľa presného kontraktu,
• ochranu pred replay útokom,
• idempotentné spracovanie udalostí,
• uloženie pôvodných bajtov XML a príloh,
• oddelenie prijatia súboru od jeho účtovného schválenia,
• karanténu pri chybe validácie alebo mapovania.

Ilustračný webhook cieľ používajte iba s rezervovanou doménou, napríklad:

https://webhook.example/integrations/provider/events

Toto nie je existujúca služba ani odporúčaný endpoint. Doména example je zámerne neprodukčná.

Bezpečnostné minimum

Poverenia

• Poverenia nikdy neukladajte do repozitára ani do klientského JavaScriptu.
• Sandbox a produkcia musia mať oddelené identity a tajomstvá.
• Použite správcu tajomstiev, obmedzené oprávnenia a audit rotácie.
• Tokeny, celé XML a osobné údaje nevypisujte do bežných aplikačných logov.

Transport a webhooky

• Vyžadujte TLS a overujte certifikát.
• Pri podpise vždy používajte surové telo požiadavky a presný algoritmus z dokumentácie.
• Porovnávajte podpis konštantným časom a pred porovnaním overte dĺžku a formát.
• Overujte časovú pečiatku alebo nonce, ak ich kontrakt poskytuje.
• Odpovedzte rýchlo a dlhé spracovanie presuňte do trvácnej fronty.

Oprávnenia medzi firmami

Ak integrácia obsluhuje viac účtovných jednotiek, každý dokument musí byť viazaný na správny subjekt. Identifikátor odosielateľa neprijímajte iba z používateľského vstupu; autorizujte ho voči zmluvnému účtu, povereniu alebo portfóliu klienta.

Validácia dokumentu

„XML sa dá otvoriť“ nie je úspešná validácia. Potrebujete najmenej:

1. syntaktickú kontrolu XML,
2. kontrolu schémy použitej syntaxe,
3. pravidlá EN 16931,
4. aktuálne Peppol BIS Billing pravidlá,
5. aktuálne slovenské pravidlá,
6. produktové obmedzenia podporovaného toku.

K 20. augustu 2026 je aktuálne povinné vydanie Peppol BIS Billing 3.0.21, publikované 20. mája 2026 a povinné od 17. augusta 2026. Verziu validačných artefaktov neukladajte natrvalo bez mechanizmu aktualizácie.

Pravidlá sa môžu meniť nezávisle od aplikačného releasu. V prevádzke preto evidujte:

• identifikátor použitého rulesetu,
• výsledok a fatálne chyby,
• čas validácie,
• hash dokumentu,
• verziu mapovacieho kódu.

Stavový model

Názvy stavov sú poskytovateľské, ale interný model by mal rozlišovať aspoň:

Mapovanie stavov musí vychádzať z dokumentácie poskytovateľa. Nepremenujte každú odpoveď HTTP 200 na „doručené“.

Testovací plán

Testujte v určenom testovacom prostredí so syntetickými firmami, identifikátormi a dokladmi. Neposielajte fiktívnu faktúru sami sebe v produkcii.

Minimálne scenáre:

• platná faktúra a prijatie na druhej strane,
• faktúra k prijatej platbe,
• opravný doklad a referencia,
• príloha,
• nesprávny identifikátor príjemcu,
• fatálna validačná chyba,
• dočasný timeout pred prijatím aj po možnom prijatí,
• opakovaný submit s rovnakým idempotency key,
• duplicitná webhooková udalosť,
• neplatný podpis a replay,
• nedostupná interná fronta alebo databáza,
• rotácia poverenia,
• hromadný export a obnova po výpadku,
• oddelenie viacerých firiem v jednej integrácii.

Dokumenty overte aj v OpenPeppol Testbede. Výsledok validátora nenahrádza end-to-end test so zmluvným poskytovateľom.

Prevádzkový checklist

• API kontrakt je verziovaný a uložený pri integračnej dokumentácii.
• Produkčné tajomstvá sú mimo repozitára a logov.
• Každé odoslanie má idempotentný identifikátor.
• Po timeoute vieme zistiť stav bez slepého duplicitného retry.
• Rozlišujeme prijatie API požiadavky a konečný doručovací stav.
• Webhooky overujeme, deduplikujeme a spracúvame cez trvácnu frontu.
• Ukladáme pôvodné XML a prílohy bez tichej transformácie.
• Evidujeme verziu validačných pravidiel a mapovania.
• Monitoring neobsahuje celé dokumenty ani tajomstvá.
• Máme runbook pre výpadok, incident a zmenu poskytovateľa.

Čo tento článok zámerne neuvádza

Neuvádzame univerzálne endpointy, OAuth scope, webhookové hlavičky, rate limits, ceny ani odporúčané programové knižnice. Tieto údaje nie sú vlastnosťou CPDS ako zákonnej kategórie a bez overenia konkrétneho produktu by boli zavádzajúce.

Pokračujte cez zdroje pre vývojárov, implementáciu pre ERP a rozdiel medzi doručením a daňovým oznamovaním.