API ViesVAT — integracja weryfikacji VAT UE

Nasze API REST jest dla firm i deweloperów, którzy chcą zintegrować weryfikację VIES z własnymi systemami. Oferujemy 99,5% SLA, kolejkowanie zapytań, automatyczne retry po awarii rejestru krajowego, webhooki do alertów o zmianach statusu kontrahentów oraz panel z pełną historią zapytań i raportami PDF dla audytu.

Kiedy potrzebujesz API zamiast ręcznej weryfikacji

Ręczna weryfikacja przez wyszukiwarkę wystarcza, gdy fakturujesz wewnątrzunijnie do ~20 transakcji miesięcznie. Powyżej tego progu ręczne sprawdzanie staje się źródłem trzech kategorii błędów. Pierwsza: zapominanie weryfikacji — przy presji czasu księgowy wystawia fakturę bez sprawdzenia, zauważając problem dopiero po fakcie. Druga: brak zapisu identyfikatora konsultacji — wpisanie wyniku do uwag faktury, ale bez kluczowego identyfikatora, który stanowi dowód. Trzecia: literówki w numerach VAT przy ręcznym przepisywaniu z dokumentów źródłowych. API rozwiązuje wszystkie trzy: każda faktura WDT jest automatycznie poprzedzona zapytaniem VIES, identyfikator konsultacji jest zapisywany razem z fakturą w bazie danych systemu, a w razie nieaktywnego numeru system blokuje wystawienie faktury z 0% VAT i wyświetla ostrzeżenie. Dodatkowo: dla firm z setkami stałych kontrahentów API umożliwia comiesięczne re-sprawdzenie całej bazy w jednym batch'u, wychwytując kontrahentów, którzy wypadli z VIES.

Endpointy REST — pełna specyfikacja

Główny endpoint pojedynczego sprawdzenia: GET /api/v1/check?country=DE&vat=123456789. Zwraca JSON z polami valid (boolean), name (string), address (string), requestDate (ISO 8601 timestamp), consultationNumber (string, 16 znaków), countryCode (string, 2 znaki), cached (boolean — czy odpowiedź z cache 24h), latencyMs (number — czas odpowiedzi VIES). Endpoint masowy: POST /api/v1/batch z body {numbers: [{country, vat}, ...]}. Maksymalnie 1000 numerów w jednym batch'u. Zwraca natychmiast batchId, wyniki dostarczane są webhookiem lub przez polling GET /api/v1/batch/{batchId}. Endpoint historii: GET /api/v1/history?country=DE&vat=123456789 zwraca wszystkie wcześniejsze weryfikacje tego samego numeru z Twojego konta — przydatne dla dokumentacji wstecznej. Sandbox endpoint: /api/v1/sandbox/check zwraca deterministyczne testowe dane bez konsumowania quoty VIES. Wszystkie endpointy wymagają nagłówka Authorization: Bearer YOUR_API_KEY.

Autentykacja i klucze API

Klucz API otrzymujesz natychmiast po rejestracji w panelu klienta — to ciąg ok. 40 znaków rozpoczynający się od svies_pk_ (production) lub svies_sk_ (sandbox). Wysyłaj jako nagłówek Authorization: Bearer svies_pk_xyz... Klucz może być skopiowany w wielu projektach, ale dla rozliczeń per-projekt udostępniamy sub-klucze z osobnym licznikiem zapytań. W panelu możesz zobaczyć: liczbę zapytań w bieżącym okresie, top 10 najczęściej sprawdzanych numerów, kraje z których pochodziły zapytania, średni czas odpowiedzi. Rotacja kluczy: w panelu klikasz „Generuj nowy klucz” — stary klucz zostaje ważny przez 24 godziny, by umożliwić zero-downtime deployment w produkcji. Po 24 godzinach stary klucz przestaje działać. Klucze nigdy nie powinny trafiać do kodu klienckiego (przeglądarka, aplikacja mobilna) — tylko do backendu.

Stabilność i strategia retry

Oficjalny VIES KE bywa niedostępny dla pojedynczych krajów (Niemcy, Włochy, Hiszpania najczęściej) przez 15–60 minut. Nasze API automatycznie wykrywa odpowiedź typu MS_UNAVAILABLE (kraj członkowski niedostępny) i kolejkuje zapytanie z exponential backoff: pierwsza ponowna próba po 1 minucie, druga po 5 minutach, trzecia po 15 minutach, czwarta po 1 godzinie. Po czterech nieudanych próbach uznajemy awarię za długotrwałą i informujemy Cię webhookiem. W ten sposób Twoja integracja nigdy nie zwraca błędu „brak odpowiedzi” — albo otrzymuje status, albo zapytanie pozostaje w kolejce i informuje Cię webhookiem po sukcesie. Dla wymagających klientów (Business+) udostępniamy alternatywny endpoint /api/v1/check-sync, który blokuje response do otrzymania ostatecznego wyniku z VIES (timeout 60s) — przydatny dla synchronicznych workflow, gdzie webhook jest niepraktyczny.

