W tym artykule przeprowadzimy Państwa przez pierwsze kroki pracy z PSB API: od złożenia wniosku o konto po wykonanie pierwszego wywołania API. Na końcu będą Państwo mieli działające połączenie ze środowiskiem testowym i będą wiedzieli, jak zbudowane jest API.

Do korzystania z PSB API potrzebne są dane uwierzytelniające. Można je zamówić za pośrednictwem kreatora sandbox. Po rejestracji otrzymają Państwo trzy dane:

Wskazówka: warto od razu zamówić dane uwierzytelniające zarówno dla środowiska akceptacyjnego, jak i produkcyjnego. Dzięki temu mogą Państwo bezpiecznie testować bez ryzyka przypadkowego wysłania prawdziwych faktur.

W zależności od wybranego przepływu OAuth2 mogą Państwo otrzymać również username i password dla przepływu Resource Owner Password Credentials. Dla integracji server-to-server zalecany jest przepływ Client Credentials, do którego potrzebne są jedynie clientId i clientSecret.

PSB dysponuje dwoma środowiskami. Środowisko akceptacyjne służy do rozwoju i testów, a środowisko produkcyjne do rzeczywistych transakcji.

Środowisko akceptacyjne działa identycznie jak produkcja: żądania tokenów, wywołania API i webhooki zachowują się tak samo. Różnica polega na tym, że dokumenty nie są wysyłane do prawdziwej sieci Peppol.

Uwaga: należy używać oddzielnych danych uwierzytelniających dla akceptacji i produkcji. Zapobiega to przypadkowemu użyciu danych testowych w środowisku produkcyjnym.

Każde żądanie API do PSB wymaga tokena Bearer. Token żąda się od Identity Server za pomocą żądania POST do /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

W przypadku powodzenia otrzymają Państwo odpowiedź JSON zawierającą access token:

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

Token jest ważny przez 3600 sekund (1 godzinę). Po wygaśnięciu wystarczy zażądać nowego tokena. Pełny proces uwierzytelniania, w tym przepływ Resource Owner Password Credentials i odnawianie tokenów, opisano w artykule o uwierzytelnianiu.

Dysponując ważnym tokenem, mogą Państwo wywoływać API. Dobrym punktem wyjścia jest endpoint GET /api/v1/me, który zwraca informacje o koncie i powiązanych organizacjach (party).

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

Pomyślna odpowiedź zawiera dane konta i listę party, do których mają Państwo uprawnienia. Każda party posiada PartyId (np. numer KvK lub OIN) oraz uprawnienia określające, co można robić: wysyłać dokumenty, odbierać je, usuwać lub zarządzać hookami.

Dokumenty można dostarczać w dowolnym formacie obsługiwanym przez PSB: UBL 2.1, NLCIUS, BIS Billing V3, PINT, CII, XRechnung, Factur-X, FatturaPA i ponad 20 innych standardów. PSB automatycznie wykrywa format i transformuje go na format oczekiwany przez odbiorcę. Nie trzeba zatem wiedzieć, jakiego formatu używa odbiorca.

PSB API zwraca wszystkie odpowiedzi w formacie JSON. Same dokumenty (faktury, zamówienia) są wysyłane i odbierane jako XML.

Kody statusu HTTP są zgodne ze standardowymi konwencjami REST:

W przypadku błędu 4xx odpowiedź zawiera komunikat wskazujący problem. Przy błędach 5xx zaleca się ponowienie żądania z zastosowaniem exponential backoff.

PSB przewiduje dwie role określające, co użytkownik może robić.

ApUser to rola standardowa. Pozwala na wysyłanie i odbieranie dokumentów oraz zarządzanie webhookami dla party, do których użytkownik jest przypisany.

ApManager posiada dodatkowo uprawnienia administracyjne: tworzenie i usuwanie użytkowników, rejestrowanie organizacji w rejestrze Peppol SMP/SML oraz korzystanie z Enrollment API do konfigurowania nowych party.

Dla każdej party uprawnienia są konfigurowane oddzielnie: canSendDocument, canReceiveDocument, canRemoveDocument i canManageHook. Każda zarejestrowana party musi być przypisana do co najmniej jednego konta ApUser.

Pełna dokumentacja referencyjna API jest dostępna jako Swagger UI na psb.econnect.eu. Mogą tam Państwo przeglądać endpointy, sprawdzać formaty żądań i odpowiedzi oraz testować wywołania API z własnym tokenem. Plik swagger.json można również pobrać, aby za pomocą narzędzi takich jak OpenAPI Generator wygenerować kod klienta w wybranym języku.