4 · Administrationsreferenz

Statuswerte

Jede Prüfung liefert einen normalisierten Status, abgeleitet aus dem Qualitätscode der Post (PSTAT) und dem transportseitigen Aufrufstatus. Der Status steuert die Ampel und das Gate-Verhalten.

Status (Anzeige)	PSTAT	Ampel	Bedeutung
Nicht geprüft	–	⚪ grau	Es wurde noch keine Prüfung durchgeführt.
Korrekt	1	🟢 grün	Adresse ist wie erfasst gültig und zustellbar.
Vorschlag (Schreibweise)	2	🟡 gelb	Die Post schlägt eine standardisierte Schreibweise vor.
Vorschlag (Korrektur)	3 / 5	🟡 gelb	Die Post schlägt eine korrigierte Adresse vor.
Vorschlag (Vervollständigung)	4	🟡 gelb	Die Post schlägt eine ergänzte Adresse vor (z. B. fehlende Hausnummer).
Teilweise bestätigt	6	🔴 rot	Nur ein Teil (Strasse, PLZ oder Hausnummer) konnte bestätigt werden.
Nicht gefunden	7	🔴 rot	Die Adresse wurde nicht gefunden.
Nicht eindeutig	8	🔴 rot	Mehrere mögliche Treffer.
Ausländisch (nicht geprüft)	9 / Ländergrenze	⚪ grau	Kein Aufruf – Adresse ausserhalb CH/LI.
Fehler	10 / Transport	🔴 rot	Die Prüfung konnte nicht abgeschlossen werden.

Vorschlag ≠ übernommen: Ein Vorschlag-Status bedeutet, dass die Post eine bessere Adresse anbietet – am Datensatz wurde nichts automatisch geändert. Die Übernahme erfolgt bewusst per Klick.

Feldreferenz «Adressvalidierung Einrichtung»

Verbindung

Feld	Bedeutung
Umgebung	Test- oder Produktionsendpunkt der Post.
Basis-URL (Produktion / Test)	REST-Basis-URL inkl. Port und abschliessendem `/` (vorbelegt).
Benutzername	Reiner technischer Benutzer (z. B. `TU_1234567_0001`) ohne `@service.post.ch`.
Passwort	Wird verschlüsselt im Isolated Storage abgelegt (nicht im Einrichtungssatz).
Timeout (ms)	HTTP-Timeout für Aufrufe an die Post (Standard 10 000).

Auslöser und Modi

Feld	Bedeutung	Standard
Manuelle Schaltfläche aktivieren / Button-Modus	Aktion Adresse prüfen auf den Karten.	an / Vorschlag
Karten automatisch prüfen	Autoprüfung + Hinweis beim Ändern eines Adressfeldes.	an
Adressen auf Belegen prüfen	Prüfung + Hinweis beim Ändern der Belegadresse.	an
Freigabe-Gate aktivieren / -Modus	Prüfung beim Freigeben.	an / Vorschlag
Belegdruck-Gate aktivieren / -Modus	Prüfung vor Druck unbuchbarer Belege.	an / Vorschlag
Mahn-Gate aktivieren / -Modus	Prüfung beim Ausstellen und vor Druck/Versand der Mahnung.	an / Vorschlag
Buchungs-Gate aktivieren / -Modus	Prüfung vor dem Buchen.	an / Blockieren
Druck-Gate aktivieren / -Modus	Prüfung vor Druck gebuchter Rechnung.	an / Vorschlag
Versand-Gate aktivieren / -Modus	Prüfung vor Versand gebuchter Rechnung.	an / Vorschlag
Auch bei E-Mail prüfen	Prüfung auch beim E-Mail-Versand.	aus

Blockier-Verhalten (nur im Modus Blockieren)

Feld	Standard
Blockieren: Teilweise bestätigt (PSTAT 6)	aus
Blockieren: Adresse nicht gefunden (PSTAT 7)	an
Blockieren: Adresse nicht eindeutig (PSTAT 8)	aus
Blockieren, wenn Post nicht erreichbar	aus
Blockieren: Korrektur verfügbar	aus

Hintergrund-Warteschlange

Feld	Standard
Warteschlange: Debitoren / Lieferadressen / Kontakte / Kreditoren / Bestelladressen	alle an
Stapelgrösse pro Lauf	50
Laufintervall (Minuten)	30
Erneute Prüfung (Tage)	90
Hausnummern bei falscher/fehlender Nr. auflisten	an
Log-Verlauf aufbewahren (Tage)	0 (für immer)
Bei Verschlechterung erneut öffnen	an
Zurückgestellte erneut öffnen nach (Tagen)	30
Erledigte erneut öffnen nach (Tagen)	0 (aus)

