V tomto článku projdete prvními kroky práce s PSB API: od žádosti o účet až po první API volání. Na konci budete mít funkční připojení k testovacímu prostředí a budete vědět, jak je API sestaveno.

K používání PSB API potřebujete credentials. Ty požádáte prostřednictvím sandbox-asistenta. Po registraci obdržíte tři údaje:

Tip: požádejte si credentials rovnou pro akceptační i produkční prostředí. Tak můžete bezpečně testovat bez rizika neúmyslného odeslání reálných faktur.

V závislosti na zvoleném OAuth2 flow můžete také obdržet username a password pro Resource Owner Password Credentials flow. Pro integrace server-server je doporučený Client Credentials flow a potřebujete pouze clientId a clientSecret.

PSB má dvě prostředí. Akceptační prostředí používejte pro vývoj a testování, produkční prostředí pro reálné transakce.

Akceptační prostředí funguje identicky jako produkce: žádosti o token, API volání a webhooky se chovají stejně. Rozdíl je v tom, že dokumenty se neodesílají do reálné sítě Peppol.

Pozor: používejte oddělené credentials pro akceptaci a produkci. Tak zabráníte tomu, aby se testovací credentials omylem dostaly do produkčního prostředí.

Každý API požadavek na PSB vyžaduje Bearer token. Tento token si vyžádáte na Identity Serveru prostřednictvím POST požadavku 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

Při úspěchu obdržíte JSON odpověď s access tokenem:

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

Token je platný 3600 sekund (1 hodina). Po vypršení jednoduše požádáte o nový token. Kompletní proces autentizace včetně Resource Owner Password Credentials flow a obnovy tokenů je popsán v článku o autentizaci.

S platným tokenem můžete volat API. Dobrým výchozím bodem je endpoint GET /api/v1/me, který vrátí informace o Vašem účtu a organizacích (party), které jsou k němu přiřazeny.

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

Úspěšná odpověď obsahuje Vaše údaje o účtu a seznam party, pro které jste oprávněni. Každá party má PartyId (například číslo KvK nebo OIN) a oprávnění, která určují, co můžete dělat: odesílat dokumenty, přijímat, mazat nebo spravovat hooky.

PSB API vrací odpovědi ve formátu JSON. Samotné dokumenty (faktury, objednávky) se odesílají a přijímají jako XML. PSB podporuje více než 20 formátů e-dokumentů včetně 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 při uploadu, takže dokument můžete odeslat ve vlastním formátu bez manuální konverze. PSB validuje každý dokument vůči příslušným XSD a business rules.

HTTP stavové kódy dodržují standardní REST konvence:

Při chybě 4xx odpověď obsahuje chybovou zprávu s uvedením problému. Při chybách 5xx je rozumné požadavek zopakovat s exponential backoff.

PSB zná dvě role, které určují, co uživatel může dělat.

ApUser je standardní role. S ní můžete odesílat a přijímat dokumenty a spravovat webhooky pro party, ke kterým jste přiřazeni.

ApManager má navíc administrátorská oprávnění: vytvářet a mazat uživatele, registrovat organizace v registru Peppol SMP/SML a používat Enrollment API k zřizování nových party.

Pro každou party se oprávnění nastavují samostatně: canSendDocument, canReceiveDocument, canRemoveDocument a canManageHook. Každá registrovaná party musí být přiřazena minimálně k jednomu účtu ApUser.

Kompletní API reference je dostupná jako Swagger UI na psb.econnect.eu. Tam můžete prozkoumat endpointy, zobrazit formáty požadavků a odpovědí a testovat API volání s vlastním tokenem. swagger.json je také ke stažení, takže s nástroji jako OpenAPI Generator můžete generovat klientský kód v jazyce podle vlastního výběru.