Segment · Aktualizované 2026-05-09

CPDS pre IT a devops oddelenia

Technický pohľad na implementáciu Peppol e-fakturácie pre slovenské IT a devops tímy: REST API, webhooks, AS4 transportný protokol, sandbox testovanie, security model a praktické postupy pre prepojenie ERP a CPDS.

Rýchla odpoveď

IT oddelenie integruje CPDS cez REST API (HTTPS + JSON, OAuth 2.0 alebo API kľúč). Príjem cez webhook callback, odosielanie cez POST /invoices s UBL XML, status tracking cez polling alebo webhook. AS4 protokol medzi CPDS-CPDS rieši poskytovateľ. Plánujte 4–8 týždňov na základnú integráciu a sandbox testovanie, ďalšie 2–4 týždne na performance tuning a hardening. Príkladom slovenského CPDS s OpenAPI 3.1 špecifikáciou a SDK v 6 jazykoch je ePošťák API dokumentácia.

Architektonický pohľad

Z pohľadu IT je Peppol ekosystém vrstvená architektúra, kde každá vrstva rieši odlišnú zodpovednosť:

  • Vaše ERP / aplikácie — generujú obchodné dokumenty (faktúra, dobropis, objednávka).
  • Vaša integrácia — middleware, ktorý transformuje obchodný doklad na UBL XML podľa BIS Billing 3.0 a komunikuje s CPDS.
  • CPDS / Peppol Access Point — pripája vás do globálnej Peppol siete, podpisuje a šifruje doklady, vykonáva validáciu, doručuje cez AS4 ďalším AP-om.
  • Peppol SML/SMP — globálna service discovery vrstva (Service Metadata Locator a Service Metadata Publisher), ktorá hovorí „kde je participant XYZ a aké formáty prijíma".
  • Cieľový AP — protistrana (CPDS druhej firmy), ktorá doručí dokument do ERP príjemcu.

REST API — typický kontrakt

Slovenskí CPDS poskytovatelia ponúkajú podobnú množinu endpointov, kompatibilnú s OpenAPI 3.0 špecifikáciou. Príklady (skutočná schéma sa môže líšiť):

Príjem dokumentov

  • GET /v1/inbox — paginated list prijatých faktúr s metadata.
  • GET /v1/invoices/{id} — detail vrátane UBL XML a PDF (ak generuje CPDS).
  • POST /v1/webhooks — registrácia webhook URL pre push notifikácie pri nových faktúrach.

Odosielanie dokumentov

  • POST /v1/invoices — odoslanie UBL XML faktúry. Body je raw XML alebo multipart s prílohami.
  • POST /v1/invoices/validate — dry-run validácia bez odoslania. Vráti syntaktické a obchodné chyby pred ostrým submitom.
  • GET /v1/invoices/{id}/status — sledovanie stavu (Submitted, Delivered, Acknowledged, Rejected) po odoslaní.

Discovery a metadata

  • GET /v1/participants/lookup?id=0245:SK1234567890 — overenie, či zákazník/dodávateľ je v Peppol sieti a aké formáty podporuje.
  • GET /v1/health — status check pre monitoring.

Webhooks — best practices

CPDS posiela webhooky pre asynchrónne udalosti — nový dokument prijatý, odoslanie potvrdené, odoslanie zamietnuté. Robustná webhook integrácia má:

  • HMAC podpis — header X-CPDS-Signature s SHA-256 alebo SHA-512 HMAC payloadu, validujte pred spracovaním. (Niektoré CPDS prešli z SHA-256 na SHA-512 — overte aktuálny štandard poskytovateľa.)
  • Idempotenciu — webhook môže byť doručený opakovane, uchovávajte ID a deduplikujte.
  • Acknowledgement — vráťte HTTP 2xx do 10 sekúnd, inak CPDS retry-uje (typicky exponential backoff: 1m, 5m, 30m, 2h, 12h).
  • Async processing — webhook handler len enqueuje úlohu, spracovanie deje samotný worker. Zabráni timeoutom pri pomalom backende.
  • Source IP allowlist — niektorí CPDS publikujú CIDR rozsahy svojich webhook IP, validujte pred prijatím.

