Was die Funktion leistet

Gebaut für Schweizer Rechnungsstellung, nicht für generische Formularprüfungen

Schweizer QR-Rechnungen haben strenge Adressregeln. HelvAddress macht daraus eine produktionsreife API, auf die sich Ihre Teams verlassen können.

Erkennt Modus S oder K automatisch

Senden Sie strukturierte Felder oder zwei Freitextzeilen. Die API erkennt automatisch, ob die Adresse im strukturierten Modus (S) oder kombinierten Modus (K) validiert werden muss.

Validiert jedes einzelne Feld

Prüft Maximallängen, Pflichtfelder, zulässige Zeichen und QR-Rechnungsregeln, bevor ein Dokument erzeugt wird.

Prüft echte Schweizer Postleitzahlen

Postleitzahlen werden nicht nur formal geprüft. Sie werden gegen das offizielle Schweizer Post-Ortschaftsverzeichnis validiert.

Liefert strukturierte Verstösse zurück

Antwortet immer mit HTTP 200 und `valid` true/false plus einer sauberen Liste von Verstössen je Feld, Code und Meldung – ideal für Formulare und Geschäftsprozesse.

Compliance-fähig by design

Explizit ausgerichtet auf SIX Swiss Payments Standard v2.3

Das ist die Validierungsschicht, die Schweizer Fakturierungsteams brauchen, bevor sie eine QR-Rechnung drucken, exportieren oder versenden.

HelvAddress bietet einen dedizierten Endpoint für QR-Rechnungs-Adressvalidierung, damit Sie SIX-Regeln nicht selbst im ERP, E-Commerce oder in Ihrer Fakturierungsplattform nachbauen müssen.

Das Ergebnis sind einfachere Compliance, weniger Rechnungs-Ausnahmen und ein schnellerer Weg in die Produktion für Schweizer Zahlungsprozesse.

Was der Endpoint garantiert

Der Vertrag ist bewusst so gestaltet, dass er sich einfach in Formulare, APIs und Dokumentpipelines integrieren lässt.

Nur Schweizer Adressen (`countryCode = CH`)
Funktionale Antworten kommen immer als HTTP 200 mit strukturiertem Body
Wenn gültig, ist das Objekt `formatted` direkt verwendbar
Adressmodi

Unterstützt beide QR-Rechnungs-Adressstile

Ob Ihr System vollständig strukturierte Adressen speichert oder noch mit historischen Freitextzeilen arbeitet – der Validierungsfluss passt sich Ihrem Datenmodell an.

MODE S streetName · buildingNumber · postalCode · town
Modus S — strukturierte Adressen

Verwenden Sie getrennte Felder, wenn Ihr System Strasse, Hausnummer, Postleitzahl und Ort bereits separat speichert.

  • Ideal für ERP, CRM, Billing-Engines und Stammdatenplattformen
  • Validiert `streetName`, `buildingNumber`, `postalCode` und `town` Feld für Feld
  • Optimal für präzises Feedback in strukturierten Formularen
MODE K addressLine1 · addressLine2
Modus K — kombinierte Adresszeilen

Verwenden Sie zwei Freitextzeilen, wenn das Vorsystem Adressen noch im klassischen kombinierten Schweizer Zahlungsformat speichert.

  • Gut geeignet für Legacy-Buchhaltungssysteme und importierte Adressdaten
  • Validiert `addressLine1` und `addressLine2` gegen QR-Rechnungsregeln
  • Ermöglicht Compliance-Kontrollen, ohne zuerst Ihr Datenmodell umzubauen
Automatische Moduserkennung Wenn `addressLine1` oder `addressLine2` vorhanden ist, validiert die API im Modus K. Andernfalls verwendet sie automatisch Modus S.
Was geprüft wird

Die wichtigsten Kontrollen passieren in einem Request

Der Endpoint beantwortet die geschäftskritische Frage: Darf diese Adresse jetzt auf einer Schweizer QR-Rechnung erscheinen?

