Ce que fait cette feature

Pensé pour la facturation suisse, pas pour une simple validation générique

Les QR-factures suisses imposent des règles strictes. HelvAddress transforme ces contraintes en une API exploitable immédiatement par vos équipes.

Détection automatique du mode S ou K

Envoyez des champs structurés ou deux lignes libres. L'API déduit automatiquement si l'adresse doit être validée en mode structuré (S) ou combiné (K).

Validation complète de chaque champ

Contrôle les longueurs maximales, les champs requis, les caractères autorisés et les contraintes de format QR-facture avant la génération du document.

Contrôle de vrais NPA suisses

Les NPA ne sont pas seulement contrôlés en format. Ils sont vérifiés contre le répertoire officiel des localités postales suisses.

Violations structurées en retour

Retourne toujours HTTP 200 avec `valid` à true/false et une liste exploitable de violations par champ, code et message — idéal pour les formulaires et les workflows métier.

Conformité prête à l'emploi

Aligné explicitement sur le SIX Swiss Payments Standard v2.3

C'est la couche de validation dont les équipes facturation suisses ont besoin avant d'imprimer, d'exporter ou d'envoyer une QR-facture.

HelvAddress expose un endpoint dédié à la validation d'adresses QR-facture pour éviter de réimplémenter les règles SIX dans votre ERP, votre plateforme e-commerce ou votre stack de facturation.

Résultat : une conformité plus simple, moins d'exceptions de facturation et une mise en production plus rapide pour vos workflows de paiement suisses.

Ce que garantit le endpoint

Le contrat a été pensé pour s'intégrer simplement dans des formulaires, des APIs métier et des pipelines de génération documentaire.

Adresses suisses uniquement (`countryCode = CH`)
Les réponses fonctionnelles utilisent toujours HTTP 200 avec un body structuré
Quand l'adresse est valide, l'objet `formatted` est directement exploitable
Modes d'adresse

Compatible avec les deux styles d'adresse QR-facture

Que votre système stocke des adresses entièrement structurées ou encore des lignes libres historiques, le flux de validation s'adapte à votre modèle.

MODE S streetName · buildingNumber · postalCode · town
Mode S — adresses structurées

Utilisez des champs séparés lorsque votre système stocke déjà la rue, le numéro, le code postal et la localité indépendamment.

  • Idéal pour les ERP, CRM, moteurs de facturation et plateformes de données maîtres
  • Valide `streetName`, `buildingNumber`, `postalCode` et `town` champ par champ
  • Le meilleur choix pour remonter des erreurs précises dans des formulaires structurés
MODE K addressLine1 · addressLine2
Mode K — lignes d'adresse combinées

Utilisez deux lignes libres lorsque le système amont stocke encore l'adresse dans le format historique combiné des paiements suisses.

  • Bien adapté aux systèmes comptables legacy et aux adresses importées
  • Valide `addressLine1` et `addressLine2` contre les contraintes QR-facture
  • Permet d'ajouter des contrôles de conformité sans refondre d'abord votre modèle de données
Détection automatique du mode Si `addressLine1` ou `addressLine2` est présent, l'API valide la requête en mode K. Sinon, elle utilise automatiquement le mode S.
Ce qui est contrôlé

Les contrôles clés sont exécutés en une seule requête

Le endpoint répond à la vraie question métier : cette adresse peut-elle figurer sur une QR-facture suisse maintenant ?

1
Longueurs maximales

Applique les limites SIX comme 70 caractères pour le nom et la rue, 16 pour le code postal ou le numéro, et 35 pour la localité.

2
Jeu de caractères autorisé

Rejette les caractères interdits et les caractères de contrôle pour rester compatible avec les contraintes de génération des QR-factures suisses.

3
Règles sur le NPA suisse

Contrôle le format attendu des codes postaux suisses à 4 chiffres lorsque applicable et leur cohérence avec le pays demandé.

4
Correspondance avec le répertoire postal officiel

Confirme que le NPA existe dans les données officielles des localités postales suisses, et pas seulement qu'il ressemble à un code valide.

5
Formatage prêt à l'emploi

Quand l'adresse est valide, l'API renvoie un objet `formatted` nettoyé et prêt pour la génération de QR-facture.

Design de la réponse

Facile à brancher dans les formulaires, workflows et systèmes de facturation

Pas de logique d'exception complexe, pas d'ambiguïté. Votre application reçoit un résultat explicite à chaque appel.

Exemple de requête
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"
}
Réponse valide
{
  "valid": true,
  "mode": "S",
  "violations": [],
  "formatted": {
    "mode": "S",
    "name": "Max Muster AG",
    "streetName": "Bahnhofstrasse",
    "buildingNumber": "1",
    "postalCode": "8001",
    "town": "Zürich",
    "countryCode": "CH"
  }
}
Réponse invalide
{
  "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"
    }
  ]
}
Cela rend HelvAddress particulièrement utile pour la validation inline : le frontend peut mettre en évidence exactement le bon champ et le bon message sans gérer plusieurs branches HTTP d'erreur.
Valeur métier

Une meilleure façon de sécuriser vos workflows de paiement suisses

Toute entreprise suisse qui émet des factures ou gère des paiements a besoin d'une conformité d'adresse fiable avant de générer une QR-facture.

Équipes facturation et ERP

Validez les adresses créancier et débiteur avant la génération PDF, les exports de factures en lot ou les impressions.

Éditeurs de logiciels de facturation

Intégrez la conformité QR-facture suisse directement dans votre produit sans maintenir vous-même un moteur de règles ni une base de référence des NPA.

E-commerce et portails

Détectez plus tôt les problèmes d'adresse bloquants pour le paiement, avant même que la facture ne soit créée.

Besoin de conformité QR-facture suisse sans la développer vous-même ?

Utilisez HelvAddress pour valider les adresses avant la facturation, l'impression et les opérations de paiement — sur une infrastructure hébergée en Suisse et avec un contrat API simple à intégrer.

Lire la doc API Nous contacter Explorer la normalisation