★ Offizielles EU-VIES-System

VatScan API

EU-USt-IdNr.-Validierung über das offizielle VIES-System. Authentifizierung per X-API-Key. Einen Key erhältst du im Portal.

GET/v1/check/{vat}

Validiert eine USt-IdNr. (z.B. ATU13585627) über das EU-VIES-System. Alternativ als Query-Form: /v1/check?vat=ATU13585627. Liefert immer die Gültigkeit; Firmenname und Adresse — wo der Mitgliedstaat sie bereitstellt — in den Bezahltarifen. Free-Keys erhalten nur Gültigkeit + UID.

user@vatscan:~$cat example.sh

curl -H "X-API-Key: $KEY" https://api.vatscan.eu/v1/check/ATU13585627

Antwort

user@vatscan:~$cat response.json

{
  "country_code": "AT",
  "vat_number": "U13585627",
  "valid": true,
  "name": "Beispiel GmbH",
  "address": "Musterstraße 1, 1010 Wien",
  "checked_at": "2026-06-12T14:07:03Z"
}

GET/v1/limits

Liefert die für deinen Key geltenden effektiven Tariflimits (nach Auflösung User-Override → Tarif → Default) plus den aktuellen Verbrauch —ideal fürs Auslastungs-Monitoring. 0 bedeutet unbegrenzt; *_remaining ist dann null. Das Tageskontingent zählt geprüfte UID-Abfragen und wird zur reset_hour_utc (UTC) zurückgesetzt.

user@vatscan:~$cat example.sh

curl -H "X-API-Key: $KEY" https://api.vatscan.eu/v1/limits

Antwort

user@vatscan:~$cat response.json

{
  "effective": {
    "rate_limit_per_min": 600,
    "rate_limit_per_day": 5000000,
    "max_ips_per_batch": 100
  },
  "unlimited": { "per_min": false, "per_day": false },
  "reset_hour_utc": 0,
  "usage": {
    "minute_used": 2,
    "minute_remaining": 598,
    "day_used": 1234,
    "day_remaining": 4998766,
    "next_day_reset_utc": "2026-06-16T00:00:00Z",
    "seconds_until_day_reset": 50000
  },
  "plan": {
    "name": "Pro",
    "rate_limit_per_min": 600,
    "rate_limit_per_day": 5000000,
    "fair_use_per_day": null,
    "max_ips_per_batch": 100,
    "price_on_request": false,
    "monthly_price_cents": 7900,
    "currency": "EUR"
  }
}

GET/v1/public/check?vat=…

Schlüsselfreie Demo (pro IP gedrosselt) — liefert nur Gültigkeit + UID, ohne Firmendaten. Für produktive Nutzung den authentifizierten Endpoint mit API-Key verwenden.

GET/v1/health

Liveness-Check, keine Authentifizierung nötig.

user@vatscan:~$cat example.sh

curl https://api.vatscan.eu/v1/health

Antwortfelder

Feld	Bedeutung
`country_code`	ISO-Ländercode (z.B. AT). Sonderfälle: Griechenland = EL, Nordirland = XI.
`vat_number`	Nationaler Teil der UID in VIES-Schreibweise (z.B. U13585627).
`valid`	true / false laut VIES. null = derzeit nicht ermittelbar.
`name`	Eingetragener Firmenname, sofern der Mitgliedstaat ihn herausgibt. Nur Bezahltarif.
`address`	Eingetragene Anschrift, sofern verfügbar. Nur Bezahltarif.
`checked_at`	Zeitpunkt der zugrunde liegenden Prüfung (ISO 8601, UTC). Nur Bezahltarif.

Rate-Limits

Limits gelten pro Nutzer (alle Keys teilen sich ein Kontingent), pro Minute und pro Tag — abhängig vom Tarif. Jede Antwort enthält die aktuellen Header:

Header	Bedeutung
`X-RateLimit-Limit`	Erlaubte Abfragen pro Minute (oder „unlimited“).
`X-RateLimit-Remaining`	Im laufenden Minutenfenster noch verfügbar.
`Retry-After`	Sekunden bis zum nächsten erlaubten Versuch (bei HTTP 429).

Fehlercodes

Fehler kommen als JSON mit einem Code (Feld error, bei Auth/Rate-Limit error_code).

HTTP	Code	Bedeutung
`400`	`invalid_vat`	UID-Format oder Prüfziffer ungültig.
`401`	`missing_api_key`	Kein X-API-Key-Header gesendet.
`401`	`invalid_api_key`	API-Key ungültig oder widerrufen.
`429`	`rate_limit_per_minute`	Minuten-Limit erreicht.
`429`	`rate_limit_per_day`	Tages-Kontingent erreicht.
`429`	`rate_limited`	Demo-Limit des schlüsselfreien /v1/public/check erreicht.
`503`	`vies_unavailable`	Das EU-VIES-System ist aktuell nicht erreichbar.