Modules
Otwórz Orbito

GUS i VIES

OficjalnyDarmowy

Uzupełnia dane firmy do faktury po numerze NIP — z bazy GUS (REGON) albo VIES dla firm z UE — i sprawdza NIP w automatyzacjach.

@core·Wiktor KoźmińskiBrak recenzji2 firmy z instalacjąAktualizacja 9 października 2026
gusregonviesnipbirdane firmykontrahentfakturaweryfikacja nip
Zainstaluj w Orbito Otwiera panel Orbito na karcie modułu
Licencja
Bezpłatny
Wersja
1.4.0

GUS i VIES (core/gus)

Osobny moduł Orbito zależny od core/orders. W trybie edycji sekcji Faktura na karcie zamówienia pokazuje przy polu NIP przycisk GUS / VIES. Kliknięcie:

  • dla numeru bez prefiksu albo z prefiksem PL wyszukuje podmiot w GUS BIR1.1,
  • dla numeru z prefiksem innego kraju UE wyszukuje podmiot w VIES.

Prefiks PL jest usuwany z pola NIP. Dla numerów zagranicznych prefiks kraju pozostaje częścią numeru VAT. Moduł uzupełnia:

  • nazwę firmy,
  • NIP,
  • ulicę i numer,
  • kod pocztowy,
  • miasto,
  • kraj.

Dane są tylko wpisywane do formularza. Każde pobranie odświeża wszystkie pola, więc brak wartości w nowej odpowiedzi usuwa wartość pozostałą po wcześniejszym wyszukiwaniu. Użytkownik zatwierdza dane standardową ikoną zapisu sekcji Faktura, więc samo zapytanie nie modyfikuje zamówienia. Zakres nazwy i adresu zwracany przez VIES zależy od rejestru danego kraju.

Konfiguracja

Po instalacji otwórz konfigurację modułu i ustaw:

  1. środowisko Produkcja albo Test,
  2. klucz użytkownika GUS BIR.

Klucz jest polem typu sekret i nie jest przechowywany w repozytorium ani w paczce. Alternatywnie można przekazać go do kontenera jako GUS_BIR_API_KEY.

Dokumentacja usługi: <https://api.stat.gov.pl/Home/RegonApi>

VIES: <https://ec.europa.eu/taxation_customs/vies/>

Automatyzacje

Akcja Sprawdź NIP (check_nip) wymaga ORDER_ID z wyzwalacza. Pobiera aktualne invoice.taxNo z core/orders.getById i sprawdza obecność podmiotu w GUS. Nie zmienia danych zamówienia. Prefiks PL, spacje, myślniki i kropki są normalizowane przed walidacją długości i sumy kontrolnej.

WyjścieZnaczenie
true — PrawidłowyNIP przeszedł walidację i GUS zwrócił pasujący podmiot z numerem REGON
false — NieprawidłowyBrak NIP, nieprawidłowa długość, zapis lub suma kontrolna albo potwierdzony brak podmiotu w GUS (kod 4)
unsupported — ZagranicznyNumer z prefiksem innego kraju; akcja nie odpytuje VIES

Od wersji 1.3.0 akcja udostępnia te trzy wyjścia. W istniejących grafach połączenia z usuniętych gałęzi missing i invalid należy przenieść do wyjścia Nieprawidłowy (false).

Brak zamówienia, klucza BIR, timeout i błędna odpowiedź usługi zatrzymują bieg automatyzacji z błędem — nie prowadzą do wyjścia „Nieprawidłowy”. Odpowiedź BIR z <ErrorCode> wewnątrz <dane> jest traktowana jako komunikat, a pusta odpowiedź wymaga potwierdzenia przez GetValue('KomunikatKod') w tej samej sesji. Kontrakt: dokumentacja GUS BIR.

Przykład: Zamówienie wymaga faktury → Sprawdź NIP → Nieprawidłowy → Dodaj powiadomienie z modułu core/orders. Pozostałe wyjścia można podłączyć do osobnych kroków. Weryfikacja dotyczy obecności w REGON.

Wymagania

  • core/orders w wersji 2.6.2 lub nowszej (hook views.orderInvoiceEdit),
  • @orbito/api-lib w wersji 3.10.0 lub nowszej.

Paczka

./make-zip.sh

Archiwum zawiera tylko pliki wykonywalne i metadane modułu, bez klucza GUS, .env, node_modules i konfiguracji rejestru npm.