🇬🇧 API Documentation: White List VAT Verifier

Overview

The White List VAT API is a high-performance .NET service designed to verify if a specific bank account (NRB) is associated with a VAT taxpayer’s identification number (NIP) in the Polish Ministry of Finance’s “White List” registry.

Unlike standard API gateways that query government servers in real-time, this API operates on a local, daily updated offline database containing hashed records. This ensures high throughput, low latency, and privacy (no external calls per request).

PL Jeśli jesteś zainteresowany(a) użyciem API, skontaktuj się proszę przez formularz kontaktowy: https://wroclawprogramowanie/contact-form/

EN If you’re interested in using the API, please contact us via the contact form: https://wroclawprogramowanie/contact-form/

Core Features

• Offline Verification: Uses SHA-512 hashing to verify pairs locally without calling external services.
• Virtual Accounts Support: Implements a masking mechanism to verify virtual bank accounts used by mass payment collectors.
• Batch Processing: Supports bulk verification of up to 10 pairs in a single request.

Internal Logic & Security

The verification process relies on cryptographic hashing rather than storing raw plain-text data.

Hashing Algorithm

1. Input Construction: DataDate + NIP + NRB (concatenated string).
2. Hashing: SHA-512 with multiple iterations (default 5000, configurable via DB).
3. Comparison: The resulting hash is compared against the hashes table.

Virtual Accounts (Masking)

If a standard check fails, the verifier checks for “Virtual Accounts”:

1. Extracts the Bank Branch ID (digits 3-10 of NRB).
2. Retrieves associated Masks from the database.
3. Applies the mask (e.g., replacing specific digits with ‘Y’ or fixed values) to the NRB.
4. Re-hashes and checks the database again.

API Endpoints

1. Single Verification (GET)

Performs a check using query parameters.

Endpoint: GET /check

Parameters:

• nip (string, required): 10-digit Tax Identification Number.
• nrb (string, required): 26-digit Bank Account Number.

Response (200 OK):

json{
  "found": true,
  "status": "Valid",
  "searchTimeMs": 1.25,
  "iterations": 1,
  "method": "Standard",
  "dataDate": "20250101"
}

2. Single Verification (POST)

Performs a check using a JSON body.

Endpoint: POST /check

Request Body:

json{
  "nip": "9810000054",
  "nrb": "70102035709724546729803218"
}

3. Batch Verification (POST)

Verifies multiple pairs in one request. Ideal for bulk processing.

Endpoint: POST /check/batch

Constraints:

• Max batch size: 10 items (configurable via WhiteListApi:BatchLimit).

Request Body:

json[
  {
    "nip": "7360005919",
    "nrb": "55160014620008864235770040"
  },
  {
    "nip": "1132480641",
    "nrb": "40105010251000002280149754"
  }
]

Response (200 OK): Returns an array of result objects corresponding to the input order.

Data Models

CheckResponse Object

🇵🇱 Dokumentacja API: Weryfikator Białej Listy VAT

Przegląd

White List VAT API to wydajna usługa służąca do weryfikacji, czy dany numer rachunku bankowego (NRB) jest przypisany do numeru NIP podatnika w oficjalnym wykazie “Biała Lista” Ministerstwa Finansów.

W przeciwieństwie do standardowych bramek API, które odpytują serwery rządowe w czasie rzeczywistym, to API działa na lokalnej aktualizowanej codziennie bazie zawierającej skróty (hashe) danych. Zapewnia to ogromną wydajność, brak limitów zapytań API MF oraz bezpieczeństwo danych.

Baza usługi jest aktualizowana codziennie oficjalną świerzą kopią Białej Listy udostępnianą przez Ministerstwo Finansów.

Faktury „scamowe” w KSeF to fałszywe dokumenty wystawione na NIP firmy bez rzeczywistej transakcji, mające na celu oszustwa VAT lub wyłudzenia. W ramach KSeF 2.0 (od 1.02.2026 r.) przedsiębiorcy mogą zgłaszać takie dokumenty do MF i ukrywać je w systemie, co chroni przed niezasadnym podatkiem VAT.

Podatnicy powinni monitorować KSeF, aby szybko wykrywać i zgłaszać podejrzane faktury, ograniczając ryzyko prawne i finansowe.

Nie płać: Absolutnie nie należy opłacać podejrzanej faktury do czasu dokładnej weryfikacji i wyjaśnienia sprawy.

Poprawność rachunku bankowego do zapłaty:

Oszuści często podają na fakturach (nawet tych fałszywych, poza KSeF) zmieniony numer konta. Zawsze weryfikuj numer konta w Białej Liście VAT przed dokonaniem płatności.

Za pomocą tej usługi możesz zweryfikować NIP, Numer Rachunku Bankowego według oficjalnej “Białej Listy VAT” Ministerstwa Finansów, upewniając się że przelewasz pieniądze na właściwy rachunek.

Kluczowe funkcje

• Weryfikacja Offline: Używa haszowania SHA-512 do sprawdzania par NIP+NRB lokalnie.
• Obsługa Rachunków Wirtualnych: Implementuje mechanizm masek, umożliwiając weryfikację rachunków masowych (używanych np. przez dostawców mediów).
• Przetwarzanie Wsadowe (Batch): Obsługa do 10 zapytań w jednym żądaniu HTTP.

Logika Wewnętrzna i Bezpieczeństwo

Algorytm Haszowania

API nie przechowuje jawnych numerów kont. Weryfikacja polega na odtworzeniu skrótu kryptograficznego:

1. Budowa wejścia: DataDanych + NIP + NRB (ciąg znaków).
2. Haszowanie: SHA-512 z wielokrotną iteracją (domyślnie 5000, konfigurowalne w bazie).
3. Porównanie: Wynikowy skrót jest szukany w tabeli hashes.

Rachunki Wirtualne (Maski)

Jeśli standardowe sprawdzenie nie zwróci wyniku, weryfikator sprawdza tzw. maski bankowe:

1. Wyciąga Identyfikator Oddziału Banku (cyfry 3-10 z NRB).
2. Pobiera przypisane Maski z bazy danych.
3. Aplikuje maskę do badanego NRB (np. podmieniając cyfry na znaki formatowania).
4. Ponownie haszuje i sprawdza w bazie.

Endpointy API

1. Pojedyncza Weryfikacja (GET)

Szybkie sprawdzenie przez pasek adresu / parametry URL.

Adres: GET /check

Parametry:

• nip (string): 10-cyfrowy NIP.
• nrb (string): 26-cyfrowy numer konta.

Przykład Użycia:

bash
curl -X GET "http://localhost:5000/check?nip=9810000054&nrb=70102035709724546729803218"

2. Pojedyncza Weryfikacja (POST)

Sprawdzenie z użyciem ciała żądania JSON.

Adres: POST /check

Przykład Body:

json{
  "nip": "1120000322",
  "nrb": "83249000054243980827278527"
}

3. Weryfikacja Zbiorcza (POST Batch)

Sprawdza listę par NIP-NRB.

Adres: POST /check/batch Limity: Domyślnie max 10 elementów.​

Przykład Body:

json[
  { "nip": "1810004094", "nrb": "39102055610000370202959088" },
  { "nip": "1130013160", "nrb": "57102010550000910200159426" }
]

Model Danych (CheckResponse)

Obiekt zwracany przez API zawiera szczegóły weryfikacji: