---
title: "USt-IdNr. validieren"
description: "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)

```bash
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](/de/api/organization/update-organization), 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](/de/api/organization/update-organization). Ein kundengescoptes API-Token kann diesen Endpoint nicht aufrufen, selbst mit Admin-Rolle.

## Antwort (Response)

```json
{
  "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](/de/api/organization/update-organization)
- `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](/de/api/error-codes-and-known-pitfalls) für die vollständige Übersicht.