Weryfikacja VAT UE (VIES) – instrukcja obsługi modułu PrestaShop

1. Do czego służy moduł

Gdy sprzedajesz firmie z innego kraju UE, której numer VAT jest aktywny, nie doliczasz jej VAT, bo podatek rozlicza nabywca (odwrotne obciążenie). Konsumenci, firmy bez ważnego numeru i klienci z Twojego kraju płacą VAT jak zwykle. PrestaShop nie odróżnia tych klientów, bo w ogóle nie sprawdza numerów VAT.

Moduł sprawdza numer VAT z adresu klienta w VIES, unijnym rejestrze numerów VAT prowadzonym przez Komisję Europejską, i przekazuje wynik do naliczania podatku w PrestaShop. Zweryfikowana firma z innego kraju UE widzi ceny, dostawę i sumę zamówienia bez VAT, a wszyscy pozostali płacą VAT według Twoich reguł podatkowych. Każda odpowiedź VIES jest zapisywana, więc o ten sam numer moduł pyta najwyżej raz na okres ważności sprawdzenia. Przekroczenia czasu, awarie VIES i limity zapytań są obsługiwane i zapisywane w dzienniku. Każde zamówienie zachowuje wynik sprawdzenia, a jego faktura może mieć adnotację o odwrotnym obciążeniu.

Działa z PrestaShop 1.7.8, 8.x i 9.x (PHP 7.2.5 lub nowszy), z motywami Classic i Hummingbird oraz w trybie multistore.

2. Instalacja

1. Pobierz moduł z Moje konto → Historia zamówień w addonspresta.com.
2. W panelu administracyjnym otwórz Moduły → Menedżer modułów i kliknij Prześlij moduł.
3. Upuść plik ap_vies_v1.1.0.zip i poczekaj na potwierdzenie.
4. Kliknij Konfiguruj na karcie modułu i sprawdź ramkę Status na górze strony.

Zaraz po instalacji moduł jest włączony, a Twój kraj to domyślny kraj sklepu. Zanim zaczniesz na nim polegać:

• układ adresu każdego kraju UE, do którego sprzedajesz, musi zawierać pole Numer VAT (Międzynarodowy → Lokalizacje → Kraje → Edytuj → Format adresu, pole vat_number). Ramka Status wymienia aktywne kraje UE, w których go brakuje;
• jeśli ramka Status pokazuje stare ustawienie PrestaShop VATNUMBER_MANAGEMENT, kliknij Wyłącz stare ustawienie. To ustawienie pochodzi z dawnego modułu „vatnumber” i usuwa VAT dla każdego zagranicznego numeru bez sprawdzania go.

3. Jak to działa

Kiedy moduł pyta VIES. Numer jest sprawdzany, gdy klient zapisuje adres w sklepie (na koncie albo w zamówieniu), gdy adres jest zapisywany w panelu albo przez inny moduł, oraz gdy klient otwiera stronę zamówienia, a zapisana odpowiedź dla adresu podatkowego koszyka jest starsza niż okres ważności sprawdzenia. Sprawdzane są tylko numery z krajów UE. Przed zapytaniem moduł usuwa spacje, kropki i myślniki, przyjmuje numer z prefiksem kraju albo bez niego (dla Grecji przyjmuje GR, choć jej kod w VIES to EL) i sprawdza format używany w danym kraju, więc oczywiste literówki w ogóle nie trafiają do VIES.

Kiedy VAT jest usuwany. Muszą być spełnione wszystkie warunki:

• moduł jest włączony, a podatki w sklepie są włączone;
• adres ma numer VAT, a jego kraj należy do UE i nie jest Twoim krajem;
• numer należy do kraju z adresu;
• VIES potwierdził numer, a potwierdzenie jest młodsze niż okres ważności sprawdzenia albo, gdy VIES nie mógł go potwierdzić ponownie, młodsze niż ten okres plus okres karencji. Oznaczenie pracownika (Oznacz jako ważny / Oznacz jako nieważny) ma pierwszeństwo przed VIES.

PrestaShop nalicza wtedy 0% od produktów, dostawy i pakowania na prezent. W każdym innym przypadku Twoje reguły podatkowe działają bez zmian. Liczy się adres, którego sklep używa do podatków: adres dostawy albo adres do faktury, jeśli tak ustawiono w Międzynarodowy → Podatki.

Szybkość. Naliczanie podatku odczytuje tylko zapisane odpowiedzi z bazy danych i nigdy nie czeka na VIES. Klient czeka na VIES tylko przy zapisie adresu albo przy wejściu do zamówienia z nieaktualną odpowiedzią, najwyżej przez Limit czasu.

