API VIES (unijny VAT)
walidacja VAT-UE bez klucza

Jeden GET, jeden JSON

Endpoint jest publiczny, metoda GET, a parametr ?format=json zwraca dane maszynowo (bez niego dostajesz stronę HTML dla człowieka). Ścieżka to /vies/{kraj}/{numer} — kraj to dwuliterowy kod państwa UE (np. PL, DE), numer to numer VAT bez prefiksu kraju:

curl "https://skanfirmy.pl/vies/PL/5260250995?format=json"

W odpowiedzi dostajesz status ważności numeru, nazwę i adres podatnika w formie zwracanej przez VIES — dla polskich numerów od 26.09.2026 zamiast adresu tylko miejscowość (szczegóły niżej) — oraz znacznik czasu zapytania (dowód sprawdzenia):

{
  "countryCode": "PL",
  "vatNumber": "5260250995",
  "valid": true,
  "result": "valid",
  "name": "ORANGE POLSKA SPÓŁKA AKCYJNA",
  "address": null,
  "city": "WARSZAWA",
  "requestDate": "2026-09-26T08:15:02.000Z",
  "privacy": {
    "naturalPerson": null,
    "hidden": ["address"],
    "reason": "Dane osoby fizycznej prowadzącej działalność ograniczone do niezbędnych do weryfikacji kontrahenta (RODO). Pełny wpis publikuje rejestr źródłowy (officialSource).",
    "officialSource": "https://www.gov.pl/web/kas/wykaz-podatnikow-vat"
  },
  "checkedAt": "2026-09-26"
}

Pole valid to jedyna miarodajna odpowiedź na pytanie „czy ten unijny numer VAT jest ważny”. Pola name i address VIES zwraca tylko wtedy, gdy dane państwo członkowskie je ujawnia — część krajów ich nie udostępnia i wówczas potrafią być puste.

Bez klucza API, bez rejestracji, bez limitu dziennego

Endpoint działa od razu — nie musisz zakładać konta, generować klucza API ani pilnować dziennego limitu zapytań. Jedyne ograniczenie chroni serwis przed nadużyciami: najwyżej 20 zapytań na 10 sekund z jednego adresu IP (po przekroczeniu kod 429 przez 10 sekund; od 25.09.2026). To celowa różnica względem komercyjnych nakładek na VIES: chcemy, żeby walidację VAT-UE dało się wpiąć w minutę, także z poziomu agenta AI. Serwis jest bezpłatny i służy do pojedynczych zapytań inicjowanych przez użytkowników lub ich agentów, nie do masowego pobierania danych.

Zamiast VIES SOAP

Oficjalna usługa to VIES Komisji Europejskiej — SOAP z operacją checkVat, kopertami XML i odpowiedzią, którą trzeba samodzielnie sparsować. Działa, ale integracja potrafi zająć popołudnie. Nasz endpoint robi to wszystko po stronie serwera i zwraca gotowy JSON — Ty wysyłasz jeden GET.

Co zwraca /vies/{kraj}/{numer}:

Dla numeru z innego państwa działa tak samo — np. niemiecki numer sprawdzisz przez GET /vies/DE/811128135?format=json. Prefiks kraju (DE, PL) idzie w ścieżce jako {kraj}, a sam numer bez prefiksu jako {numer}.

Polskie numery VAT — zmiana od 26.09.2026

VIES nie mówi, czy polski numer VAT należy do spółki, czy do osoby fizycznej prowadzącej działalność — a adres osoby fizycznej jest daną osobową i bywa jej adresem zamieszkania. Dlatego od 26.09.2026 dla każdego numeru PL zamiast adresu zwracamy tylko miejscowość: pole address ma wartość null, miejscowość jest w polu city, a pole privacy mówi, co pominęliśmy i gdzie jest pełny wpis (Wykaz podatników VAT na gov.pl; naturalPerson ma wartość null, bo VIES tego nie rozstrzyga). Takie odpowiedzi mają nagłówki X-Robots-Tag: noindex i Cache-Control: private, max-age=3600, a strona HTML nie ma nazwy w tytule ani w danych strukturalnych. Numery z pozostałych państw zwracamy bez zmian. Pełne dane polskiej spółki, z adresem siedziby, daje /nip/{nip}.

