eConnect oferuje SDK i biblioteki klienckie, które pozwalają na szybszą integrację z PSB API. Ponadto mogą Państwo wykorzystać specyfikację OpenAPI (swagger.json) do samodzielnego wygenerowania klienta w praktycznie dowolnym języku programowania.

Na GitHubie, w ramach organizacji theinvoicingcompany, dostępne są dwa oficjalnie wspierane SDK:

Oba SDK obudowują PSB REST API i oferują typowane metody do najczęściej używanych operacji: uwierzytelnianie, wysyłanie i odbieranie faktur, zarządzanie hookami oraz odpytywanie danych podmiotów.

SDK .NET jest dostępny jako pakiet NuGet. Po zainstalowaniu mogą się Państwo uwierzytelnić i wykonać pierwsze wywołanie API w zaledwie kilku liniach kodu.

// Authenticatie en eerste aanroep met de .NET SDK
var client = new PsbClient(new PsbClientOptions
{
    ClientId = "jouw-client-id",
    ClientSecret = "jouw-client-secret",
    BaseUrl = "https://accp-psb.econnect.eu",
    IdentityUrl = "https://accp-identity.econnect.eu"
});

var me = await client.GetMeAsync();
Console.WriteLine($"Account: {me.Name}");

Wskazówka: podczas prac deweloperskich należy używać URL-ów akceptacyjnych (accp-psb i accp-identity). Po uruchomieniu produkcyjnym należy przełączyć na URL-e produkcyjne.

SDK PHP instaluje się za pomocą Composera. SDK automatycznie obsługuje zarządzanie tokenami OAuth, dzięki czemu mogą się Państwo skupić na logice biznesowej.

// Authenticatie en eerste aanroep met de PHP SDK
$client = new \EConnect\Psb\PsbClient([
    'client_id' => 'jouw-client-id',
    'client_secret' => 'jouw-client-secret',
    'base_url' => 'https://accp-psb.econnect.eu',
    'identity_url' => 'https://accp-identity.econnect.eu',
]);

$me = $client->getMe();
echo "Account: " . $me->getName();

Pracują Państwo w innym języku niż .NET lub PHP? PSB API jest w pełni udokumentowane jako specyfikacja OpenAPI 3.0. Mogą Państwo pobrać plik swagger.json ze strony psb.econnect.eu i na jego podstawie wygenerować klienta za pomocą OpenAPI Generator.

OpenAPI Generator obsługuje ponad 50 języków i frameworków, w tym Java, Python, TypeScript, Go i Ruby. Przykład z narzędziem wiersza poleceń:

openapi-generator-cli generate \
  -i https://psb.econnect.eu/swagger/v1/swagger.json \
  -g java \
  -o ./psb-client-java

Wynikiem jest kompletna biblioteka kliencka z typowanymi modelami dla wszystkich obiektów żądań i odpowiedzi. Wystarczy skonfigurować uwierzytelnianie (patrz artykuł o uwierzytelnianiu) i można od razu zacząć.

Uwaga: wygenerowane klienty domyślnie nie zawierają zarządzania tokenami. Należy samodzielnie zaimplementować logikę żądania i odnawiania tokenów lub skorzystać z biblioteki OAuth2 dla swojej platformy.

Najbardziej bezpośrednim sposobem na eksplorację API jest Swagger UI na psb.econnect.eu. Mogą tam Państwo:

• Przeglądać wszystkie endpointy, pogrupowane według obszaru funkcjonalnego (SalesInvoice, PurchaseInvoice, Hook, Peppol itp.)
• Sprawdzać schematy żądań i odpowiedzi ze wszystkimi polami i ich typami danych
• Wykonywać wywołania API z własnym tokenem Bearer, bezpośrednio z przeglądarki
• Pobierać plik swagger.json do generowania kodu

Swagger UI jest również przydatnym odniesieniem podczas prac deweloperskich. W razie wątpliwości co do struktury żądania lub pól w odpowiedzi, zawsze znajdą tam Państwo aktualną specyfikację.

Wolą Państwo nie używać SDK? PSB API to standardowe REST API, które można wywoływać za pomocą dowolnego klienta HTTP. Poniżej przykład z curl, który pokazuje, jak zażądać tokena, a następnie pobrać dane konta:

# Token aanvragen
TOKEN=$(curl -s -X POST https://accp-identity.econnect.eu/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=jouw-client-id" \
  -d "client_secret=jouw-client-secret" \
  -d "scope=ap" | jq -r '.access_token')

# Accountgegevens ophalen
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  https://accp-psb.econnect.eu/api/v1/me | jq .

W zastosowaniach produkcyjnych zaleca się przechowywanie tokena w pamięci podręcznej i odnawianie go dopiero krótko przed wygaśnięciem (po ok. 3500 sekundach). Nie należy żądać nowego tokena przy każdym żądaniu.