AS4 — čo je dobré vedieť

AS4 (Applicability Statement 4) je transportný protokol používaný v Peppol sieti medzi Access Pointmi. Pre developera vašej aplikácie je AS4 „neviditeľný" — komunikujete s vaším CPDS cez REST, on rieši AS4 voči ďalším AP-om. Praktické fakty o AS4:

  • Postavený na ebMS3 (ebXML Messaging Services 3.0) — SOAP + MIME multipart.
  • Obojstranná autentizácia X.509 certifikátmi (Peppol Authority CA).
  • Asynchrónny acknowledgement — receipt (signed) ako dôkaz doručenia.
  • Podpora reliable messaging (WS-RM), non-repudiation, confidentiality.
  • Štandard od OASIS, oficiálne profily pre Peppol: docs.peppol.eu/edelivery.

Sandbox testovanie — odporúčaný postup

  1. Registrácia sandbox účtu u CPDS (typicky zdarma). Získate test participant ID v slovenskom formáte (napr. 0245:SKTEST123) a API kľúče oddelené od produkčných.
  2. Smoke test — zavolajte GET /v1/health a GET /v1/participants/lookup?id=<your-id>. Overí sa autentizácia a discovery.
  3. Round-trip test — pošlite testovaciu faktúru sami sebe (sender ID = receiver ID). Príde späť cez webhook do 1–5 minút.
  4. Validačný test — pošlite zámerne chybnú faktúru (nesprávne DPH sadzby, neexistujúce participant ID, malformed XML). Overte, že CPDS vráti relevantné chyby.
  5. Performance test — synthetic load test s realistickým objemom. Sledujte p95 latencia a error rate. Pre enterprise 50+ rps minimum.
  6. Resilience test — simulujte výpadky (network timeout, rate-limit response, 5xx errory). Overte retry logiku a circuit-breaker.
  7. End-to-end test s reálnym partnerom — pred 1.1.2027 dohodnite test s 2–3 kľúčovými klientmi a dodávateľmi, ktorí už majú Peppol setup.

Security checklist

  • TLS 1.2+ povinné, TLS 1.3 odporúčané. Bez výnimiek.
  • API kľúče v secret manager (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager). Žiadne hardcoded kľúče v kóde alebo .env súboroch v gitu.
  • Rotácia kľúčov — automaticky každých 90 dní, manuálna rotácia pri podozrení na únik.
  • Princíp najmenších oprávnení — read-only kľúče pre monitoring, write kľúče len pre integration servisy.
  • Webhook HMAC validation — vždy. Bez výnimky.
  • Encryption at rest v databáze (AES-256), KMS-managed kľúče.
  • Audit log všetkých CPDS API interakcií — append-only, retention 10 rokov.
  • DPA (Data Processing Agreement) s CPDS poskytovateľom, mapovanie GDPR data flow.

Súvisiace zdroje

Často kladené otázky — IT oddelenia

