← Blog
API4 min czytania

Dane firmy po numerze NIP w Laravelu — API GUS REGON (BIR) i biała lista VAT

Jak automatycznie uzupełniać dane kontrahenta po NIP: API BIR z rejestru REGON (SOAP, klucz, raporty, sesja), gotowa biblioteka PHP, biała lista podatników VAT i to, jak spiąć je w Laravelu z cache i kolejkami, żeby nie wpaść w limity.

Wpisanie numeru NIP i automatyczne uzupełnienie nazwy, adresu i danych rejestrowych firmy to jedna z tych funkcji, które użytkownicy biorą za oczywistość. Za kulisami stoją dwa publiczne API: BIR z rejestru REGON prowadzonego przez GUS i API wykazu podatników VAT (tzw. białej listy) Ministerstwa Finansów. Korzystamy z nich m.in. w CRM dla brokerów finansowych, gdzie dane klientów uzupełniają się same. Poniżej, jak to działa i jak to zrobić porządnie w Laravelu. Stan na wrzesień 2026.

API BIR (REGON)

Dokumentacja, wersje i klucz

Dokumentacja jest na portalu api.stat.gov.pl. Dostępne są dwie wersje usługi: BIR 1.1 i nowsza BIR 1.2 (od grudnia 2024), która m.in. obsługuje kody PKD 2025 i dłuższe numery lokali w adresach.

Do produkcji potrzebny jest klucz użytkownika, o który występuje się mailowo do GUS (podając m.in. dane firmy, osobę kontaktową i adresy IP, z których będą szły zapytania). Do testów GUS udostępnia środowisko testowe z publicznym kluczem abcde12345abcde12345 i zanonimizowaną, historyczną kopią danych.

Protokół i operacje

BIR to usługa SOAP 1.2 z nagłówkami WS-Addressing. Przebieg zapytania:

  1. Zaloguj z kluczem — zwraca identyfikator sesji, który dołącza się do kolejnych żądań w nagłówku HTTP sid.
  2. DaneSzukajPodmioty — wyszukanie po NIP, REGON albo KRS (albo po liście do 20 numerów). Odpowiedź zawiera m.in. typ podmiotu, który decyduje, jaki raport pobrać dalej.
  3. DanePobierzPelnyRaport — pełne dane w wybranym raporcie, np. BIR11OsPrawna dla osób prawnych albo BIR11OsFizycznaDzialalnoscCeidg dla jednoosobowych działalności (w wersji 1.2 z prefiksem BIR12).
  4. GetValue — m.in. kod i treść komunikatu po nieudanym wyszukiwaniu czy status sesji.
  5. Wyloguj na koniec.

Odpowiedzi zawierają dane w XML zapisanym jako tekst, który trzeba osobno sparsować. Przy takiej kombinacji — SOAP 1.2, WS-Addressing, nagłówek sesji — wbudowany SoapClient bywa kłopotliwy, dlatego sięgamy po bibliotekę.

Biblioteka gusapi/gusapi

Najpopularniejsza biblioteka PHP to gusapi/gusapi. Obsługuje logowanie, wyszukiwanie i pobieranie raportów:

use GusApi\GusApi;

$gus = app()->isProduction()
    ? new GusApi(config('services.gus.key'))
    : new GusApi('abcde12345abcde12345', 'dev');

$gus->login();

$reports = $gus->getByNip($nip);

Dla każdego znalezionego podmiotu pełne dane pobiera się metodą getFullReport($report, $reportType), dobierając typ raportu (stałe w klasie ReportTypes) do typu podmiotu — inny raport dotyczy spółki, inny jednoosobowej działalności.

Warto wiedzieć, że biblioteka obsługuje BIR 1.1. Jeśli potrzebujesz pól dostępnych tylko w 1.2 (np. PKD 2025), sprawdź aktualny stan projektu albo przygotuj własną obsługę raportów 1.2.

Biała lista podatników VAT

API wykazu podatników VAT jest prostsze: REST, bez klucza. Zwraca status VAT podmiotu, dane rejestrowe i — co najważniejsze przy płatnościach — zgłoszone rachunki bankowe.

$response = Http::baseUrl('https://wl-api.mf.gov.pl')
    ->get("/api/search/nip/{$nip}", ['date' => now()->toDateString()])
    ->throw()
    ->json('result');

Każda odpowiedź ma requestId, który warto zapisać — to potwierdzenie, że rachunek był sprawdzony danego dnia. Limity są niskie: około 100 zapytań wyszukujących dziennie (do 30 podmiotów w jednym zapytaniu) i kilka tysięcy zapytań sprawdzających rachunek. Przy dużej liczbie kontrahentów lepiej korzystać z codziennie publikowanego pliku płaskiego.

Jak spinamy to w Laravelu

  • Serwis z jednym interfejsem — CompanyLookup::byNip() zwraca znormalizowany obiekt z nazwą, adresem, REGON, KRS i statusem VAT, niezależnie od tego, z którego API pochodzą dane.
  • Cache — dane firmy zmieniają się rzadko, więc wynik trzymamy w cache i nie odpytujemy GUS przy każdym otwarciu formularza. To także ochrona przed limitami.
  • Kolejki — masowa aktualizacja danych kontrahentów (np. co noc) idzie w kolejce, porcjami, z przerwami między zapytaniami.
  • Logowanie — każde zapytanie zapisujemy z wynikiem; przy danych, na podstawie których podejmuje się decyzje (np. rachunek do przelewu), to ślad audytowy.
  • Obsługa braku danych — nieznaleziony podmiot, przerwa techniczna usługi, wygasła sesja: każdy przypadek ma własny komunikat dla użytkownika zamiast ogólnego błędu.
  • Testy — w testach podmieniamy klientów API na atrapy (Http::fake() dla białej listy, mock serwisu dla BIR), a środowisko testowe GUS zostawiamy do testów integracyjnych.

Te same zasady stosujemy przy innych rejestrach, np. CEIDG, KRS i SUDOP — w CRM dla brokerów synchronizacja z rejestrami działa zarówno na żądanie doradcy, jak i masowo po dacie zmian. Więcej o tym, jak budujemy takie połączenia, na stronie integracji API dla firm.

Podsumowanie

  • BIR (REGON): SOAP 1.2 z WS-Addressing, klucz od GUS, sesja w nagłówku sid, raporty zależne od typu podmiotu; wersje 1.1 i 1.2.
  • gusapi/gusapi oszczędza pracy z SOAP, ale obsługuje BIR 1.1.
  • Biała lista VAT: REST bez klucza, niskie limity dzienne, requestId jako potwierdzenie sprawdzenia.
  • W Laravelu: jeden serwis, cache, kolejki dla operacji masowych, logowanie i atrapy w testach.

Chcesz, żeby Twój system sam uzupełniał dane kontrahentów? Napisz do nas — zbudujemy integrację z GUS, białą listą i innymi rejestrami, których potrzebujesz.

← Wszystkie artykuły