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
Host: viesapi.eu:443
Authorization: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"
User-Agent: VIESAPIClient/client_version platform_name/platform_version
Accept: mime_type

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 klienta API (w naszych bibliotekach jest to wersja środowiska bibliotecznego np. 17 dla JAVA, lub 7.4 dla PHP),
  • mime_type – nazwa typu MIME, w jakim powinna zostać zwrócona odpowiedź, obsługiwane są dwa typy: text/xml oraz application/json, jeśli żądanie nie zawiera nagłówka Accept, domyślnie zwracany jest kod XML.

Żądanie uwierzytelnienia

Dane autoryzacyjne muszą być przygotowane zgodnie z Uwierzytelnianie HTTP: Uwierzytelnianie dostępu MAC i jest to zalecana metoda uwierzytelniania. Istnieje również możliwość skorzystania z ww Uwierzytelnianie HTTP: Uwierzytelnianie podstawowe metody, jednakże ze względów bezpieczeństwa prosimy o jej stosowanie tylko wtedy, gdy z jakiegoś powodu użycie pierwszej metody nie jest możliwe.

Każde zapytanie do naszego serwisu musi zostać uwierzytelnione przy użyciu jednej z dwóch dostępnych metod.

Metoda 1 – HMAC (zalecana)

Specyfikacja zastosowanej metody autoryzacji: Uwierzytelnianie HTTP: Uwierzytelnianie dostępu MAC. Autoryzacja polega na wyliczeniu HMAC SHA256 z odpowiednio przygotowanego ciągu znaków 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

Metoda 2 — Uwierzytelnianie podstawowe

Specyfikacja zastosowanej metody autoryzacji: Uwierzytelnianie HTTP: Uwierzytelnianie podstawowe.

Przykład 1

Ciąg wejściowy do funkcji Base64 to:

str = key_id + ':' + key

Gdzie:

  • key_id – Identyfikator klucza API (w przypadku środowiska testowego, test_id strunowy),
  • key – Klucz API (w przypadku środowiska testowego string test_key).

Dla środowiska testowego ciąg wejściowy dla funkcji Base64 będzie wyglądał następująco:

str = "test_id:test_key"

Po zastosowaniu funkcji Base64 otrzymujemy:

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

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

Authorization: Basic dGVzdF9pZDp0ZXN0X2tleQ==

Przykład 2

Poniższy przykład przedstawia zapytanie, które można wywołać w środowisku testowym z poziomu przeglądarki internetowej. Po prostu skopiuj i wklej go w pasku adresu przeglądarki:

https://test_id:test_key@viesapi.eu/api-test/get/vies/euvat/PL7171642051

Gdzie:

  • test_id – do uwierzytelnienia w produkcji środowisko, parametr powinien zawierać poprawny identyfikator klucza używanego do autoryzacji,
  • test_key – do uwierzytelnienia w produkcji środowisku, parametr powinien zawierać poprawną wartość klucza używanego do autoryzacji.

Identyfikator klucza oraz klucz są generowane przez użytkownika po zalogowaniu się na jego konto w serwisie viesapi.eu portal (API keys patka). See dokumentacja aby uzyskać więcej informacji na temat generowania identyfikatorów i kluczy.

Odpowiedź

Jeśli żądanie zostanie obsłużone poprawnie, generowana jest następująca odpowiedź:

Szczegółowy opis zwracanych atrybutów:

  • uid – unikalny identyfikator zapytania generowany przez viesapi.eu,
  • countryCode – kod kraju, w którym zarejestrowana jest firma powiązana z podanym w zapytaniu numerem VAT UE,
  • vatNumber – podany w zapytaniu numer VAT UE weryfikowanej firmy,
  • valid – odpowiedź z serwisu VIES, informująca o aktualnym statusie VAT UE sprawdzanego podmiotu:
    • true – podany w zapytaniu numer VAT UE jest aktualny,
    • false – podany w zapytaniu numer VAT UE jest nieprawidłowy,
  • traderName – nazwa handlowa firmy,
  • traderCompanyType – zawsze zwracał ciąg znaków '-',
  • traderAddress – adres firmy, pod którą firma jest zarejestrowana,
  • id – unikalny identyfikator zapytania generowany przez system VIES
  • date – data wykonania zapytania
  • source – źródło danych, zawsze: http://ec.europa.eu

Odpowiedź na błąd

W przypadku jakiegokolwiek błędu związanego z obsługą żądania, zwracany jest następujący komunikat o błędzie:

Błąd

Szczegółowy opis zwracanych atrybutów:

  • code – unikalny kod błędu do automatycznej obsługi błędów,
  • description – opis błędu możliwego do przechwycenia przez człowieka,
  • details - Mrudy szczegółowy opis błędu (opcjonalnie),