Przed użyciem legacy SOAP API potrzebne są App Keys i SecurityToken uzyskany przez endpoint Login. Ten artykuł wyjaśnia krok po kroku, jak to działa.

Ważne: To jest legacy SOAP API. Dla nowych integracji zalecamy REST API, które wykorzystuje OAuth 2.0.

App Keys składają się z Consumer Key i Consumer Secret. Tworzy się je w platformie eConnect w menu Połączenia. Wymagana jest rola administratora.

Dostępne są dwa typy aplikacji:

Dla wariantu księgowego używa się App Integration Request: klient udziela przez platformę zgody na dostęp do swojej administracji. Jest to istotne dla dostawców oprogramowania działających w imieniu wielu klientów.

Uwierzytelnianie przebiega w dwóch krokach:

Krok 1: Login

Wywołanie endpointu Login z Consumer Key i Consumer Secret. W odpowiedzi otrzymuje się SecurityToken.

<Login>
  <ConsumerKey>jouw-consumer-key</ConsumerKey>
  <ConsumerSecret>jouw-consumer-secret</ConsumerSecret>
</Login>

Krok 2: przekazanie SecurityToken

SecurityToken przekazuje się w headerze SOAP przy wszystkich kolejnych wywołaniach. Token jest ważny przez 4 godziny. Można też żądać nowego tokena na każdą sesję.

<soap:Header>
  <SecurityToken>ontvangen-security-token</SecurityToken>
</soap:Header>

Krok 3: pobranie informacji o koncie

Po udanym loginie wywołuje się GetAccountParties, aby pobrać swoje EConnectPartyId (numer XCNL). Ten ID jest potrzebny przy wysyłaniu i odbieraniu dokumentów.

WSDL zawiera pełną specyfikację wszystkich dostępnych endpointów, typów danych i kodów błędów. WSDL można importować do narzędzi takich jak SoapUI lub Visual Studio, aby automatycznie generować kod klienta.

Transfer-Encoding=chunked: SOAP API nie obsługuje chunked transfer encoding. Należy upewnić się, że klient HTTP wysyła header content-length zamiast używać chunked encoding. Jest to jeden z najczęstszych błędów implementacyjnych.

Wygasły token: jeśli SecurityToken jest starszy niż 4 godziny, otrzymuje się błąd uwierzytelniania (seria kodów błędów 600). Należy zażądać nowego tokena przez Login.

Brak subscriptionKey: bez ważnej subscriptionKey w URL endpointu wszystkie żądania są odrzucane. Należy sprawdzić, czy klucz jest prawidłowy i nadal aktywny.

SOAP API zwraca ustrukturyzowane kody błędów w formacie ERR + opcode + seria + ID. Serie kodów błędów wskazują typ błędu:

Rozważają Państwo przejście na OAuth2 i REST API? Dokumentacja PSB na psb.econnect.eu z nowoczesnym przepływem uwierzytelniania.

• SOAP API: przegląd i endpointy
• SOAP: wysyłanie faktur (SendDocument)
• SOAP: odbieranie faktur
• Przegląd PSB REST API