V tomto článku prejdete prvými krokmi práce s PSB API: od žiadosti o účet až po prvé API volanie. Na konci budete mať funkčné pripojenie k testovaciemu prostrediu a budete vedieť, ako je API zostavené.

Na používanie PSB API potrebujete credentials. Tie požiadate prostredníctvom sandbox-asistenta. Po registrácii obdržíte tri údaje:

Tip: požiadajte si credentials hneď pre akceptačné aj produkčné prostredie. Tak môžete bezpečne testovať bez rizika neúmyselného odoslania reálnych faktúr.

V závislosti od zvoleného OAuth2 flow môžete tiež obdržať username a password pre Resource Owner Password Credentials flow. Pre integrácie server-server je odporúčaný Client Credentials flow a potrebujete iba clientId a clientSecret.

PSB má dve prostredia. Akceptačné prostredie používajte na vývoj a testovanie, produkčné prostredie na reálne transakcie.

Akceptačné prostredie funguje identicky ako produkcia: žiadosti o token, API volania a webhooky sa správajú rovnako. Rozdiel je v tom, že dokumenty sa neodosielajú do reálnej siete Peppol.

Pozor: používajte oddelené credentials pre akceptáciu a produkciu. Tak zabránite tomu, aby sa testovacie credentials omylom dostali do produkčného prostredia.

Každá API požiadavka na PSB vyžaduje Bearer token. Tento token si vyžiadate na Identity Serveri prostredníctvom POST požiadavky na /connect/token.

POST /connect/token HTTP/1.1
Host: accp-identity.econnect.eu
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=jouw-client-id
&client_secret=jouw-client-secret
&scope=ap

Pri úspechu obdržíte JSON odpoveď s access tokenom:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "ap"
}

Token je platný 3600 sekúnd (1 hodina). Po vypršaní jednoducho požiadate o nový token. Kompletný proces autentifikácie vrátane Resource Owner Password Credentials flow a obnovy tokenov je popísaný v článku o autentifikácii.

S platným tokenom môžete volať API. Dobrým východiskovým bodom je endpoint GET /api/v1/me, ktorý vráti informácie o Vašom účte a organizáciách (party), ktoré sú k nemu priradené.

GET /api/v1/me HTTP/1.1
Host: accp-psb.econnect.eu
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Úspešná odpoveď obsahuje Vaše údaje o účte a zoznam party, pre ktoré ste oprávnení. Každá party má PartyId (napríklad číslo KvK alebo OIN) a oprávnenia, ktoré určujú, čo môžete robiť: odosielať dokumenty, prijímať, mazať alebo spravovať hooky.

PSB API vracia odpovede vo formáte JSON. Samotné dokumenty (faktúry, objednávky) sa odosielajú a prijímajú ako XML. PSB podporuje viac ako 20 formátov e-dokumentov vrátane UBL 2.1, NLCIUS, Peppol BIS Billing V3, PINT, CII, XRechnung, Factur-X/ZUGFeRD, FatturaPA, ebInterface, Svefaktura, e-FFF, OIOUBL, Finvoice a ISDOC.

API automaticky rozpozná formát dokumentu pri uploade, takže dokument môžete odoslať vo vlastnom formáte bez manuálnej konverzie. PSB validuje každý dokument voči príslušným XSD a business rules.

HTTP stavové kódy dodržiavajú štandardné REST konvencie:

Pri chybe 4xx odpoveď obsahuje chybovú správu s uvedením problému. Pri chybách 5xx je rozumné požiadavku zopakovať s exponential backoff.

PSB pozná dve roly, ktoré určujú, čo používateľ môže robiť.

ApUser je štandardná rola. S ňou môžete odosielať a prijímať dokumenty a spravovať webhooky pre party, ku ktorým ste priradení.

ApManager má navyše administrátorské oprávnenia: vytvárať a mazať používateľov, registrovať organizácie v registri Peppol SMP/SML a používať Enrollment API na zriaďovanie nových party.

Pre každú party sa oprávnenia nastavujú samostatne: canSendDocument, canReceiveDocument, canRemoveDocument a canManageHook. Každá registrovaná party musí byť priradená minimálne k jednému účtu ApUser.

Kompletná API referencia je dostupná ako Swagger UI na psb.econnect.eu. Tam môžete preskúmať endpointy, zobraziť formáty požiadaviek a odpovedí a testovať API volania s vlastným tokenom. swagger.json je tiež stiahnuteľný, takže s nástrojmi ako OpenAPI Generator môžete generovať klientský kód v jazyku podľa vlastného výberu.