e-pity Płatnika API w pigułce

e-pity Płatnika API to interfejs programistyczny do testowania dostępnych metod oraz generowania dokumentacji w formacie Open API 2.0 (Swagger) do integracji z narzędziami testowymi (np. PostMan).

Interfejs e-pity Płatnika API umożliwia podłączenie się do bazy aktualnie wykorzystywanej przez program e-pity Płatnika (również przez sieć lokalną) lub do bazy MS SQL. Panel serwera e-pity Płatnika API jest dostępny tylko dla użytkowników z uprawnieniami administratora i jest wyposażony w opcjonalną autoryzację zapytań dla zabezpieczenia wrażliwych danych (HTTP Basic Auth).

Interfejs programistyczny e-pity Płatnika API daje możliwość:

  • zautomatyzowania procesu importu danych do aplikacji (w formatach XML, XML e-Deklaracji, CSV);
  • zautomatyzowania wydruku dokumentów PDF z aplikacji lub bezpośrednio z pliku w formacie XML e-file (m.in. z ustawieniem jakości wydruku, pogrubienia znaków, nazw własnych plików itp.);
  • pobierania pełnych danych z formularzy zapisanych w bazie aplikacji e-pity Płatnika (w formacie JSON);
  • pobierania pełnych danych z wpisów aktówki zapisanych w bazie aplikacji e-pity Płatnika (w formacie JSON);
  • pobierania informacji o dostępnych formularzach (pełna baza formularzy programu e-pity Płatnika);
  • pobieranie informacji o dostępnych bazach/profilach;
  • generowania testowych, losowych formularzy (w formacie XML e-file).

Funkcje dostępne w standardowej wersji programu e-pity Płatnika, jak wysyłka i sprawdzanie statusów e-Deklaracji, wysyłka deklaracji e-mailem, walidacja kontrahentów NIP, konwersja formularzy, etc. zostaną zaimplementowane na indywidualne zamówienie.

Funkcje PREMIUM są dostępne w zależności od liczby zakupionych PUNKTÓW.
Wypróbuj je w wersji testowej e-pity Płatnika dla 30 formularzy.
Dowiedz się więcej o dedykowanych funkcjach e-pity Płatnika bezpośrednio u naszego konsultanta - zakładka Kontakt.

Rest API

Aplikacja e-pity Płatnika server pozwala komunikować się z aplikacją e-pity Płatnika za pomocą protokołu HTTP poprzez udostępnione REST API. Funkcjonalność ta wykorzystuje metody GET oraz POST protokołu HTTP. Całość jest prosta w obsłudze, wystarczy zainstalować aplikację na swoim serwerze i już można zacząć używać API. Dozwolone metody znajdują się w dziale dokumentacja.

Przykład - jak zwrócić listę typów formularzy:

GET http://127.0.0.1:8000/types/list

Można też określić ilość elementów na stronie oraz przejść do konkretnej strony:

GET http://127.0.0.1:8000/types/list?pageNo=3&itemsOnPage=500

Autoryzacja

Zapytania do serwera autoryzowane są za pomocą metody Basic access authentication.

Aby uzyskać autoryzację, należy dołączyć klucz poprzedzony wyrazem Basic do nagłówka Authorization zapytania. Klucz tworzony jest na podstawie loginu i hasła użytkownika aplikacji serwerowej zakodowanym do base64 wg schematu (stringlogin:hasło.

Przykład

Login: root
Hasło: toor
Klucz do zakodowania: root:toor
Klucz po zakodowaniu do base64: cm9vdDp0b29y

Nagłówek HTTP:

Authorization: Basic cm9vdDp0b29y

Kody odpowiedzi

200 OK  
400 Bad request złe parametry zapytania
401 Unauthorized brak wymaganej autoryzacji http
403 Forbidden operacja zakazana dla tego użytkownika lub licencji
404 Not Found element nie został odnaleziony
405 Not Allowed usługa w tej chwili nie jest dostępna
500 Internal Server Error inny błąd serwera

Wykonywanie zapytań

Serwer e-pity Płatnika nie jest aplikacją wielowątkową. Zapytania do serwera są wykonywane szeregowo, tj. jeżeli trzech użytkowników zleci generowanie formularzy (np. po 500 sztuk), to trzeci użytkownik musi czekać, aż zakończy się generowanie 500 formularzy pierwszego i drugiego użytkownika.

Stronicowanie zapytań

Indeks numPages zwraca liczbę stron od 1 do n, natomiast indeks pageNo od 0 do m.

W przypadku, kiedy wynik będzie rozłożony na np. osiem stron, przy wyświetlaniu ostatniej strony indeksy przyjmą odpowiednio następujące wartości:

[numPages] => 8
[pageNo] => 7

Do ustalania liczby pozycji na stronie służy zmienna itemsOnPage. Domyślną wartością po zainstalowaniu aplikacji jest 100, wartość można zmienić wchodząc w Ustawienia -> Ustawienia aplikacji. W polu Liczba elementów na stronie (dla zwracanych list) należy podać nową, domyślną wartość. Jeśli ustawimy 0 - wyniki nie będą stronicowane (UWAGA - może to powodować zbytnie obciążenie aplikacji).

Licencjonowanie

Większość funkcji e-pity Płatnika API są za darmo (wszystkie, oprócz funkcji Premium). W celu podłączenia serwera do bazy MSSQL nie jest wymagany dodatkowy abonament (jest to darmowe). 
Do wydruku formularzy, eksportowania oraz generowania e-Deklaracji (dla płatnych formularzy) wymagana jest licencja punktowa e-pity Płatnika.