1
Feldlängen

Setzt SIX-Maximallängen durch, etwa 70 Zeichen für Namen und Strassen, 16 für Postleitzahl oder Hausnummer und 35 für den Ort.

2
Zulässiger Zeichensatz

Lehnt unzulässige Zeichen und Steuerzeichen ab, damit die Adresse mit den Vorgaben der Schweizer QR-Rechnung kompatibel bleibt.

3
Schweizer PLZ-Regeln

Prüft, dass Schweizer Postleitzahlen – wo anwendbar – das erwartete 4-stellige Format einhalten und zum angeforderten Land passen.

4
Abgleich mit offiziellem Postverzeichnis

Bestätigt, dass die Postleitzahl im offiziellen Schweizer Post-Ortschaftsverzeichnis existiert und nicht nur formal korrekt aussieht.

5
Sofort nutzbare Formatierung

Wenn die Adresse gültig ist, liefert die API ein bereinigtes `formatted`-Objekt zurück, das direkt für die QR-Rechnung verwendet werden kann.

Antwortdesign

Leicht in Formulare, Workflows und Fakturierungssysteme integrierbar

Kein exception-lastiger Flow, kein Rätselraten. Ihre Anwendung erhält jedes Mal ein explizites Resultat.

Request-Beispiel
POST /api/addresses/validate/qrbill
Authorization: Bearer {access_token}
Content-Type: application/json
X-HelvAddress-API-Version: 1.0.0

{
  "name": "Max Muster AG",
  "streetName": "Bahnhofstrasse",
  "buildingNumber": "1",
  "postalCode": "8001",
  "town": "Zürich",
  "countryCode": "CH"
}
Gültige Antwort
{
  "valid": true,
  "mode": "S",
  "violations": [],
  "formatted": {
    "mode": "S",
    "name": "Max Muster AG",
    "streetName": "Bahnhofstrasse",
    "buildingNumber": "1",
    "postalCode": "8001",
    "town": "Zürich",
    "countryCode": "CH"
  }
}
Ungültige Antwort
{
  "valid": false,
  "mode": "S",
  "violations": [
    {
      "field": "postalCode",
      "code": "INVALID_POSTAL_CODE",
      "message": "postalCode must be a valid Swiss postal code"
    },
    {
      "field": "town",
      "code": "FIELD_REQUIRED",
      "message": "town is required"
    }
  ]
}
Dadurch eignet sich HelvAddress besonders für Inline-Validierung: Das Frontend kann exakt das betroffene Feld und die richtige Meldung hervorheben, ohne mehrere HTTP-Fehlerpfade zu behandeln.
Business-Nutzen

Ein besserer Weg, Schweizer Zahlungsprozesse abzusichern

Jedes Schweizer Unternehmen, das Rechnungen erstellt oder Zahlungen verwaltet, braucht verlässliche Adress-Compliance, bevor eine QR-Rechnung erzeugt wird.

Fakturierungs- und ERP-Teams

Validieren Sie Gläubiger- und Schuldneradressen vor PDF-Erstellung, Batch-Exporten oder Druckprozessen.

Anbieter von Billing-Software

Integrieren Sie Schweizer QR-Rechnungs-Compliance direkt in Ihr Produkt, ohne selbst eine Regel-Engine oder PLZ-Referenzdaten pflegen zu müssen.

E-Commerce und Portale

Erkennen Sie adressbedingte Zahlungsprobleme früher im Checkout oder Konto-Flow – noch bevor die Rechnung erzeugt wird.

Brauchen Sie Schweizer QR-Rechnungs-Compliance ohne Eigenentwicklung?

Nutzen Sie HelvAddress, um Adressen vor Fakturierung, Druck und Zahlungsvorgängen zu validieren – auf in der Schweiz gehosteter Infrastruktur und mit einem entwicklerfreundlichen API-Vertrag.

API-Dokumentation lesen Kontakt aufnehmen Normalisierung erkunden