USt-IdNr. validieren

Validiert die für die Organisation gespeicherte Umsatzsteuer-Identifikationsnummer gegen das EU-Register VIES und speichert das Ergebnis. Nur eine gültige USt-IdNr. aus einem anderen EU-Mitgliedsstaat qualifiziert die Organisation für die Reverse-Charge-Abrechnung nach AGB § 10.2.

POST /api/organizations/:organizationPublicId/vat-id/validate

Beispiel (cURL)

BASE_URL="https://uptimeify.io"
TOKEN="<dein-api-token>"
ORG_ID="<organization-public-id>"

curl -X POST "$BASE_URL/api/organizations/$ORG_ID/vat-id/validate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Hinweise:

Dieser Endpoint erwartet keinen Request Body. Er validiert genau das, was aktuell als vatId und countryCode an der Organisation gespeichert ist — setze beides vorher mit Organisation aktualisieren, falls nötig.
Die Validierung ist eine bewusste, eigenständige Aktion und kein Nebeneffekt beim Speichern der Organisation. Der EU-Dienst VIES ist langsam und pro Mitgliedsstaat gelegentlich nicht erreichbar — ein PATCH auf die Organisation darf daran nicht scheitern oder hängen bleiben. Das Speichern einer neuen vatId oder eines neuen countryCode setzt vatIdStatus auf unverified zurück; erst dieser Endpoint macht daraus wieder ein Ergebnis.
Reverse Charge nach AGB § 10.2 greift nur, wenn das Land der Organisation ein EU-Mitgliedsstaat außer Deutschland ist, eine USt-IdNr. gespeichert ist und vatIdStatus exakt valid lautet. Jede andere Kombination wird zum Standard-Steuersatz abgerechnet.
Erfordert Schreibzugriff auf die Organisation (Org-Admin oder Global-Admin) aus einer uneingeschränkten Session oder einem uneingeschränkten Token — dieselbe Berechtigung wie bei Organisation aktualisieren. Ein kundengescoptes API-Token kann diesen Endpoint nicht aufrufen, selbst mit Admin-Rolle.

Antwort (Response)

{
  "vatIdStatus": "valid",
  "vatIdValidatedAt": "2026-07-30T09:15:00.000Z",
  "vatIdValidationNote": null,
  "taxTreatment": "reverse_charge"
}

vatIdStatus ist einer von:

Wert	Bedeutung
`unverified`	Noch nicht validiert, oder die gespeicherte `vatId`/`countryCode` hat sich seit der letzten Validierung geändert (siehe oben). Dieser Endpoint liefert diesen Wert nie zurück — er ist der Default vor jeder Validierung.
`valid`	VIES hat die USt-IdNr. bestätigt. Nur dieser Status gewährt Reverse Charge.
`invalid`	VIES hat die USt-IdNr. abgelehnt, ihr Länderpräfix gehört keinem EU-Umsatzsteuerland an, oder er stimmt nicht mit dem gespeicherten `countryCode` der Organisation überein.
`unavailable`	VIES konnte kein Ergebnis liefern — Timeout, HTTP-Fehler, oder ein Mitgliedsstaat, dessen Register sich selbst als nicht erreichbar meldet (`MS_UNAVAILABLE`). Bewusst getrennt von `invalid`: Ein Ausfall darf niemals als „die USt-IdNr. ist falsch“ gelesen werden, da das einem berechtigten Kunden zu Unrecht den Reverse Charge entziehen würde. Später erneut versuchen.

taxTreatment gibt die daraus resultierende Abrechnungsart an und ist entweder standard oder reverse_charge.

vatIdValidationNote ist eine kurze, lesbare Begründung (z. B. warum eine Prüfung invalid oder unavailable ergeben hat); bei einem valid-Ergebnis null.

Häufige Fehler

401 Unauthorized (data.code: unauthorized) wenn du nicht angemeldet bist
400 Invalid Organization identifier wenn :organizationPublicId weder eine Legacy-Integer-ID noch eine gültige UUID-Public-ID ist
403 Forbidden (data.code: forbidden) wenn du keinen Schreibzugriff auf die Organisation hast
403 Forbidden (data.code: customerScopedTokenForbidden) wenn mit einem kundengescopten API-Token aufgerufen wird; dies ist eine organisationsweite Aktion und erfordert ein organisationsgescoptes Token oder eine Session
404 Organization not found (kein data.code) wenn :organizationPublicId zu keiner bestehenden Organisation aufgelöst werden kann
404 Organization not found (data.code: organizationNotFound) wenn die Organisation in dem kurzen Zeitfenster zwischen der Auflösung von :organizationPublicId und der eigenen Prüfung des Endpoints gelöscht wird — ein Sonderfall, nicht die übliche Not-Found-Antwort
422 No VAT ID stored for this organization (data.code: vatIdMissing) wenn für die Organisation keine vatId gespeichert ist — speichere zuerst eine mit Organisation aktualisieren
409 The VAT ID or country changed while validation was in flight (data.code: vatIdChangedDuringValidation) wenn vatId oder countryCode während der laufenden VIES-Abfrage gleichzeitig geändert wurde — das noch laufende Ergebnis wird verworfen, statt auf veraltete Daten geschrieben zu werden. Gefahrlos wiederholbar.

Siehe Fehlerliste für die vollständige Übersicht.

USt-IdNr. validieren

Beispiel (cURL)

Antwort (Response)

Häufige Fehler

Auf dieser Seite