Datenschutz und Datenhaltung

Keine zusätzlichen Felder auf den Stammtabellen. Alle Prüfdaten liegen in eigenen Tabellen der App, verknüpft über Quelltabellennr. + Quell-System-ID: ein Prüfprotokoll (vollständiger Verlauf) und eine Ergebnistabelle (je Quelle das aktuellste Ergebnis).
Passwort verschlüsselt im Isolated Storage (Unternehmensbereich) – nie im Klartext im Einrichtungssatz. Die Authentifizierung erfolgt durchgehend als SecretText.
Sparsame API-Nutzung – ein normalisierter Adress-Hash (SHA256) verhindert identische Wiederholungsaufrufe; ausländische Adressen werden ohne Aufruf übersprungen.
Datenklassifizierung des Einrichtungssatzes: CustomerContent.
Übermittelte Daten: Für die Prüfung werden die Adressbestandteile (Strasse/Hausnr., PLZ, Ort, Land) an den Adress-Webservice der Schweizerischen Post übermittelt. Massgeblich ist die Datenschutzerklärung der Post für den Adress-Webservice.

Berechtigungen

Die App liefert zwei Berechtigungssätze:

Berechtigungssatz	Objektname	Für wen
Ventoo Address Validation	`AddressValidUserVTO`	Tägliche Nutzung: Arbeitsvorrat bearbeiten, Stichwörter pflegen, Adressen prüfen, Einrichtung lesen.
Ventoo Address Validation - Setup	`AddressValidAdminVTO`	Konfiguration: enthält den Benutzer-Satz und das Bearbeiten der Einrichtung (Endpunkte, Zugangsdaten, Gates) sowie Installation/Upgrade.

Ohne Berechtigungssatz nutzbar: Die automatischen Abläufe (Infoboxen, Gates, Rollencenter-Cues, Hintergrund-Warteschlange) laufen für jeden Benutzer über die inhärenten Rechte der Objekte – niemand erhält bei der normalen Arbeit einen Berechtigungsfehler. Der Einrichtungssatz ist als Read + Insert hinterlegt, sodass der erste Zugriff den Datensatz automatisch anlegt.

Weisen Sie den aktiv im Arbeitsvorrat tätigen Personen Ventoo Address Validation zu; der Person, die den Dienst konfiguriert, Ventoo Address Validation - Setup. Der Person für die Adresspflege zusätzlich das Profil Address Data Steward.

Technische Eckdaten

Merkmal	Wert
Plattform	Business Central (SaaS), BC 28 / Runtime 17.0
Objekt-ID-Bereich	70679775 – 70679799
Objekt-Namenszusatz	`VTO` (Suffix an jedem Objekt- und Steuerelementnamen)
Post-Dienst	Adress-Webservice, Tarifstufe Address Assistant (`BuildingVerification4`)
Sprachen	Entwicklungssprache `en-US`; Übersetzungen `de-CH`, `fr-CH`, `it-CH`
Herausgeber	Ventoo · https://www.ventoo.ch

Fehlerbehebung

Symptom	Mögliche Ursache / Lösung
Verbindung testen schlägt fehl	Benutzername mit `@service.post.ch`-Zusatz eingegeben (nur den reinen `TU_…`-Namen verwenden); falsches Passwort; falsche Umgebung (Test/Produktion).
Alle Adressen sind Ausländisch (nicht geprüft)	Länder-/Regionscode ist nicht CH/LI und nicht leer – so gewollt (Ländergrenze).
Prüfung scheinbar «hängt» beim Massenlauf	Minutenlimit der Post erreicht (Fehler 106); die Warteschlange fährt beim nächsten Lauf fort. Stapelgrösse ggf. senken.
Gate blockiert unerwartet	Buchungs-Gate-Modus steht auf Blockieren und ein Blockier-Kriterium (z. B. PSTAT 7) trifft zu – Adresse korrigieren oder Modus/Kriterium anpassen.
Gate warnt/blockiert immer wieder bei bereits geprüfter Adresse	Adresse im Arbeitsvorrat auf Erledigt oder Zurückgestellt setzen; die Gates vertrauen dann genau dieser Adresse und warnen/blockieren nicht mehr. Erscheint sie erneut, hat sich die Adresse geändert oder wurde wiedervorgelegt (verschlechtertes Ergebnis / Wiedervorlage-Frist).
Korrekturvorschlag wird nicht angezeigt	Adresse ist bereits Korrekt (PSTAT 1) oder Ausländisch; nur bei Vorschlag-Status gibt es einen übernehmbaren Wert.