Dokumentacja API REST

Wstęp

Udostępniane przez nas API wykorzystuje standardowy protokół HTTP. Wszystkie funkcje API korzystają z metody HTTP GET. Każde wywołanie funkcji wymaga autoryzacji zapytania. Dane do autoryzacji zapytania przesyłane są w nagłówku HTTP.

Usługa produkcji

Wymagana jest rejestracja podmiotu, który chce korzystać z funkcjonalności systemu viesapi.eu. Aby to zrobić, przejdź do Rejestracja stronę i wypełnij odpowiedni formularz. Warunkiem korzystania z systemu viesapi.eu jest akceptacja Warunki usługi. Poprawne wypełnienie formularza i kliknięcie Zarejestrować przycisk założy konto w systemie viesapi.eu i jego automatyczną aktywację.

Przy pierwszym logowaniu generowany jest automatycznie identyfikator wraz z odpowiednim kluczem. Identyfikator jest publiczny i nie wymaga ochrony, natomiast klucz jest prywatny i nie powinien być udostępniany osobom trzecim.

Adres serwisu produkcyjnego: https://viesapi.eu/api

Usługa testowa

Pełną funkcjonalność wszystkich bibliotek współdzielonych można sprawdzić za pomocą udostępnionej Przetestuj API VIES. Korzystając z testowego API można sprawdzić wszystkie funkcje oferowane w płatnych planach bez konieczności zakładania konta.

Adres serwisu testowego: https://viesapi.eu/api-test

Definicja interfejsu API

Szczegółowa definicja API jest dostępna w formacie zgodnym z OpenAPI i można ją pobrać jako plik YAML tutaj.

API jest również dostępne jako interfejs klienta Swagger UI.

Wykonanie zapytania

Przykład wykonania zapytania do serwisu testowego:

GET /api-test/get/vies/euvat/PL7171642051 HTTP/1.1
Gospodarz: viesapi.eu:443
Autoryzacja: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"
User-Agent: VIESAPIClient/wersja_klienta nazwa_platformy/wersja_platformy

Gdzie:

  • api_key_id – identyfikator klucza API (na środowisku produkcyjnym wartość identyfikatora wygenerowanego podczas rejestracji, na środowisku testowym wartość test_id),
  • unix_timestamp – aktualny czas w postaci liczby sekund od tzw Epoka Uniksa,
  • random_str – losowy ciąg, inny dla każdego zapytania (min. 8 znaków, max. 16 znaków),
  • b64_calculated_mac_value – obliczony HMAC (za pomocą API key, wartość test_key na środowisku testowym),
  • client_version – wersja kliencka (w naszych bibliotekach jest to wersja naszej biblioteki API np. 1.2.3),
  • platform_name – nazwa platformy klienckiej API (w naszych bibliotekach jest to nazwa języka biblioteki np. JAVA, PHP, .NET, Python),
  • platform_version – Wersja platformy klienckiej API (w naszych bibliotekach jest to wersja środowiska bibliotecznego np. 17 dla JAVA lub 7.4 dla PHP).

Wszystkie odpowiedzi zwracane przez serwis są w formacie XML.

Żądanie uwierzytelnienia

Specyfikacja zastosowanej metody autoryzacji: Uwierzytelnianie HTTP: Uwierzytelnianie dostępu MAC. Każde zapytanie skierowane do naszej witryny musi zostać uwierzytelnione tą metodą. Autoryzacja polega na obliczeniu HMAC SHA256 z odpowiednio przygotowanego ciągu i przesłaniu wyniku w nagłówku HTTP.

Przykład

Ciąg wejściowy do funkcji HMAC to:
ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'

Gdzie:

  • ts – aktualny czas w postaci liczby sekund od tzw Epoka Uniksanależy zawsze podawać aktualny czas wykonania zapytania (tolerancja serwera +/- 10 min w stosunku do aktualnego czasu),
  • nonce – losowy ciąg, inny dla każdego zapytania (min. 8 znaków, max. 16 znaków),
  • method – nazwa metody HTTP (zawsze GET),
  • path – ścieżka URL zapytania do wykonania,
  • host – Nazwa serwera VIES API (zawsze viesapi.eu),
  • port – numer portu serwera VIES API (zawsze 443),
  • ’\n’ – znak nowej linii (kod ASCII 10, 0x0A).

Dla zapytania o NIP PL7171642051 wysłanego do usługi testowej w dniu 2019-11-25 00:00:00 UTC ciąg wejściowy do funkcji HMAC będzie wyglądał następująco:
str = "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n"

Plik wejściowy z ciągiem znaków dla tego przykładu można pobrać tutaj.

Z przygotowanego ciągu obliczamy HMAC SHA256, jako hasło HMAC, które podajemy API key, czyli w przypadku testowego API, wartość test_key:

HMAC_SHA256(str, "test_key") = 7776a12b958233ce60dd0f16b8d141e80472a1ee3b1e1fb136d7abe34cb59306

Funkcja HMAC SHA256 zwraca 32 bajty binarne (pokazane powyżej jako a hex ciąg dla czytelności). Pobierz plik z wartością binarną tutaj.

Wartość binarną wyliczonego HMAC należy zakodować algorytmem Base64, otrzymujemy:

d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY=

Wartość tę należy przesłać jako wartość MAC w nagłówku z danymi do autoryzacji. Wreszcie:

Authorization: MAC id="test_id", ts="1574640000", nonce="dt831hs59s", mac="d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY="

Na komputerze z systemem Linux wymaganą wartość MAC można obliczyć w jednym kroku za pomocą tego polecenia:

$ echo -e -n "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n" | openssl dgst -sha256 -hmac "test_key" -binary | openssl enc -base64