SDK i biblioteki — pełna lista

Udostępniamy oficjalne SDK dla popularnych języków, utrzymywane na GitHubie. PHP: kompatybilne z Laravel, Symfony, WordPress/WooCommerce; instalacja przez Composer (viesvat/php-sdk); zawiera helpery dla popularnych frameworków fakturowych (FakturaXL, BiznesPlus). Python: klient asynchroniczny aiohttp; instalacja przez PyPI (pip install viesvat); type hints; obsługa Django, FastAPI, Flask. Node.js: pakiet @viesvat/sdk; pełne typy TypeScript; obsługa Express, NestJS, Next.js API routes. .NET: NuGet ViesVAT.Sdk; .NET 6, 7, 8, 9; integracja z Entity Framework. Java: Maven Central pl.viesvat:sdk; Java 11+; obsługa Spring Boot. Każde SDK zawiera: typy DTO dla request/response, automatyczny retry z exponential backoff, cache wbudowany (24h zgodnie z zaleceniem KE), helpery „validateBeforeInvoice” które rzucają wyjątek jeśli VAT nie jest aktywny, oraz integracje z popularnymi frameworkami logowania (Monolog, structlog, Winston, Serilog, SLF4J).

Webhooki i alerty — proaktywne monitorowanie

API obsługuje webhooki dla trzech głównych zdarzeń. Pierwsze: statusChanged — gdy numer kontrahenta, który wcześniej był aktywny, stał się nieaktywny (codzienna ponowna weryfikacja w godzinach 3:00 CET). Przydatne dla wykrywania, że stały klient wypadł z VIES — np. likwidacja firmy, wygaśnięcie VAT-UE — zanim wystawisz mu kolejną fakturę. Drugie: batchCompleted — zakończenie zapytania masowego (batch). Trzecie: registryDown — wykrycie awarii rejestru krajowego, który ma wpływ na Twoich kontrahentów (mamy konkretne numery z tego kraju w Twojej bazie). Webhooki pozwalają zbudować proaktywne systemy alertujące — np. powiadomienie księgowości przez Slack/Teams/e-mail, gdy stały kontrahent DE wypadł z VIES. Format webhooka: POST na zadefiniowany URL z body JSON i nagłówkiem X-Signature (HMAC-SHA256). Retry dostawy: 1 min, 5 min, 30 min, 2h, 6h — potem do dead-letter queue. Zalecane: implementacja idempotencji po stronie odbiorcy (każdy webhook ma unikalny eventId).

Buforowanie wyników — 24h cache

Komisja Europejska oficjalnie zaleca, by nie wysyłać tego samego zapytania wielokrotnie w ciągu 24 godzin. Nasze API implementuje automatyczne buforowanie: gdy w ciągu 24h ostatnio sprawdziłeś już dany numer, kolejne zapytanie zwraca wynik z cache (oznaczony cached: true w odpowiedzi), bez konsumowania quoty VIES. Dla Ciebie oznacza to: oszczędność quoty (znacząca dla firm z stałą bazą kontrahentów — np. 100 stałych klientów = 100 zapytań/dzień zamiast tysięcy), szybszą odpowiedź (cache zwraca w <50ms vs ~1000ms z VIES), mniejsze ryzyko trafienia na chwilową awarię rejestru. Cache nigdy nie przekracza 24h — to limit ostrożnościowy, bo status w VIES może się zmienić każdej chwili. Dla zastosowań wymagających absolutnej świeżości (np. dzień wystawiania faktury) dodaj parametr ?nocache=true w zapytaniu — wymusi świeże zapytanie do VIES.

Cennik i plany — szczegółowo

Plan Free: 100 zapytań/miesiąc, bez SLA, idealny do testów i małych integracji. Dostęp do sandbox bez limitów. Plan Pro: 49 EUR/miesiąc lub 499 EUR/rok (-15%). 10 000 zapytań/miesiąc, SLA 99,5% (jeśli niedotrzymane, zwrot proporcjonalny), webhooki, historia 1 rok, raporty PDF, sub-klucze. Plan Business: 199 EUR/miesiąc lub 1999 EUR/rok. Nielimitowane zapytania w ramach fair use, SLA 99,9%, dedykowany manager, historia 7 lat (audit-ready), multi-tenant dla biur rachunkowych, integracja z popularnymi ERP w cenie. Plan Enterprise: od 999 EUR/miesiąc. On-premise option (Docker images), własny SLA, integracja z dowolnym ERP, dedykowany account manager z Polski, 24/7 phone support. Wszystkie plany zawierają archiwizację identyfikatorów konsultacji minimum 1 rok (Free) lub 7 lat (Pro+) — zgodnie z polskim wymogiem przechowywania dokumentów księgowych.

Przykład produkcyjny — sprawdzenie przed fakturą

