Cosa fa questa funzionalità

Pensata per la fatturazione svizzera, non per una semplice validazione generica

Le QR-fatture svizzere impongono regole rigorose sugli indirizzi. HelvAddress trasforma queste regole in un'API pronta per la produzione.

Rileva automaticamente il modo S o K

Inviate campi strutturati o due righe libere. L'API deduce automaticamente se validare l'indirizzo in modalità strutturata (S) o combinata (K).

Valida ogni singolo campo

Controlla lunghezze massime, campi obbligatori, caratteri consentiti e vincoli di formato QR-fattura prima della generazione del documento.

Controlla NPA svizzeri reali

I codici postali non vengono controllati solo come formato. Sono verificati rispetto al repertorio ufficiale delle località postali svizzere.

Restituisce violazioni strutturate

Restituisce sempre HTTP 200 con `valid` true/false e una lista chiara di violazioni per campo, codice e messaggio — ideale per form e workflow business.

Conformità pronta all'uso

Allineata esplicitamente al SIX Swiss Payments Standard v2.3

È il layer di validazione che i team di fatturazione svizzeri devono avere prima di stampare, esportare o inviare una QR-fattura.

HelvAddress espone un endpoint dedicato alla validazione di indirizzi per QR-fattura, così non dovete reimplementare le regole SIX nel vostro ERP, e-commerce o stack di billing.

Il risultato è una conformità più semplice, meno eccezioni di fatturazione e una strada più veloce verso la produzione per i workflow di pagamento svizzeri.

Cosa garantisce il endpoint

Il contratto è stato progettato per integrarsi facilmente in form, API applicative e pipeline di generazione documenti.

Solo indirizzi svizzeri (`countryCode = CH`)
Le risposte funzionali usano sempre HTTP 200 con body strutturato
Quando valido, l'oggetto `formatted` è immediatamente utilizzabile
Modalità di indirizzo

Supporta entrambi gli stili di indirizzo della QR-fattura

Che il vostro sistema memorizzi indirizzi completamente strutturati o ancora righe libere legacy, il flusso di validazione si adatta al vostro modello dati.

MODE S streetName · buildingNumber · postalCode · town
Modalità S — indirizzi strutturati

Usate campi separati quando il sistema memorizza già via, numero civico, codice postale e località in modo indipendente.

  • Ideale per ERP, CRM, motori di billing e piattaforme di master data
  • Valida `streetName`, `buildingNumber`, `postalCode` e `town` campo per campo
  • Perfetto quando volete feedback precisi dentro form strutturati
MODE K addressLine1 · addressLine2
Modalità K — righe di indirizzo combinate

Usate due righe libere quando il sistema a monte conserva ancora gli indirizzi nel formato storico combinato dei pagamenti svizzeri.

  • Adatta a sistemi contabili legacy e dati di indirizzo importati
  • Valida `addressLine1` e `addressLine2` contro i vincoli della QR-fattura
  • Permette di aggiungere controlli di conformità senza riprogettare subito il modello dati
Rilevamento automatico della modalità Se `addressLine1` o `addressLine2` è presente, l'API valida la richiesta in modalità K. Altrimenti usa automaticamente la modalità S.
Cosa viene controllato

I controlli chiave avvengono in una sola richiesta

L'endpoint è progettato per rispondere alla vera domanda business: questo indirizzo può comparire ora su una QR-fattura svizzera?

1
Lunghezze dei campi

Applica i limiti massimi SIX come 70 caratteri per nome e via, 16 per codice postale o numero civico e 35 per la località.

2
Set di caratteri consentito

Rifiuta caratteri non ammessi e caratteri di controllo per mantenere la compatibilità con i vincoli di generazione della QR-fattura svizzera.

3
Regole sul NPA svizzero

Controlla che i codici postali svizzeri abbiano, dove applicabile, il formato atteso a 4 cifre e siano coerenti con il paese richiesto.

4
Confronto con il repertorio postale ufficiale

Conferma che il codice postale esista nel repertorio ufficiale delle località postali svizzere, non solo che sembri formalmente corretto.

5
Formattazione pronta all'uso

Quando l'indirizzo è valido, l'API restituisce un oggetto `formatted` pulito e pronto per l'uso in QR-fattura.

Struttura della risposta

Facile da integrare in form, workflow e sistemi di fatturazione

Niente flussi pieni di eccezioni, niente ambiguità. La vostra applicazione riceve sempre un risultato esplicito.

Esempio di richiesta
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"
}
Risposta valida
{
  "valid": true,
  "mode": "S",
  "violations": [],
  "formatted": {
    "mode": "S",
    "name": "Max Muster AG",
    "streetName": "Bahnhofstrasse",
    "buildingNumber": "1",
    "postalCode": "8001",
    "town": "Zürich",
    "countryCode": "CH"
  }
}
Risposta non valida
{
  "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"
    }
  ]
}
Questo rende HelvAddress particolarmente utile per la validazione inline: il frontend può evidenziare esattamente il campo corretto e il messaggio giusto senza gestire più rami HTTP di errore.
Valore business

Un modo migliore per mettere in sicurezza i workflow di pagamento svizzeri

Qualsiasi azienda svizzera che emette fatture o gestisce pagamenti ha bisogno di una conformità affidabile degli indirizzi prima di generare una QR-fattura.

Team fatturazione ed ERP

Convalidate gli indirizzi di creditore e debitore prima della generazione PDF, degli export massivi di fatture o delle operazioni di stampa.

Vendor di software di fatturazione

Integrate la conformità svizzera per QR-fattura direttamente nel vostro prodotto senza mantenere un motore di regole o dati di riferimento NPA interni.

E-commerce e portali

Intercettate prima i problemi di indirizzo che possono bloccare il pagamento, prima ancora che la fattura venga creata.

Vi serve la conformità QR-fattura svizzera senza svilupparla internamente?

Usate HelvAddress per validare gli indirizzi prima di fatturazione, stampa e operazioni di pagamento — su infrastruttura ospitata in Svizzera e con un contratto API semplice da integrare.

Leggi la doc API Contattaci Esplora la normalizzazione