W Pythonie

Z biblioteką requests całość to kilka linii — warto od razu sprawdzić valid:

import requests

def waliduj_vat_ue(kraj: str, numer: str) -> dict:
    r = requests.get(f"https://skanfirmy.pl/vies/{kraj}/{numer}?format=json", timeout=10)
    r.raise_for_status()
    data = r.json()
    if not data["valid"]:
        raise ValueError(f"Numer VAT-UE {kraj}{numer} jest nieaktywny w VIES")
    return data

d = waliduj_vat_ue("PL", "5260250995")
print(d["name"])
# ORANGE POLSKA SPÓŁKA AKCYJNA

Każda odpowiedź (także błędna) niesie pole result, więc rozgałęzienie możesz oprzeć na jednej wartości zamiast na samym kodzie HTTP. Kluczowe: literówka a numer niezarejestrowany to dwa różne stany — błędny format to result: "invalid_format" (HTTP 400), a poprawny, lecz niezarejestrowany numer to valid: false z result: "not_registered" (HTTP 200). Dzięki temu nie mylisz pomyłki w numerze z realnym brakiem rejestracji.

W JavaScripcie

const r = await fetch("https://skanfirmy.pl/vies/PL/5260250995?format=json");
if (r.ok) {
  const d = await r.json();
  console.log(d.valid, d.name);
}

W PHP

$ch = curl_init("https://skanfirmy.pl/vies/PL/5260250995?format=json");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$d = json_decode(curl_exec($ch), true);
echo $d["valid"] ? $d["name"] : "numer nieaktywny";

Krajowy VAT i dane rejestrowe — jednym NIP-em

VIES odpowiada na pytanie o unijny numer VAT. Jeśli sprawdzasz polską firmę i potrzebujesz krajowego statusu VAT (Wykaz VAT / Biała Lista), wpisu w KRS i numeru REGON (poza osobami fizycznymi), użyj /nip/{nip}?format=json — łączy te źródła w jednej odpowiedzi. Pozostałe endpointy (wszystkie GET → JSON, bez klucza):

• /vies/{kraj}/{numer} — walidacja unijnego numeru VAT (VIES, Komisja Europejska)
• /nip/{nip} — status VAT + Biała Lista + KRS + REGON (poza osobami fizycznymi)
• /nips/{lista} — wiele NIP-ów naraz (rozdzielonych przecinkami)
• /regon/{nip} — dane z rejestru REGON (GUS)

Dla agentów AI pod adresem https://skanfirmy.pl/mcp stoi serwer Model Context Protocol (MCP) z narzędziem do walidacji unijnego VAT (i kilkoma innymi do NIP, KRS i REGON) — również bez klucza. Mapa endpointów dla modeli jest w llms.txt, a pełna specyfikacja maszynowa w OpenAPI 3.1. Walidację numeru VAT-UE w interfejsie zrobisz w narzędziu VIES (unijny VAT).

Publiczny endpoint a typowe płatne API VIES

Większość komercyjnych nakładek REST na VIES działa w modelu freemium — konto, klucz API i dzienny limit zapytań w bezpłatnym progu. Ten endpoint jest publiczny i bezpłatny, a poza samym valid zwraca też nazwę, adres i datę sprawdzenia. Różnice w skrócie:

To nie jest oficjalne API VIES — dane pochodzą z tego samego źródła (system VIES Komisji Europejskiej), tylko udostępnione jednym zapytaniem GET.

Skąd pochodzą dane i czym to nie jest

Dane pochodzą wprost z systemu VIES prowadzonego przez Komisję Europejską. To niezależne narzędzie — nie jest oficjalnym API VIES ani z nim powiązane; jedynie udostępnia jego dane w wygodniejszej formie. Nazwę i adres VIES zwraca tylko wtedy, gdy dane państwo członkowskie je ujawnia, a wartość valid odzwierciedla stan w chwili z pola requestDate — status może się później zmienić.

Najczęstsze pytania