Dokumentacja API REST

Dokumentacja REST interfejsu API VIES

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),

Kody błędów

Poniższa tabela zawiera listę wszystkich możliwych błędów zwracanych przez interfejsy API REST i biblioteki programistyczne:

Kod błędu Komunikat o błędzie
8 Nieprawidłowy format żądania
10 Nieprawidłowa ścieżka API
11 Wewnętrzny błąd usługi
22 Numer VAT UE jest nieprawidłowy
23 Nie udało się pobrać danych z systemu VIES
26 Ta funkcja nie jest dostępna w aktualnie wybranym planie
27 Ta funkcja nie obsługuje tego trybu wyszukiwania
33 Zapytanie o podane dane nie jest możliwe w trybie testowym
35 Nie jest wymagana autoryzacja zapytania dostępu
36 Usługa jest tymczasowo niedostępna ze względu na zaplanowane prace techniczne
43 Nie udało się pobrać liczby zapytań użytkowników w bieżącym miesiącu
54 Nieprawidłowa data lub godzina na komputerze lub systemie użytkownika
55 Nieprawidłowa wartość ciągu MAC w nagłówku z danymi uwierzytelniającymi zapytania
57 Nieprawidłowa wartość klucza w nagłówku z danymi uwierzytelniającymi zapytania
58 Osiągnięto maksymalną liczbę jednoczesnych zapytań dla tego państwa członkowskiego
59 Aplikacja w państwie członkowskim nie odpowiada lub jest niedostępna
101 Numer IP połączenia nie zgadza się z numerem IP przypisanym do klucza API
102 Klucz API jest zablokowany
103 Nieprawidłowy klucz API
104 Osiągnięto maksymalną liczbę zapytań dostępną dla wybranego planu
105 Konto zablokowane lub usunięte
106 Nieprawidłowy typ konta
107 Konto przedpłacone nie zostało opłacone
108 Nieprawidłowy identyfikator klucza API
201 Nie udało się połączyć z usługą API VIES
202 Odpowiedź usługi API VIES ma nieprawidłowy format
203 Nieprawidłowy typ numeru
204 NIP jest nieprawidłowy
205 Numer identyfikacyjny VAT UE jest nieprawidłowy
206 Funkcja wygenerowała wyjątek
207 Data ma nieprawidłowy format
208 Nieprawidłowy parametr wejściowy