GET /vies/{country}/{vat}

GET /vies/{country}/{vat}

Waliduje numer VAT w usłudze VIES Komisji Europejskiej. Zwraca informację, czy numer jest obecnie zarejestrowany, oraz nazwę i adres podatnika, jakie VIES ma w bazie (o ile pozwala na to polityka udostępniania danego Państwa Członkowskiego).

Parametry

Nazwa	Gdzie	Przykład	Uwagi
`country`	ścieżka	`DE`, `FR`, `EL`	ISO 3166-1 alpha-2. Grecja jest akceptowana jako `GR` (ISO) lub `EL` (natywna forma VIES); odpowiedź zwraca ten sam zapis, który przesłałeś.
`vat`	ścieżka	`123456789`	Numer VAT bez prefiksu kraju. Długość zależy od kraju (od 4 do 12 cyfr).

Odpowiedź

{
  "countryCode": "DE",
  "vatNumber": "123456789",
  "requestDate": "2026-05-27+02:00",
  "valid": true,
  "name": "Acme GmbH",
  "address": "Hauptstraße 1"
}

Znaczenie pól

countryCode — zwrócony w tej samej formie, w jakiej go przesłałeś. Wyślij GR, dostaniesz GR; wyślij EL, dostaniesz EL. Wewnętrznie Stawka normalizuje obie wartości do EL (forma używana w VIES) na potrzeby wywołania nadrzędnego.
vatNumber — zwrócony bez zmian z parametru ścieżki. Bez reformatowania.
requestDate — własny znacznik czasu VIES dla tej walidacji, zawierający offset strefy czasowej.
valid — true lub false. Tylko true oznacza, że numer jest zarejestrowany właśnie teraz. false oznacza, że VIES sprawdził go i numeru nie ma w bazie.
name — nazwa podatnika. null, jeśli VIES jej nie podał (część Państw Członkowskich nie udostępnia tych danych) lub jeśli zwrócił literalnie ---.
address — ta sama semantyka co name.

Ważność jest point-in-time

VIES zwraca migawkę tego, co rejestr Państwa Członkowskiego pokazuje w momencie, gdy zapytanie do niego trafia. Numer ważny dziś może być nieważny jutro i odwrotnie. Zapisuj requestDate, jeśli potrzebujesz ścieżki audytu z możliwością obrony tego, co i kiedy sprawdziłeś.

Zachowanie cache’u

Cache-Control: private, max-age=300–3600. Dokładna wartość zależy od sygnałów w odpowiedzi usługi nadrzędnej. Powtarzane wywołania dla tej samej pary (country, vat) trafiają do naszego cache’u i nie zużywają Twojego limitu zapytań ani kwoty.

Błędy

Status	Body	Przyczyna
422	`{"error": "INVALID_INPUT"}`	VIES odrzucił format kraju lub numeru VAT. Popraw dane wejściowe.
503	`{"error": "MS_UNAVAILABLE"}`	Rejestr konkretnego Państwa Członkowskiego jest niedostępny. Spróbuj później; to przerywany problem po stronie VIES.
503	`{"error": "SERVICE_UNAVAILABLE"}`	Sam VIES działa z degradacją.
503	`{"error": "TIMEOUT"}`	VIES przekroczył nasz twardy timeout.
502	`{"error": "..."}`	Cokolwiek innego (błąd parsowania, awaria sieci, nieznany kod nadrzędny). Prosimy o otwarcie issue.
401	`{"error": "INVALID_KEY"}`	Brakujący lub nieprawidłowy token bearer.
429	`{"error": "RATE_LIMITED"}` lub `{"error": "QUOTA_EXCEEDED"}`	Zobacz limity i kwoty.

Greckie kody kraju (GR vs EL)

VIES używa EL (kod ISO 639 języka greckiego, a nie kod ISO 3166 Grecji) dla greckich numerów VAT. ISO 3166 mówi, że Grecja to GR. Stawka akceptuje oba zapisy:

curl https://api.stawka.eu/vies/GR/123456789  -H "Authorization: Bearer ..."
curl https://api.stawka.eu/vies/EL/123456789  -H "Authorization: Bearer ..."

Oba walidują ten sam numer w usłudze nadrzędnej; pole countryCode w odpowiedzi zwraca ten zapis, który przesłałeś. Wybierz to, czego oczekują Twoje systemy downstream — nie ma „właściwego” wyboru między ISO 3166 a natywną formą VIES.