Błędy i limity. Gdy VIES albo system kraju członkowskiego nie odpowiada, moduł zachowuje ostatnią odpowiedź, zapisuje błąd w dzienniku i przez Przerwę po błędzie VIES nie wysyła nowych zapytań (przeciążony VIES dostaje najpierw to samo zapytanie jeszcze raz po sekundzie): do danego kraju po błędzie jego systemu albo po odpowiedzi, która nie przyszła na czas, a do całego VIES po błędzie usługi albo połączenia. Powyżej limitu Zapytań na minutę albo Zapytań na godzinę sprawdzenia czekają. Każde wstrzymane sprawdzenie trafia do dziennika jako „Nie wysłano”. Awaria VIES nigdy nie blokuje klienta.

Zamówienia i faktury. Gdy zamówienie jest składane z numerem VAT, moduł zapisuje, co odpowiedział VIES (numer, decyzję, numer konsultacji, firmę, datę). Strona zamówienia w panelu pokazuje to w ramce VAT UE (VIES), a faktura i korekta zamówienia bez VAT mają Twoją adnotację.

Sieć i prywatność. Moduł łączy się wyłącznie z usługą VIES Komisji Europejskiej (ec.europa.eu) i tylko po to, żeby sprawdzić numer. Wysyła numer VAT oraz, jeśli go podasz, Twój własny numer VAT. Nie łączy się z addonspresta.com, nie zmienia tabel PrestaShop i nie dodaje żadnych plików do sklepu.

4. Funkcje i ustawienia

Otwórz Moduły → Menedżer modułów → Weryfikacja VAT UE (VIES) → Konfiguruj. Ramka Pomoc na górze prowadzi do tej instrukcji i do strony modułu w addonspresta.com, w języku Twojego panelu.

Status

Pokazuje problemy, przez które moduł nie działa tak, jak oczekujesz (wyłączone podatki, stare ustawienie VATNUMBER_MANAGEMENT, kraje UE bez pola numeru VAT, Twój kraj spoza UE), liczbę zapytań wysłanych w ostatniej godzinie, trwające przerwy i tryb testowy.

Ustawienia podatku

Te ustawienia dotyczą sklepu wybranego w nagłówku panelu.

• Usuwaj VAT dla zweryfikowanych firm z UE — wyłącz, żeby naliczać VAT wszystkim i wstrzymać sprawdzanie w sklepie.
• Twój kraj — klienci z tego kraju zawsze płacą VAT, nawet z ważnym numerem.
• Twój numer VAT — opcjonalny. Gdy go wpiszesz, VIES przy każdym sprawdzeniu zwraca numer konsultacji, który możesz pokazać urzędowi skarbowemu jako dowód weryfikacji. Widać go w dzienniku i w zamówieniu.
• Gdy VIES uzna numer za nieważny — zapisz adres, nalicz VAT i ostrzeż klienta (domyślnie) albo nie zapisuj adresu, dopóki numer nie zostanie poprawiony lub usunięty. To samo dotyczy numeru w złym formacie. Gdy VIES nie odpowiada, adres jest zawsze zapisywany.
• Uznawaj potwierdzony numer, gdy VIES nie odpowiada — okres karencji w godzinach (od 0 do 720, domyślnie 72), liczony po okresie ważności sprawdzenia.
• Akceptuj poprawny numer, gdy VIES nie odpowiada — domyślnie wyłączone. Po włączeniu, gdy VIES nie odpowie w sprawie numeru (VIES albo system kraju nie działa, jest przeciążony albo za wolny), numer w formacie właściwym dla kraju adresu zostaje przyjęty: VAT jest usuwany, klient dowiaduje się, że numer zostanie sprawdzony ponownie, a strona zamówienia oznacza je jako „Zaakceptowany bez odpowiedzi VIES — sprawdź numer”. Numer, który VIES uznał za nieważny, ani sprawdzenie wstrzymane przez Twoje limity nigdy nie są akceptowane. Takie zamówienia sprawdź przed wystawieniem faktury.
• Adnotacja na fakturach i korektach — osobny tekst dla każdego języka, do 500 znaków, drukowany w języku zamówienia. Domyślnie: „Odwrotne obciążenie: podatek VAT rozlicza nabywca.” Dostosuj go do swojej sytuacji i zaleceń księgowego, np. dopisując artykuł dyrektywy VAT (196 dla usług, 138 dla wewnątrzwspólnotowej dostawy towarów). Zostaw puste, jeśli nie chcesz adnotacji.

