Skip to content

Kontakte: USt-IdNr. beim BZSt bestätigen (#1385) - #1435

Merged
firsttris merged 10 commits into
mainfrom
ustid-bestaetigung
Nov 18, 2026
Merged

firsttris merged 10 commits into
mainfrom
ustid-bestaetigung

Conversation

@thomas-baumeister

@thomas-baumeister thomas-baumeister commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Erster Teil von #1385 nach dem Plan im Issue und der Antwort des Maintainers: Die USt-IdNr. eines Kontakts aus einem anderen EU-Mitgliedstaat bestätigt das BZSt über die eVatR-REST-API, und jede Antwort zur Nummer bleibt als Nachweis gespeichert. Die Prüfung vor dem Festschreiben und die ZM-Vorprüfung folgen im zweiten Pull Request.

Refs #1385

Was sich ändert

  • Kontaktseite: Karte „Bestätigung beim BZSt“ mit der letzten Antwort zur aktuellen Nummer (Status und Zeitpunkt, bei qualifizierter Abfrage der Vergleich von Name, Straße, PLZ und Ort), Knopf „Beim BZSt bestätigen“ und allen Abfragen, auch zu früheren Nummern. Nach dem Anlegen und nach dem Speichern unter Kontakte fragt die Seite einmal, wenn die Nummer noch nie angefragt wurde oder Name oder Anschrift von der letzten qualifizierten Bestätigung abweichen; eine zuletzt ungültige Nummer nur auf Knopfdruck. Kontakte, die anderswo angelegt oder geändert werden (Dialog in Rechnung, Beleg und Vorlagen, Import, REST-API), bestätigt Haben nicht von selbst; das Merkzeichen „nach dem Speichern fragen“ gilt nur für den gespeicherten Kontakt, und den Suchparameter nach dem Anlegen nimmt die Seite gleich beim Laden weg. Das Speichern wartet nicht auf das BZSt. Ohne eigene USt-IdNr. nennt die Karte das mit Link auf die Firmendaten.
  • Abfrage (packages/core/src/evatr.ts, stammdaten/ustid-bestaetigung.ts): erst einfach, bei gültiger Nummer qualifiziert mit Name und Anschrift des Kontakts (ohne Ort nur einfach). Abgefragt werden nur Nummern, die die Formprüfung aus USt-IdNr. des Lieferanten: Format je Mitgliedstaat prüfen (ATU1234 lässt sich als § 1a buchen) #1413 bestehen (ustIdProblem und ustIdAufbauProblem), deutsche nie; anfragend ist die eigene USt-IdNr. aus den Firmendaten mit gültiger Prüfziffer. Ausgewertet wird status, nicht der HTTP-Code: evatr-0008 steht in der OpenAPI unter 400, in den Statusmeldungen mit 403. Fehler des Dienstes, Zeitüberschreitung (20 s je Anfrage) und Antworten, die sich nicht lesen lassen (auch ohne lesbaren anfrageZeitpunkt), ergeben einen Hinweis, speichern nichts und werden nicht wiederholt; bei evatr-0008 bleibt es bei der einfachen Antwort.
  • Tabelle ustid_bestaetigungen (Migrationen 0289 und 0290, erzeugt auf 596e23ba): je Antwort zur Nummer (evatr-0000, -2001, -2002, -2006, -2008) die gesendeten Angaben, Status, Zeitpunkt beim BZSt, Gültigkeit, Vergleich A bis D, technische ID und der empfangene Datensatz unverändert. Nur anhängbar (haben_append_only), Audit, gegen TRUNCATE gesperrt; Sollbestand der Trigger neu erzeugt.
  • Jahresarchiv: stammdaten/ustid-bestaetigungen.csv mit den Antworten des Jahres nach dem Zeitpunkt der Anfrage in deutscher Zeit, beschrieben in index.xml. kontakt-versionen.csv und die neue Datei kommen aus archiv/export-kontakte.ts, damit yearFiles nicht weiter wächst; das Archiv bleibt sonst gleich.
  • Verbindung nach außen zu api.evatr.vies.bzst.de, nur vom Server. HABEN_EVATR=off schaltet sie ab; die Karte fehlt dann, außer es gibt schon Antworten. EVATR_API_URL nur zum Testen. In der E2E zeigen alle Server auf einen nachgebauten Dienst, eingeschaltet ist die Abfrage nur im Durchlauf belege-steuern; die SSO-Tests schalten sie ab.
  • Doku: neuer Abschnitt in kontakte.md (Pflicht nach § 6a Abs. 1 Satz 1 Nr. 4 UStG und UStAE 3a.2 Abs. 9 Sätze 4 und 5), Verbindungen nach außen und Module in architektur.md, Tabelle in architektur-datenmodell.md, beide Variablen in installation-konfiguration.md, Jahresarchiv in auswertungen.md, die Sätze zur Bestätigungsabfrage in umsatzsteuer.md, rechnungen.md und csv-import.md, ueberblick.md.

Keine Buchung, kein Kontenrahmen und keine Versteuerungsart betroffen; SKR03/SKR04 und Ist/Soll spielen hier keine Rolle.

Quellen

  • OpenAPI-Beschreibung der eVatR-API v1.2.3 und GET /app/v1/info/statusmeldungen, gelesen am 2026-11-18. Eine Testabfrage mit den dort genannten Beispielwerten (DE123456789, ATU12345678) zeigte das Format der Antwort, etwa anfrageZeitpunkt mit Nanosekunden; Fehler kommen in derselben Form.
  • UStAE 18e.1 Abs. 2, Stand 19.10.2026 (BMF): Nachweis der qualifizierten Abfrage bei einzelnen Nummern durch Übernahme des übermittelten Ergebnisses in das System des Unternehmens (Satz 3), bei gleichzeitigen Anfragen über die Schnittstelle über den empfangenen Datensatz (Sätze 4 und 5); die FAQ des BZSt nennen den Datensatz für jede Abfrage über die Schnittstelle.
  • FAQ des BZSt zur USt-IdNr.: einfache vor qualifizierter Bestätigung, keine schriftliche Bestätigungsmitteilung, keine Bestätigung für zurückliegende Zeitpunkte. Seite „Bestätigung ausländischer USt-IdNrn“: bei Zeitüberschreitung später erneut fragen, nicht sofort.

Geprüft

  • Vitest im Dev-Container mit PostgreSQL 18: 12.076 bestanden, 217 übersprungen (8 Dateien; im Container fehlen helm, cc, ERiC, Authelia, die ERiC-Doku und die Beispiele aus erica). 29 Tests in 5 Dateien schlagen fehl, die im Container ohne das Werkzeug nicht laufen: scripts/ci/doku-filter.test.ts und scripts/pr-regeln/pruefen.test.ts (kein git), deploy/backup/backup-status.test.ts (kein psql) und die Zeitlimit-Tests in packages/einvoice/src/render-client.test.ts und stammdaten/layouts.test.ts; die CI führt sie aus. Nach dem Rebase auf 596e23ba die betroffenen Dateien noch einmal: 65 von 65; nach den Nachbesserungen aus der Selbstprüfung die drei neuen Testdateien: 28 von 28.
  • Neue Tests: packages/core/src/evatr.test.ts (Anfrage, Antwort aus der Testabfrage, Zeitpunkt, Status, wann neu gefragt wird, auch zurück auf einen früheren Namen), stammdaten/ustid-bestaetigung.test.ts mit nachgebautem Dienst (einfach und qualifiziert gespeichert, nach dem Speichern nur bei Änderung, nicht vergebene Nummer, 503, kein Netz, unlesbare Antwort und unlesbarer Zeitpunkt ohne Speichern, evatr-0008, ohne Ort, abgeschaltet, ohne eigene USt-IdNr., deutsche Nummer, unbekannter Kontakt, nur anhängbar und im Änderungsprotokoll), archiv/export-ustid-bestaetigungen.test.ts (Jahresgrenze in deutscher Zeit, Antwort unverändert, index.xml).
  • Playwright: zwei neue Tests im Durchlauf belege-steuern (e2e/ustid-bestaetigung.ts): (1) Anlegen fragt einfach und qualifiziert, Knopf bei Ausfall mit Hinweis ohne Speichern, Speichern mit neuer Anschrift fragt neu, ohne Änderung nicht, axe am Desktop, am Handy und in allen Themes; (2) nach dem Speichern eines Kontakts ohne USt-IdNr. fragt der Wechsel über die Schnellsuche zu einem nie bestätigten EU-Kontakt nichts an, und wer nach dem Anlegen gleich auf „Rechnung schreiben“ geht, bleibt dort, auch wenn das BZSt langsam antwortet. Lokal nicht mit dem Test-Runner gelaufen (keine Browser im Container), nur in der CI. Dieselben Abläufe habe ich mit playwright-core gegen die Dev-Instanz und einen verzögernden nachgebauten Dienst durchgespielt: vor dem Fix 2 Abfragen beim Wechsel und /kontakte/undefined statt /rechnungen/neu, danach 0 Abfragen und /rechnungen/neu; Anlegen und Speichern mit neuer Straße fragen weiter je zweimal.
  • Von Hand im Dev-Container gegen einen nachgebauten Dienst: Anlegen mit französischer Nummer fragt gleich, Knopf, Speichern mit neuer Straße fragt neu, Speichern ohne Änderung nicht.
  • Selbstprüfung und Review: Befunde der Selbstprüfung, der Doku-Prüfung und des TDD-Reviews behoben; Vitest und Postgres-Tests fand das Review ohne Befund.
  • Lint (Biome für die geänderten Dateien und die vier Regel-Skripte; bun run lint als Ganzes meldet im Container eine lokale, git-ignorierte Datei), Typecheck aller Pakete, Doku mit Zensical --strict, PR-Regeln ohne Befund.
  • Nachprüfung des Maintainers auf de1aa823 ohne Befund (Migrationen gegen frische Datenbank, drizzle-kit check, § 18e Nr. 1 UStG, gezielte Vitest- und E2E-Läufe). Danach Merge von main und der Locator im neuen E2E-Test auf „Suche“, weil Navigation: Suchfeld heißt „Suche“, alle Kürzel passen hinein (#1386) #1415 den Knopf umbenannt hat.
  • In keinem Test fragt Haben das echte BZSt; von Hand lief nur eine Testabfrage mit den Beispielwerten aus der API-Doku.

Bilder

Rechte Spalte der Kontaktseite eines Kunden in Österreich, Testdaten; nachher nach Knopf und einem Speichern mit geänderter Straße gegen den nachgebauten Dienst.

Vorher Nachher
Hell, Desktop
Hell, Handy
Dunkel, Desktop
Dunkel, Handy

Für den Merge

Der Pull Request bringt die Migrationen 0289 und 0290, erzeugt auf 596e23ba. Kommt vorher eine andere Migration auf main, erzeuge ich sie neu, wenn er dran ist.


Generated by Claude Code

thomas-baumeister and others added 6 commits November 18, 2026 15:12
Rumpf der einfachen und qualifizierten Abfrage, Schema der Antwort, Zeitpunkt mit
Nanosekunden, Deutung der Status und wann nach dem Speichern eine neue Abfrage fällig ist.
Abgefragt werden nur Nummern, die die Formprüfung aus #1413 bestehen.

Quellen: OpenAPI-Beschreibung der eVatR-API v1.2.3 (https://api.evatr.vies.bzst.de/api-docs),
GET /app/v1/info/statusmeldungen, FAQ des BZSt zur USt-IdNr. (einfache vor qualifizierter
Bestätigung), gelesen 2026-11-18.

Refs #1385

Co-Authored-By: Claude <noreply@anthropic.com>
…hern (#1385)

Neue Tabelle ustid_bestaetigungen, nur anhängbar mit haben_append_only, Audit und Sperre
gegen TRUNCATE (Sollbestand der Trigger neu erzeugt). Die Abfrage geht erst einfach, bei
gültiger Nummer qualifiziert; jede Antwort zur Nummer wird sofort mit dem empfangenen
Datensatz gespeichert. Fehler des Dienstes bleiben ein Hinweis ohne Wiederholung.
HABEN_EVATR=off schaltet ab, EVATR_API_URL nur zum Testen. Das Jahresarchiv bekommt
stammdaten/ustid-bestaetigungen.csv.

Quellen: OpenAPI-Beschreibung der eVatR-API v1.2.3; UStAE 18e.1 Abs. 2, Stand 19.10.2026
(Nachweis über den empfangenen Datensatz); FAQ und Seite „Bestätigung ausländischer
USt-IdNrn“ des BZSt (keine schriftliche Bestätigung, bei Zeitüberschreitung nicht sofort
wiederholen).

Refs #1385

Co-Authored-By: Claude <noreply@anthropic.com>
#1385)

Die Kontaktseite zeigt die letzte Antwort mit dem Vergleich von Name und Anschrift, den
Knopf „Beim BZSt bestätigen“ und alle Abfragen. Nach dem Anlegen und Speichern fragt sie
einmal, wenn der Server es für fällig hält. In der E2E zeigen alle Server auf einen
nachgebauten Dienst; eingeschaltet ist die Abfrage nur im Durchlauf belege-steuern.

Refs #1385

Co-Authored-By: Claude <noreply@anthropic.com>
…1385)

yearFiles in export.ts ist längst über 80 Zeilen; statt sie für die neue Datei zu
verlängern, stehen kontakt-versionen.csv und ustid-bestaetigungen.csv jetzt in
export-kontakte.ts. Das Archiv bleibt gleich.

Refs #1385

Co-Authored-By: Claude <noreply@anthropic.com>
…1385)

Auf main ist 0288 inzwischen vergeben (0288_aufladung); die Tabelle kommt jetzt mit 0289
(drizzle-kit generate) und die Trigger mit 0290, Inhalt unverändert.

Refs #1385

Co-Authored-By: Claude <noreply@anthropic.com>
…1385)

- Nach dem Speichern zählt nur die letzte qualifizierte Bestätigung; zurück auf einen
  früheren Namen fragt Haben neu (vorher reichte irgendeine frühere).
- Eine Antwort ohne lesbaren Zeitpunkt oder ohne lesbares JSON meldet „ließ sich nicht
  lesen“ statt „Gültig“ oder „Keine Antwort“.
- Die Karte zeigt oben die letzte Antwort zur aktuellen Nummer und lädt nach der Abfrage
  nur die Kontaktseite neu.
- Die SSO-Tests schalten die Abfrage ab; Fundstelle UStAE 18e.1 Abs. 2 Sätze 3 bis 5;
  architektur.md nennt evatr.ts und ustid-bestaetigung, installation-konfiguration.md
  „unter Kontakte“.

Refs #1385

Co-Authored-By: Claude <noreply@anthropic.com>
@thomas-baumeister

Copy link
Copy Markdown
Collaborator Author

Selbstprüfung (beitrag-pruefen)

Stand: 8888537, geprüft in einem frischen Agenten ohne den Verlauf der Entstehung; Nachträge unten.

Wollen wir das?

Vollständig

Akzeptanzkriterium Ergebnis Datei oder Test
Speichern mit ATU… fragt einfach/qualifiziert, Ergebnis mit Zeitpunkt und Status am Kontakt, nicht änderbar teilweise Kontaktseite: e2e/ustid-bestaetigung.ts, ustid-bestaetigung.test.ts („nach dem Speichern“, „nicht ändern, löschen oder leeren“); Dialog im Rechnungseditor, CSV-Import und API nur per Knopf (kontakte.md, Grenzen)
Hinweis vor dem Festschreiben fehlt (Teil 2) –
ZM-Vorprüfung fehlt (Teil 2) –
Abgeschaltet oder 503 wie heute, Stub, keine echte Abfrage in der CI erfüllt ustid-bestaetigung.test.ts („Fehler des Dienstes“, „abgeschaltet“), playwright.config.ts
Hell, dunkel, Handy erfüllt Bilder in der Beschreibung; axe und Kontraste in e2e/ustid-bestaetigung.ts

Daher Refs #1385.

Quellen und fachlich heikel: ja (GoBD-Nachweis nach UStAE 18e.1, neue nur anhängbare Tabelle; keine Buchung, Steuer oder Meldung)

Aussage oder Fall Quelle, Fundstelle Ergebnis
Einfach mit zwei Feldern; qualifiziert ab firmenname und ort, Straße und PLZ optional OpenAPI v1.2.3, POST /v1/abfrage bestätigt
Erst einfach, dann qualifiziert FAQ des BZSt, Bestätigungsverfahren bestätigt
A bis D nur bei gültiger Nummer OpenAPI bestätigt
Status statt HTTP-Code (0008: 400 in der OpenAPI, 403 in den Statusmeldungen) OpenAPI, GET /app/v1/info/statusmeldungen bestätigt
Nachweis-Status 0000, 2001, 2002, 2006, 2008; Meldungen zu 2002 und 2006 Statusmeldungen bestätigt
Keine deutschen Nummern; anfragend die eigene deutsche Status 0006; UStAE 18e.1 Abs. 1; FAQ bestätigt
Keine schriftliche Bestätigung, nicht rückwirkend FAQ bestätigt
Nicht sofort wiederholen BZSt, Bestätigung ausländischer USt-IdNrn bestätigt
Empfangener Datensatz als Nachweis FAQ (Schnittstelle); UStAE 18e.1 Abs. 2 Satz 3 (Einzelanfrage) und Satz 5 (mehrere über die Schnittstelle), Stand 19.10.2026 bestätigt; Fundstelle präzisieren
Gegengerechnet: ATU12345678 mit allen Angaben OpenAPI-Beispiel = ustid-bestaetigung.test.ts „erst einfach, dann qualifiziert“
Randfall: 404 / evatr-2001; ohne Ort OpenAPI = Tests „nicht vergebene Nummer“, „ohne Ort nur einfach“
Größe der „Session“ bei evatr-0008 Doku schweigt nicht prüfbar; wie mit dem Maintainer vereinbart
Wann nach dem Speichern neu gefragt wird kontakte.md: „seit der letzten Bestätigung geändert“ widerspricht evatrNeuNoetig (vergleicht mit jeder früheren qualifizierten Bestätigung: A → B → A fragt nicht neu, die Karte zeigt dann den Vergleich zu B)

Einfachste Lösung?

Jeder Teil dient einem Kriterium. Formprüfung aus zm.ts (#1413), GoBD-Trigger und Archivhilfen werden wiederverwendet. Der Auslöser nach dem Speichern sitzt bewusst in der Oberfläche (Kontaktseite), nicht in saveContact: so keine Massenabfragen beim Import, und die Karte zeigt die Antwort sofort. Ob das so bleibt, ist eine Frage unten.

Regeln

Regel Ergebnis Stelle
Doku stimmt mit dem Code ✗ docs/kontakte.md:57 gegen packages/core/src/evatr.ts:175 (siehe oben)
Beschreibung zum Stand ✗ nennt Migrationen 0288/0289 und „erzeuge ich neu“; es sind 0289/0290, auf 596e23b erzeugt; „alle Server“ gilt nicht für playwright.sso-only.config.ts
Geld, SKR03/SKR04, Ist/Soll, Feldvertrag betrifft nicht keine Buchung
CI nicht prüfbar Entwurf: nur Docs und PR-Regeln (grün); der neue E2E-Test läuft erst mit „Ready for review“

Rest ✓ (lokal: evatr.test.ts, ustid-bestaetigung.test.ts, export-ustid-bestaetigungen.test.ts, trigger-inventory.test.ts, truncate.test.ts, 37 von 37).

Weitere Vorschläge ohne Pflicht:

  • unlesbarer anfrageZeitpunkt ergibt den Hinweis „Gültig“ ohne Nachweis (ustid-bestaetigung.ts:114, :123);
  • die Karte zeigt oben die letzte Antwort zu irgendeiner Nummer statt zur aktuellen (UstIdBestaetigungCard.tsx:47);
  • router.invalidate() nach der Abfrage im Hintergrund (:54) trifft die Seite, die gerade offen ist;
  • ustid-bestaetigung und evatr.ts in docs/architektur.md nennen;
  • HABEN_EVATR in installation-konfiguration.md: „unter Kontakte anlegt oder ändert“.

Offene Fragen an den Maintainer

  1. Automatisch fragt Haben nur auf der Kontaktseite; im Dialog des Rechnungseditors, beim CSV-Import und über die API nur per Knopf. Reicht das, wo Teil 2 vor dem Festschreiben warnt?
  2. Die neue Verbindung ist nach dem Update an und schickt Name und Anschrift von EU-Kunden an das BZSt: Satz in den Versionshinweisen?
  3. GoBD-Nachweis mit neuer Sperre: Merge nach deinem OK wie bei Teil 2?
  4. 20 s Zeitlimit je Anfrage bei den derzeit langen Antwortzeiten, die das BZSt nennt: passt das?

Nachtrag d8cd9d6

Beide ✗ und alle Vorschläge behoben; die zwei roten Tests der Selbstprüfung sind darauf grün, die neuen Testdateien 28 von 28, Typecheck grün.

  • Doku und Code: evatrNeuNoetig vergleicht nur noch mit der letzten qualifizierten Bestätigung zur Nummer; Test „zurück auf einen früheren Stand“ in evatr.test.ts.
  • Beschreibung: Migrationen 0289/0290 und „Für den Merge“ berichtigt; playwright.sso-only.config.ts setzt HABEN_EVATR: "off".
  • Unlesbare Antwort oder unlesbarer Zeitpunkt: Hinweis „Die Antwort des BZSt ließ sich nicht lesen; gespeichert ist nichts …“, getrennt von „Keine Antwort vom BZSt“; Test in ustid-bestaetigung.test.ts.
  • Karte: oben die letzte Antwort zur aktuellen Nummer, frühere Nummern unter „Alle Abfragen“; nach der Abfrage lädt sie nur die Kontaktseite neu (invalidate mit Filter auf /_app/kontakte/$id).
  • Fundstelle „UStAE 18e.1 Abs. 2 Sätze 3 bis 5, FAQ des BZSt“ in Code, Migration und kontakte.md; architektur.md nennt evatr.ts und ustid-bestaetigung; installation-konfiguration.md „unter Kontakte“.

Generated with Claude Code

@thomas-baumeister

Copy link
Copy Markdown
Collaborator Author

Doku-Prüfung (doku-pruefen)

Stand: d8cd9d6, geprüft in einem frischen Agenten, unabhängig von der Selbstprüfung; nur die geänderten .md-Dateien, den Code prüft tdd-review. Ich ändere nichts selbst, die Fixes macht die Session des PR.

Befunde

1. Fachliche Aussage ohne Quelle (docs/kontakte.md:55)

Für Reverse Charge und innergemeinschaftliche Lieferungen muss die USt-IdNr. des Kunden gültig sein, und wer sich darauf beruft, braucht einen Nachweis.

Der Link auf § 18e UStG im nächsten Satz belegt nur das Bestätigungsverfahren, nicht die Pflicht. Die Quellen dafür: § 6a Abs. 1 Satz 1 Nr. 4 UStG („eine ihm von einem anderen Mitgliedstaat erteilte gültige Umsatzsteuer-Identifikationsnummer verwendet“) für die Lieferung; für Reverse Charge UStAE 3a.2 Abs. 9 Sätze 4 und 5 (Stand 19.10.2026, S. 150): Mit der USt-IdNr. gilt der Kunde als Unternehmer, wenn der Leistende sich Gültigkeit, Name und Anschrift nach § 18e UStG hat bestätigen lassen. Vorschlag:

Für innergemeinschaftliche Lieferungen muss die USt-IdNr. des Kunden gültig sein (§ 6a Abs. 1 Satz 1 Nr. 4 UStG); bei Reverse Charge gilt der Kunde mit ihr als Unternehmer, wenn du sie samt Name und Anschrift bestätigen lässt (UStAE 3a.2 Abs. 9 Sätze 4 und 5). Das tut das Bundeszentralamt für Steuern (BZSt) im Bestätigungsverfahren (§ 18e UStG); Haben fragt es über dessen eVatR-Schnittstelle.

2. Ausnahmen unvollständig: REST-API fehlt (docs/kontakte.md:62)

Kontakte, die du aus Rechnung, Beleg oder Import anlegst, bestätigt Haben nicht von selbst; das geht auf ihrer Detailseite.

bestaetigeUstIdFn ruft nur die Karte auf (apps/web/src/components/UstIdBestaetigungCard.tsx:48), ausgelöst vom Formular auf /kontakte/neu und der Detailseite. POST /kontakte und PATCH /kontakte/{id} der REST-API (docs/api.md:37) legen Kontakte an und ändern Name und Anschrift ohne Abfrage; das Ändern nennt der Satz gar nicht. Vorschlag:

Kontakte, die du anderswo anlegst oder änderst (Dialog in Rechnung, Beleg und Vorlagen, Import, REST-API), bestätigt Haben nicht von selbst; das geht auf ihrer Detailseite.

3. Nummern mit falschem Aufbau: keine Abfrage, keine Karte, kein Wort dazu (docs/kontakte.md:23 und :62)

Die Nummer eines anderen EU-Mitgliedstaats bestätigt das BZSt.

evatrPruefbar (packages/core/src/evatr.ts:67) lässt nur Nummern durch, die auch ustIdAufbauProblem aus zm.ts bestehen. Ohne bisherige Antworten zeigt die Detailseite dann gar keine Karte (apps/web/src/routes/_app/kontakte/$id.tsx:102), und das Kontaktformular warnt nicht vor dem Aufbau (UstIdHinweis.tsx sucht nur Dubletten). Wer ATU1234567 tippt, sieht nichts und findet in der Doku keinen Grund. Dazu prüft Haben auch XI (Nordirland), das kein Mitgliedstaat ist (zm.ts, Kommentar in evatr.ts:65; FAQ des BZSt: XI-Nummern sind im Bestätigungsverfahren prüfbar). Vorschlag für „Grenzen“:

Deutsche Nummern bestätigt das BZSt nicht. Nummern, deren Aufbau nicht zum Land passt (geprüft wie bei der Vorprüfung der ZM), fragt Haben nicht an.

und in der Tabelle „Die Nummer eines anderen EU-Mitgliedstaats oder Nordirlands (XI) …“.

4. Klingt, als bestätige Haben vor dem Festschreiben (docs/rechnungen.md:216)

Ob die Nummer erteilt ist, bestätigt vorher das BZSt am Kontakt.

Vorher stand dort eine Handlung des Nutzers („klärst du vorher mit der Bestätigungsabfrage“). Jetzt liest es sich wie ein Schritt, den Haben vor dem Festschreiben erledigt. Das tut es nicht: Festschreiben prüft die Bestätigung nicht (docs/kontakte.md:62), und einen Kunden aus dem Dialog im Rechnungseditor fragt Haben nicht an (InvoiceEditor.tsx:714 → NewContactDialog → ContactForm.tsx:124, Zweig onSaved ohne Abfrage). Vorschlag:

Ob die Nummer erteilt ist, lässt du vorher am Kontakt vom BZSt bestätigen.

(docs/umsatzsteuer.md:167 „am besten vor der ersten Rechnung“ bleibt als Rat erkennbar, passt.)

5. Vergessene Stelle (docs/csv-import.md:78, nicht im Diff)

Ob sie erteilt ist, weiß nur das BZSt

Wie die geänderten Sätze in rechnungen.md und umsatzsteuer.md verweist diese Stelle auf die Bestätigung beim BZSt, die es jetzt in Haben gibt; gerade importierte Kontakte bestätigt Haben aber nicht von selbst (kontakte.md:62). Vorschlag:

Ob sie erteilt ist, bestätigt das BZSt auf der Detailseite des Kontakts; der Import fragt nicht an.

6. Weiter als der Code, und die Regel zum zweiten Mal (docs/installation-konfiguration.md:74)

Sonst fragt der Server api.evatr.vies.bzst.de, wenn jemand unter Kontakte einen Kontakt mit ausländischer USt-IdNr. anlegt oder ändert oder die Bestätigung von Hand anstößt

evatrNeuNoetig (packages/core/src/evatr.ts:169) fragt nach dem Speichern nur, wenn die Nummer noch keine Antwort hat oder Name oder Anschrift von der letzten qualifizierten Bestätigung abweichen. Ändert jemand nur E-Mail oder Telefon, oder war die Nummer zuletzt ungültig (:174), fragt Haben nicht. Wann genau, sagt kontakte.md („Wann“); hier reicht, ob und wohin. Vorschlag:

Sonst fragt der Server api.evatr.vies.bzst.de nur zu Kontakten mit ausländischer USt-IdNr., nach dem Speichern unter Kontakte, wenn eine Bestätigung fällig ist, oder von Hand

Ohne Beanstandung geprüft

  • Gegen die OpenAPI v1.2.3 und GET /app/v1/info/statusmeldungen: einfach mit zwei Feldern, qualifiziert ab firmenname und ort, Straße und PLZ optional; A bis D nur bei gültiger Nummer, die Wörter Stimmt bis Nicht mitgeteilt = EVATR_VERGLEICH; Nachweis-Status 0000, 2001, 2002, 2006, 2008 = „gültig, nicht vergeben, noch nicht oder nicht mehr gültig“; evatr-0006 (keine deutschen Nummern), evatr-0008 (Höchstzahl), „später noch einmal“.
  • Gegen die FAQ des BZSt: erst einfach, dann qualifiziert; Datensatz als Nachweis bei der Schnittstelle; keine schriftliche Bestätigung; nichts rückwirkend; Weitergabe an die Mitgliedstaaten.
  • UStAE 18e.1 Abs. 2 (S. 725): Satz 3 deckt die Übernahme des Ergebnisses bei Einzelanfragen, Sätze 4 und 5 den Datensatz über die Schnittstelle; „Sätze 3 bis 5“ trifft für Einzelanfragen über die Schnittstelle zu.
  • kontakte.md gegen den Code: Wann (evatrNeuNoetig, auch „zuletzt ungültig“), Speichern wartet nicht, ohne Ort nur einfach, gesendete Angaben (evatrAnfrage), Fehler ohne Speichern und ohne Wiederholung, evatr-0008 mit einfacher Antwort und neuer Abfrage beim nächsten Speichern, Karte mit letzter Antwort zur aktuellen Nummer und „Alle Abfragen“, „ohne-eigene“, Knopf und Überschrift, nur anhängbar mit Audit (Migration 0290).
  • installation-konfiguration.md: HABEN_EVATR (Karte nur mit Antworten), EVATR_API_URL = EVATR_URL, Zeile zu compose.yml (dort kein HABEN_EVATR). architektur.md: Verbindung nach außen wie vom Maintainer verlangt, evatr.ts, Modul ustid-bestaetigung. architektur-datenmodell.md gegen schema.ts und Migrationen. auswertungen.md gegen export-kontakte.ts (Datei nur wenn vorhanden, Jahr nach anfrageZeitpunkt in deutscher Zeit, Spalten). ueberblick.md und Front Matter von kontakte.md.
  • Kurz: keine Ankündigungen, Zusammenfassungen oder Füllwörter; keine Regel doppelt außer Befund 6. Nichts Erzeugtes, kein ADR, keine Skills, CLAUDE.md und AGENTS.md unberührt, nichts gegen „Never“.
  • zensical build --strict: „No issues found“, auch die Anker #ust-idnr-beim-bzst-bestätigen, einrichtung.md#firmendaten, auswertungen.md#jahresexport.

Generated with Claude Code

…1385)

Pflicht zur gültigen USt-IdNr. mit § 6a Abs. 1 Satz 1 Nr. 4 UStG und UStAE 3a.2 Abs. 9
Sätze 4 und 5 belegt; Grenzen nennen den Aufbau je Land, Nordirland, REST-API und das
Ändern anderswo; rechnungen.md und csv-import.md sagen, dass man die Bestätigung selbst
anstößt; die Zeile zu HABEN_EVATR wiederholt die Regel aus kontakte.md nicht mehr.

Refs #1385

Co-Authored-By: Claude <noreply@anthropic.com>
@thomas-baumeister

Copy link
Copy Markdown
Collaborator Author

TDD-Review (tdd-review)

Stand: d8cd9d6, unabhängig geprüft (Code, Tests, SQL, Konfiguration; die Markdown-Dateien prüft doku-pruefen parallel). Quellen: OpenAPI v1.2.3, GET /app/v1/info/statusmeldungen und GET /app/v1/info/eu_mitgliedstaaten, heute gelesen.

Befunde mit rotem Vitest- oder Postgres-Test

Keine. Kein Verdacht in packages/core/src/evatr.ts, stammdaten/ustid-bestaetigung.ts, im Jahresarchiv oder in den Migrationen ließ sich mit einem Test rot zeigen.

Nur mit Playwright prüfbar (im Container keine Browser), mit Nachstellung belegt

1. Der neue E2E-Test wird in der CI rot – apps/web/e2e/ustid-bestaetigung.ts:81

await page.getByRole("button", { name: "Speichern", exact: true }).click();
await expect(page.getByRole("status").filter({ hasText: "Gespeichert." })).toBeVisible();

Direkt nach dem zweiten Klick stehen zwei Status-Banner auf der Seite: Das Formular zeigt weiter „Gespeichert. Die vorige Fassung bleibt als Version erhalten.“ (ContactForm.tsx:327, saved bleibt nach dem ersten Speichern true), die Karte noch „Antwort des BZSt gespeichert.“ vom Speichern davor; ihr run leert die Meldung erst, wenn die Abfrage nach dem Speichern startet, also nach der Antwort von saveContact. hasText sucht ohne Groß- und Kleinschreibung als Teilstring, beide passen. toBeVisible wiederholt bei zwei Treffern nicht, sondern bricht sofort ab. Nachgestellt mit playwright-core 1.64.1 (aus bun.lock) und genau diesen beiden Bannern über den Matcher to.be.visible:

nach 12 ms: matches=false, Error: strict mode violation: getByRole('status').filter({ hasText: 'Gespeichert.' }) resolved to 2 elements:

Danach überspringt der serielle Durchlauf belege-steuern die restlichen Tests. Einschränken etwa mit page.getByRole("form", { name: "Kontakt" }).getByRole("status").

2. Wer nach „Kontakt anlegen“ gleich weiterklickt, wird später auf eine kaputte Kontaktseite umgeleitet – apps/web/src/routes/_app/kontakte/$id.tsx:111

if (bestaetigen) void navigate({ search: (s) => ({ ...s, bestaetigen: undefined }), replace: true });

Das läuft über pruefen(true).finally(onNachSpeichernErledigt) (UstIdBestaetigungCard.tsx:76) auch dann, wenn die Kontaktseite schon verlassen ist. useNavigate({ from: "/kontakte/$id" }) ohne to und params löst gegen den aktuellen Ort auf. Antwortet das BZSt langsam (bis zu 2 × 20 s) und ist man inzwischen etwa auf /rechnungen/neu, ersetzt der Aufruf diese Seite durch /kontakte/undefined. Was dort schon getippt war, ist ohne Rückfrage weg, weil es keinen Blocker gibt. Nachgestellt mit dem Router aus bun.lock (@tanstack/react-router 1.170.46, Speicher-Historie, derselbe Aufruf):

vorher /rechnungen/neu
Could not find match for from: /kontakte/$id
nachher /kontakte/undefined
vorher /rechnungen/r-42
Could not find match for from: /kontakte/$id
nachher /kontakte/r-42

3. Beim Wechsel zu einem anderen Kontakt fragt die Karte beim BZSt an, ohne dass gespeichert wurde – $id.tsx:60 und :97

Beim Wechsel von /kontakte/A zu /kontakte/B baut TanStack Router die Seite nicht neu auf: Match ist nur nach routeId geschlüsselt, ohne remountDeps. Deshalb merkt sich die Seite für die Meldung beim Formular savedId statt eines Booleans. nachSpeichern ist dagegen ein Boolean und bleibt true, solange keine Karte ihn verbraucht, etwa nach dem Speichern eines Kontakts mit deutscher oder ohne USt-IdNr. Springt man dann über die Schnellsuche zu einem EU-Kontakt, der nie bestätigt wurde (angelegt im Rechnungsdialog oder per Import), startet dessen Karte sofort die Abfrage „nach dem Speichern“. Name und Anschrift gehen dann ans BZSt, obwohl kontakte.md sagt, solche Kontakte bestätige Haben nicht von selbst. Aus demselben Grund bleibt die Meldung der Karte (useAction) beim Wechsel stehen und erscheint beim nächsten Kontakt. Das habe ich nur am Quelltext des Routers belegt (Match.js, MatchInner), nicht nachgestellt.

Für 2 und 3 schlage ich einen Playwright-Test im Durchlauf belege-steuern vor, mit einer Attrappe, die die Antwort verzögert. Mögliche Lösungen: die Karte mit key={contact.id}, nachSpeichern als Kontakt-ID wie savedId, die Navigation nur, solange die Seite den Kontakt noch zeigt.

Geprüft, ohne Befund

  • Statuscodes: Die Nachweise 0000, 2001, 2002, 2006 und 2008 stimmen mit OpenAPI und Statusmeldungen überein. 0003, 0007 und 2007 fallen in den Standardtext. 0003 kann nicht kommen, weil Name und Ort vor der qualifizierten Abfrage getrimmt geprüft werden. XI steht in eu_mitgliedstaaten.
  • Zeitpunkt: Nanosekunden, Zeitzone und fehlende Nachkommastellen werden richtig gelesen. Ein unlesbarer Zeitpunkt speichert nichts.
  • Reihenfolge und „fällig“: einfach und qualifiziert stehen in getrennten Transaktionen, created_at steigt also. Geprüft: Limit, Ausfall der qualifizierten Abfrage, zurück auf einen früheren Stand, leere Straße und PLZ.
  • Rechte: Beide Server-Funktionen hängen an authMiddleware; die Kontaktseite war schon vorher nur für den Inhaber.
  • GoBD: haben_append_only, Audit, Sperre gegen TRUNCATE und Sollbestand sind da. Kontakte lassen sich nicht löschen, der Fremdschlüssel ohne Kaskade ist deshalb unkritisch. Alle Tests, die contacts leeren, laufen über leeren oder session_replication_role. Die Rechte der getrennten Datenbankrollen vergibt roles.ts für alle Tabellen.
  • Migrationen: Die Kette der Snapshots (prevId) stimmt, der Snapshot 0290 ist gleich 0289. git merge-tree mit main läuft ohne Konflikt durch, main steht bei 0288.
  • Jahresarchiv: Die Jahresgrenze in deutscher Zeit stimmt, index.xml führt die neuen Spalten als Text, die Antwort wird im CSV richtig maskiert.
  • E2E-Konfiguration: Port PORT+34 ist frei. Nur belege-steuern fragt ab, sso-only hat die Abfrage aus. Der Server läuft über node-server, eine Abfrage von 2 × 20 s trennt also kein idleTimeout.

Lokal im Dev-Container mit PostgreSQL 18 (gezielt, die volle Suite läuft in der CI): evatr.test.ts, ustid-bestaetigung.test.ts, export-ustid-bestaetigungen.test.ts (28 von 28), trigger-inventory.test.ts, truncate.test.ts, triggers.test.ts, archiv/export.test.ts, rollen.test.ts, modulgrenzen.test.ts, schema-einheiten.test.ts (66 von 66). Nicht gelaufen: Playwright, Lint, Typecheck.

Generated with Claude Code

… Navigation (#1385)

Befunde aus dem Review: Die Kontaktseite merkte sich „nach dem Speichern fragen“ als
Boolean; beim Wechsel zu einem anderen Kontakt in derselben Seite fragte dessen Karte
ohne Speichern beim BZSt an. Jetzt gilt das Merkzeichen je Kontakt-ID wie savedId, und die
Karte entsteht je Kontakt neu (key). Den Suchparameter nach dem Anlegen nimmt die Seite
gleich beim Laden weg; vorher geschah das erst nach der Antwort und ersetzte, wer schon
auf „Rechnung schreiben“ war, durch /kontakte/undefined. Im E2E-Test grenzt der Selektor
die Meldung „Gespeichert.“ auf das Formular ein, und ein zweiter Test spielt Wechsel über
die Schnellsuche und Verlassen bei langsamer Antwort durch.

Refs #1385

Co-Authored-By: Claude <noreply@anthropic.com>
@thomas-baumeister

Copy link
Copy Markdown
Collaborator Author

Nachbesserungen nach Doku-Prüfung und TDD-Review

TDD-Review (Kommentar), behoben in de1aa82:

  1. Mehrdeutiger Selektor im E2E-Test: „Gespeichert.“ jetzt über getByRole("form", { name: "Kontakt" }).getByRole("status").
  2. Späte Navigation nach dem Anlegen: Die Kontaktseite nimmt ?bestaetigen gleich beim Laden weg, nicht erst nach der Antwort.
  3. Abfrage beim Wechsel zu einem anderen Kontakt: Das Merkzeichen gilt je Kontakt-ID wie savedId, die Karte entsteht je Kontakt neu (key).

Vor dem Fix mit playwright-core gegen die Dev-Instanz und einen nachgebauten Dienst mit 2,5 s Verzögerung nachgestellt: Wechsel über die Schnellsuche 2 Abfragen, „Rechnung schreiben“ endete auf /kontakte/undefined. Danach 0 Abfragen und /rechnungen/neu; Anlegen und Speichern mit neuer Straße fragen weiter je zweimal. Der zweite neue E2E-Test in e2e/ustid-bestaetigung.ts spielt beides durch; er läuft erst in der CI.

Doku-Prüfung (Kommentar), behoben in 998d985:

  1. Pflicht mit § 6a Abs. 1 Satz 1 Nr. 4 UStG und UStAE 3a.2 Abs. 9 Sätze 4 und 5 belegt (beide nachgelesen, UStAE Stand 19.10.2026).
  2. und 3. Grenzen nennen Dialoge, Import, REST-API und das Ändern anderswo, den Aufbau je Land und Nordirland (XI).
  3. und 5. rechnungen.md und csv-import.md: Die Bestätigung stößt man am Kontakt selbst an.
  4. HABEN_EVATR: wiederholt die Regel aus kontakte.md nicht mehr.

Lokal danach: Biome, Typecheck, die drei neuen Testdateien grün. Die Beschreibung ist aktualisiert.

Generated with Claude Code

Copy link
Copy Markdown
Owner

Beitragsprüfung (beitrag-pruefen, Maintainer)

Danke, Thomas, das ist sauber nach dem abgestimmten Plan gebaut:

  • Die Fachlogik liegt in packages/core.
  • Die Tabelle ist nur anhängbar, mit Audit und TRUNCATE-Sperre.
  • Die Antwort steht unverändert im Jahresarchiv.
  • Die Abfrage lässt sich abschalten und ist in keinem Test echt.
  • Die Doku sagt genau, welche Angaben ans BZSt gehen.

Stand: de1aa823. Selbstprüfung, Doku-Prüfung und TDD-Review haben wir nachgeprüft statt neu gemacht. Das TDD-Review endet auf d8cd9d65, deshalb haben wir den Fix in de1aa823 selbst gegengeprüft.

Geprüft

  • Migrationen 0289/0290: laufen gegen eine frische Datenbank durch; drizzle-kit check und generate zeigen keine Abweichung. Die prevId-Kette stimmt, es kommen nur neue Dateien dazu, und mit main gibt es keinen Konflikt (letzte Migration dort weiter 0288).
  • § 18e Nr. 1 UStG gegengelesen: Anfragend ist die eigene deutsche Nummer, bestätigt werden Nummern anderer Mitgliedstaaten. Die Fälle „ATU… mit Name und Ort: erst einfach, dann qualifiziert“ und „ohne Ort: nur einfach“ stimmen mit den Tests.
  • Lokal:

Zu deinen offenen Fragen: Die Abfrage läuft automatisch nur auf der Kontaktseite, sonst per Knopf. Das reicht, weil Teil 2 vor dem Festschreiben warnt. Das Zeitlimit von 20 s passt. Für die Versionshinweise nehmen wir einen Satz auf: Haben fragt jetzt api.evatr.vies.bzst.de und übermittelt dabei bei der qualifizierten Abfrage Name und Anschrift von EU-Kunden; abschaltbar mit HABEN_EVATR=off.

Wir mergen, sobald die CI auf de1aa823 ganz grün ist. Danach erzeugt #1423 seine Migrationen neu.


Generated by Claude Code

Seit #1415 auf main heißt der Knopf der Befehlspalette „Suche“; der neue
Test suchte noch „Schnellsuche“ und lief in der CI nach dem Merge mit main
in die Zeitüberschreitung.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y3rdfc4brdCss3uTQVHyAL

Copy link
Copy Markdown
Owner

Nachtrag: e2e-teil (4) war rot, weil der neue Test „Wechsel zu einem anderen Kontakt“ (e2e/ustid-bestaetigung.ts:127) in die Zeitüberschreitung lief. Er suchte den Knopf „Schnellsuche“. Seit #1415 auf main heißt der Knopf „Suche“, und die CI prüft den PR zusammen mit main.

Auf deinem Branch liegen jetzt zwei Commits von uns:

  • 42c1e1f9: Merge von main, ohne Konflikt.
  • b0e002c9: Der Locator heißt jetzt { name: "Suche", exact: true }, wie in befehlspalette.spec.ts.

Biome und Typecheck sind grün. Den Test selbst prüft die CI. Wir mergen, wenn sie grün ist.


Generated by Claude Code

@firsttris
firsttris merged commit 3f5ef23 into main Nov 18, 2026
26 checks passed
@firsttris
firsttris deleted the ustid-bestaetigung branch November 18, 2026 15:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants