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
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 (zawszeviesapi.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 = identyfikator_klucza + „:” + klucz
Gdzie:
key_id
– Identyfikator klucza API (w przypadku środowiska testowego,test_id
strunowy),key
– Klucz API (w przypadku środowiska testowego stringtest_key
).
Dla środowiska testowego ciąg wejściowy dla funkcji Base64 będzie wyglądał następująco:
str = "id_testu:klucz_testu"
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:
Autoryzacja: podstawowa 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 VIESdate
– data wykonania zapytaniasource
– ź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:
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),