Połączenie z VIES (wszystkie sklepy)

Te ustawienia są wspólne dla wszystkich sklepów instalacji, bo VIES widzi jeden serwer. Może je zmienić tylko pracownik, który zarządza wszystkimi sklepami.

• Sprawdzaj numer ponownie po — od 5 do 43 200 minut, domyślnie 60. Do tego czasu używana jest zapisana odpowiedź.
• Limit czasu — od 1 do 30 sekund, domyślnie 10 (niektóre kraje, np. Francja, odpowiadają po ok. 4 sekundach).
• Zapytań na minutę i Zapytań na godzinę — domyślnie 30 i 500.
• Zapytań na odwiedzającego na godzinę — domyślnie 10: sprawdzenia wywołane przez jednego odwiedzającego sklep (zalogowanego klienta albo gościa z danego adresu IP; wszyscy odwiedzający z jednego adresu IP razem mogą wysłać pięć razy więcej), żeby nikt nie wyczerpał limitów Twojego sklepu zmyślonymi numerami. Panelu administracyjnego ten limit nie dotyczy. Moduł zapisuje tylko zakodowany odcisk adresu IP, nigdy sam adres.
• Przerwa po błędzie VIES — od 0 do 1440 minut, domyślnie 5; 0 wyłącza przerwy.
• Przechowuj dziennik przez — od 1 do 365 dni, domyślnie 30.
• Tryb testowy — używa testowej usługi VIES zamiast prawdziwej: numer 100 jest ważny, 200 nieważny, a od 300 do 601 zwracają błędy VIES (np. 301 „system kraju niedostępny”, 500 „VIES przeciążony”). Prawdziwe numery nie dostają w trybie testowym odpowiedzi. Przed rozpoczęciem sprzedaży wyłącz go i usuń numery testowe z listy.

Sprawdź numer VAT

Wybierz kraj UE, wpisz numer i kliknij Sprawdź. Moduł od razu pyta VIES, nawet jeśli numer był niedawno sprawdzany; limity i przerwy nadal obowiązują. Przydaje się do sprawdzenia połączenia albo do odpowiedzi klientowi.

Numery VAT

Wszystkie dotąd sprawdzone numery: status, nazwa i adres firmy z VIES, ostatnie sprawdzenie, ostatnie potwierdzenie, ostatni błąd i liczba błędów z rzędu. Możesz szukać po numerze albo firmie i filtrować po statusie. Przy każdym numerze są przyciski:

• Sprawdź teraz — ponownie pyta VIES;
• Oznacz jako ważny / Oznacz jako nieważny — Twoja decyzja ma pierwszeństwo przed VIES, dopóki nie klikniesz Usuń oznaczenie; przydaje się np. wtedy, gdy system jakiegoś kraju nie działa od kilku dni, a firmę sprawdziłeś inaczej;
• Usuń — moduł zapomina numer i sprawdzi go ponownie, gdy klient znów go użyje.

Numer dotyczy wszystkich sklepów, dlatego oznaczenia i Usuń są dostępne tylko dla pracownika, który zarządza wszystkimi sklepami.

Dziennik

Każde zapytanie wysłane do VIES, każde sprawdzenie wstrzymane przez limity lub przerwy i każde oznaczenie: data, sklep, źródło (formularz adresu, zapis adresu, zamówienie, panel administracyjny), wynik z kodem VIES, czas w milisekundach i szczegóły. Zaznacz Tylko błędy, żeby zobaczyć problemy. Wyczyść dziennik usuwa wpisy sklepów wybranych w nagłówku; starsze wpisy są usuwane automatycznie po ustawionej liczbie dni.

5. Multistore

Ustawienia podatku zależą od sklepu albo grupy sklepów wybranej w nagłówku panelu, więc każdy sklep może mieć swój kraj, numer VAT, adnotację na fakturze i zachowanie przy nieważnym numerze. Ustawienia połączenia z VIES, lista numerów VAT i limity są wspólne dla wszystkich sklepów, bo numer jest ważny albo nie niezależnie od sklepu. Dziennik pokazuje sklepy wybrane w nagłówku, z kolumną Sklep. Pracownik, który nie zarządza wszystkimi sklepami, zmienia ustawienia podatku tylko po wybraniu jednego ze swoich sklepów i nie może zmieniać ustawień połączenia. Jedna licencja obejmuje wszystkie sklepy instalacji.

6. Odinstalowanie