Aký je rozdiel medzi REST API CPDS a AS4 protokolom?
REST API CPDS je rozhranie medzi vašou aplikáciou a vaším CPDS poskytovateľom — používa štandardný HTTPS s JSON, autentizácia API kľúčmi, typický throughput stovky requestov/sekundu. AS4 (Applicability Statement 4) je transportný protokol medzi dvoma Peppol Access Pointmi (čiže medzi CPDS a CPDS) — XML cez SOAP/MIME, obojstranná certifikátová autentizácia, šifrovanie a digitálne podpisovanie podľa ebMS3 štandardu. Ako developer aplikácie pre váš biznis sa o AS4 nemusíte starať — je to vrstva pod CPDS, ktorú rieši CPDS poskytovateľ. Vaše API volania sú jednoduché REST.
Ako vyzerá typická CPDS REST API integrácia?
Štandardný flow: (1) Autentizácia — Bearer token (z OAuth 2.0 client credentials flow) alebo API kľúč v hlavičke. (2) Príjem — webhook callback z CPDS pri každej príchodzej faktúre, payload obsahuje ID a metadata, samotný XML/PDF stiahnete cez GET /invoices/{id}. (3) Odosielanie — POST /invoices s UBL XML v body, CPDS vráti tracking ID, status sledovať cez GET alebo cez webhook callback. (4) Validácia — pred odoslaním doporučujeme zavolať POST /invoices/validate, ktorý kontroluje BIS 3.0 schemu a obchodné pravidlá bez reálneho odoslania. Štandardné HTTP status kódy a JSON error envelope.
Ako otestovať Peppol integráciu pred ostrým spustením?
Peppol má oficiálne testovacie prostredie nazývané Test environment (alias acc.edelivery.tech.ec.europa.eu pre SML directory). Väčšina CPDS poskytovateľov ponúka aj sandbox endpoint s vlastným testovacím Peppol participant ID. Postup: (1) zaregistrujte sandbox účet u CPDS, (2) získajte test participant ID a API kľúče, (3) pošlite testovaciu UBL XML faktúru cez REST API, (4) overte v test SML/SMP, že vaše ID je správne registrované, (5) overte kruhový test — pošlite si faktúru sami sebe a overte, že prišla cez webhook. Pre BIS Billing 3.0 môžete použiť aj OpenPeppol Testbed, ktorý má 10 testovacích scenárov pre SK krajinu.
Aké security a compliance požiadavky platia pre CPDS integráciu?
Hlavné aspekty: (1) Transport security — TLS 1.2+ povinné, TLS 1.3 odporúčané, certifikátová validácia s pinningom pre kritické integrácie. (2) Autentizácia — OAuth 2.0 client credentials s rotáciou tokenov, API kľúče len pre interné systémy a stored v secret manager (HashiCorp Vault, Azure Key Vault, AWS Secrets Manager). (3) Webhook security — HMAC SHA-256 alebo SHA-512 signatúry payloadu, validácia source IP/CIDR. (4) Šifrovanie at-rest — XML faktúry obsahujú PII (mená, kontakty), encryption v databáze (AES-256), KMS pre kľúče. (5) Logovanie — audit log s neopraviteľnosťou (append-only), retention 10 rokov, segregation podľa GDPR. (6) GDPR — DPA s CPDS poskytovateľom, mapovanie tokov osobných údajov.
Ako monitorovať produkciu a riešiť incidenty?
Production-grade monitoring má 4 vrstvy: (1) Synthetic monitoring — pravidelné test transakcie (každých 5–15 minút) s alertom pri zlyhaní. (2) RED metriky — Rate (tx/sec), Errors (% non-2xx), Duration (latency p50/p95/p99) per CPDS endpoint. (3) Business metriky — počet odoslaných faktúr za hodinu, odosielacia latencia, počet zamietnutých faktúr per validation rule. (4) Log aggregation — všetky CPDS interakcie do centrálneho logu (Elasticsearch, Splunk, Datadog) s correlation ID napríč ERP-staging-CPDS. Pre incidenty mať runbook s eskaláciou na 24/7 support CPDS, dual-channel komunikáciu (e-mail + telefón priamo na technical lead) a sledovanie stavu CPDS na status page poskytovateľa.
Aké programovacie jazyky a knižnice sú vhodné na implementáciu?
Pre samotnú integráciu s CPDS REST API stačí akýkoľvek jazyk s HTTP klientom — Java/Kotlin (Spring Boot), C# (.NET 8/9), TypeScript/Node.js, Python, Go, PHP. Pre prácu s UBL XML existuje viacero knižníc: Java — Mustang Project, Smojin invoicer; .NET — UBL.NET, Helger UBL; Node.js — node-ubl; Python — python-ubl. Pre validáciu BIS 3.0 schemu odporúčame oficiálne XSD a Schematron pravidlá z OpenPeppol GitHub repozitára. Pre digitálne podpisy XAdES (vyžaduje XML signature) — Apache Santuario (Java), .NET SignedXml, xades-bes-utils-py (Python). Pre väčšinu integrácií s CPDS REST API podpisy nepotrebujete — robí ich CPDS na vašu žiadosť.