Typowy flow w systemie fakturowym z naszym SDK PHP: gdy księgowa klika „Wystaw fakturę WDT” w panelu, system woła $sviesClient->validateBeforeInvoice('DE', '123456789'). Metoda wewnętrznie sprawdza cache (24h), jeśli brak — woła API ViesVAT, dostaje wynik z identyfikatorem konsultacji. Jeśli valid=true, metoda zwraca pełen obiekt VatCheck zawierający name, address, consultationNumber. System fakturowy zapisuje consultationNumber w polu vies_check_id w bazie faktur, wystawia fakturę z 0% VAT i adnotacją „WDT — reverse charge, art. 138 dyrektywy 2006/112/WE”. Jeśli valid=false, metoda rzuca VatInvalidException — system fakturowy łapie wyjątek, pokazuje ostrzeżenie księgowej („Kontrahent nieaktywny w VIES — fakturujesz z 23% VAT?”) i blokuje wystawienie z 0% VAT. Jeśli VIES nie odpowiada (MS_UNAVAILABLE), SDK automatycznie ponawia w tle przez retry queue — księgowa otrzymuje wynik z webhooka albo nadal ma wynik z cache (jeśli sprawdzony niedawno).

RODO i powierzenie przetwarzania

Korzystając z API, przetwarzamy w Twoim imieniu dane numerów VAT Twoich kontrahentów — co kwalifikuje ViesVAT jako procesora w rozumieniu RODO. Dla wszystkich klientów udostępniamy gotową umowę powierzenia przetwarzania danych (DPA) — zgodną z art. 28 RODO. Plan Free i Pro: DPA dostępna do pobrania w panelu klienta po pierwszym logowaniu, automatyczna akceptacja przy korzystaniu z API. Plan Business i Enterprise: DPA podpisywana indywidualnie z możliwością negocjacji niestandardowych klauzul. Hosting wyłącznie w UE (Frankfurt OVH, Warszawa Equinix). Bezpieczeństwo: szyfrowanie TLS 1.3 w transporcie, AES-256 w spoczynku, regularne testy penetracyjne kwartalne, audyty zewnętrzne roczne, oddzielne środowiska produkcyjne i deweloperskie, uwierzytelnianie dwuskładnikowe dla wszystkich kont admin. W razie incydentu bezpieczeństwa powiadamiamy klientów w ciągu 72 godzin zgodnie z RODO.

Monitoring i obserwowalność integracji

Dla profesjonalnych integracji udostępniamy pełny stack obserwowalności. Dashboard w panelu klienta pokazuje w czasie rzeczywistym: liczbę zapytań w bieżącej godzinie/dniu/miesiącu, średnią latencję per kraj, top błędów (które rejestry krajowe miały MS_UNAVAILABLE), wykorzystanie quoty względem planu, prognozę przekroczenia limitu. Alerty: konfigurowalne progi (np. powiadom mnie, gdy 80% quoty wykorzystane), kanały dostarczenia (e-mail, Slack webhook, Discord webhook, PagerDuty dla Enterprise). Eksport metryk: endpoint Prometheus pod /api/v1/metrics (autoryzowany), zwraca dane w formacie Prometheus exposition (countery zapytań, histogramy latencji, gauges aktualnych połączeń). Dla klientów Business z własną infrastrukturą observability wspieramy też integrację z Grafana Cloud, Datadog (przez ich Custom Metrics API) i New Relic. Logi: każde zapytanie ma unikalny request_id widoczny w odpowiedzi i w panelu — jeśli widzisz dziwne zachowanie, podaj wsparciu request_id, błyskawicznie znajdziemy w logach pełen kontekst zapytania.

Migracja z innego dostawcy — proces i wsparcie

Jeśli używasz dziś innego dostawcy API VIES (VATlayer, vatcheckapi.com, vies-api.com lub własnej integracji bezpośrednio z KE SOAP) i rozważasz migrację do ViesVAT, przygotowaliśmy ułatwioną procedurę. Krok 1: rejestracja w naszym panelu i wygenerowanie klucza API. Krok 2: nasze SDK obsługują schematy popularnych konkurentów przez warstwę kompatybilności — w PHP wystarczy zmienić $client = new VatlayerClient() na $client = new SprawdzViesClient() i podać nasz endpoint, reszta kodu działa bez zmian. Krok 3: bezpłatny audyt Twojej obecnej integracji przez naszego dewelopera — w 1 godzinę identyfikujemy potencjalne problemy i sugerujemy ulepszenia. Krok 4: migracja produkcyjna — rekomendujemy stopniowe przełączanie ruchu (najpierw 10% w canary deployment, potem 50%, potem 100%) z monitoringiem porównawczym wyników. Cały proces dla typowego klienta zajmuje 3–5 dni roboczych. Dla planu Business migracja jest wliczona w cenę pierwszego miesiąca — bez dodatkowych opłat. Klienci, którzy migrowali do nas z VATlayer i vatcheckapi w 2025 raportują średnio 30% niższy total cost (mniej overage, więcej zapytań w cache 24h, lepsze SLA dla MS_UNAVAILABLE).

Najczęściej zadawane pytania

W tej sekcji