Menedżer modułów → Weryfikacja VAT UE (VIES) → Odinstaluj usuwa ustawienia, listę numerów VAT, dziennik i wyniki VIES zapisane przy zamówieniach; od tej chwili PrestaShop znów nalicza VAT według Twoich reguł podatkowych. Już wystawione faktury się nie zmieniają. Jeśli chcesz zachować dane, użyj Wyłącz.

7. Najczęstsze pytania i problemy

Klient z ważnym numerem VAT nadal płaci VAT. Sprawdź po kolei: kraj klienta nie jest Twoim krajem; numer jest w adresie używanym do podatków (dostawy albo do faktury, zob. Międzynarodowy → Podatki); numer ma na liście status Ważny (jeśli nie, kliknij Sprawdź teraz); ramka Status nie zgłasza problemu. Ceny bez VAT pojawiają się, gdy adres zostanie wybrany w koszyku, czyli w trakcie składania zamówienia.

Klient nie może wpisać numeru VAT. W układzie adresu jego kraju brakuje pola numeru VAT. Dodaj vat_number w Międzynarodowy → Lokalizacje → Kraje → Edytuj → Format adresu.

Niemieckie numery zwracają błąd w nocy. Niemiecki system bywa w VIES niedostępny przez kilka godzin w nocy („System kraju niedostępny”). Numery potwierdzone wcześniej zachowują ceny bez VAT przez okres karencji. Nowe numery płacą VAT do odpowiedzi VIES — albo, z opcją Akceptuj poprawny numer, gdy VIES nie odpowiada, od razu dostają ceny bez VAT i są sprawdzane ponownie później.

W dzienniku jest „System kraju niedostępny”. System VAT tego kraju członkowskiego nie działa, co regularnie zdarza się w czasie prac serwisowych. Klienci potwierdzeni wcześniej zachowują ceny bez VAT przez okres karencji, a nowe numery są sprawdzane ponownie po przerwie. Jeśli system nie działa przez kilka dni, sprawdź firmę inaczej i użyj Oznacz jako ważny.

W dzienniku jest „VIES przeciążony” albo „Twój serwer jest zablokowany przez VIES”. VIES ogranicza liczbę zapytań. Zmniejsz Zapytań na minutę i Zapytań na godzinę i wydłuż Sprawdzaj numer ponownie po. Blokada zwykle mija po pewnym czasie.

Czy klient może wpisać numer VAT innej firmy? VIES potwierdza, że numer jest aktywny, a nie kto go wpisał. Zamówienie zachowuje nazwę i adres firmy zwrócone przez VIES, widoczne w ramce VAT UE (VIES) zamówienia: porównaj je z adresem klienta, zanim wyślesz duże zamówienie.

Czy moduł zmienia moje reguły podatkowe albo ceny? Nie. Mówi tylko PrestaShop, żeby naliczył 0% dla zweryfikowanej firmy z innego kraju UE. Reguły podatkowe, ceny i grupy klientów zostają bez zmian.

Klienci piszą, że ich numeru „nie udało się sprawdzić”, choć VIES działa. Poszukaj w dzienniku wpisu „Nie wysłano: osiągnięto limit odwiedzającego”. Zalogowani klienci są liczeni po koncie, goście po adresie IP, a wszyscy odwiedzający z jednego adresu razem do pięciokrotności limitu. Jeśli sklep działa za CDN albo serwerem pośredniczącym, który ukrywa adresy odwiedzających, wszyscy goście mają ten sam adres: ustaw na serwerze przekazywanie prawdziwego adresu (np. opcję „real IP” dla Cloudflare u hostingodawcy) albo zwiększ Zapytań na odwiedzającego na godzinę.

Co napisać w adnotacji na fakturze? Zapytaj księgowego. Przy usługach zwykle stosuje się „Odwrotne obciążenie” (art. 196 dyrektywy 2006/112/WE), przy towarach wysyłanych do innego kraju UE — „Wewnątrzwspólnotowa dostawa towarów” (art. 138).

8. Aktualizacje i wsparcie

Aktualizacje są bezpłatne dożywotnio: nowe wersje pobierasz z Moje konto → Historia zamówień w addonspresta.com i wgrywasz jak nowy moduł. Ustawienia, numery VAT, dziennik i dane zamówień zostają zachowane.

Wsparcie obejmuje 12 miesięcy od zamówienia: napisz na mail@addonspresta.com albo przez formularz kontaktowy w addonspresta.com (od poniedziałku do piątku, 10:00–16:00; odpowiadamy zwykle w ciągu 2 dni roboczych). Podaj wersję PrestaShop, wersję modułu i kroki, które prowadzą do problemu.

Wróć do: Instrukcje modułów