Magic Heidi API QR-facture suisse : préparer l'intégration
Confirme la spécification et l'accès de test avant d'implémenter les requêtes. La validation du QR et le contrôle de la facture restent nécessaires.
Tu développes des fonctions de facturation pour le marché suisse ? Distingue trois tâches : générer le PDF, créer la section de paiement Swiss QR et rapprocher les paiements. Cette page t'aide à définir les exigences et les tests de réception d'une éventuelle intégration.
Le délai de réalisation dépend de la spécification retenue, du modèle de données et des cas à tester. Aucun temps d'intégration standard n'est promis ici.
Confirmer le contrat API et les conditions d'accès
État au 1er novembre 2026. Cette page est une orientation technique, pas une spécification publique approuvée. Avant de commencer, demande le contrat API actuellement pris en charge, les conditions d'accès et un environnement de test expressément autorisé. Contacte Magic Heidi avec ton cas d'usage et le volume prévu.
Les anciennes versions de cette page et de l'article de blog présentaient des exemples de requêtes et de réponses contradictoires. Ils ne constituent pas une base fiable pour du code de production. Confirme notamment les noms de champs, le format des dates, la représentation des taux de TVA et la structure de la réponse. Un appel présent dans un autre logiciel ne prouve pas qu'un contrat public est pris en charge.
Cette page ne garantit ni endpoint public gratuit, ni méthode d'authentification, quota, tarif, SLA ou durée de validité des liens PDF. Sans environnement de test convenu, n'envoie aucune donnée réelle de client, de patient ou de compte bancaire à un endpoint.
Ce que la spécification doit définir
| Domaine | Points à confirmer avant de coder |
|---|---|
| Requête | Champs obligatoires, types, dates, devise et numéro de facture |
| TVA | Pourcentage ou valeur décimale, arrondis, prix HT/TTC et taux multiples |
| Adresse | Éléments séparés, pays et règles de validation |
| Compte et référence | Types d'IBAN admis, QRR/SCOR/NON, chiffres de contrôle et communication éventuelle |
| Réponse | Chemin JSON réel vers le PDF, statuts, erreurs et autorisation de téléchargement |
| Exploitation | Authentification, limites, délais, nouvelles tentatives et prévention des doublons |
| Données | Stockage, accès, suppression, validité des liens et archivage propre |
Tests de réception technique
- Utilise uniquement des appels de test convenus, non facturables, avec des données fictives.
- Compare les succès et les erreurs à la réponse réelle. N'invente ni noms de champs ni codes d'erreur.
- Télécharge le PDF et vérifie les totaux, les arrondis, la langue et les informations fiscales.
- Décode les données QR et contrôle le compte, la référence, la devise et les adresses selon les directives SIX actuelles.
- Teste un IBAN invalide, une combinaison compte-référence interdite, une adresse manquante et une devise non prise en charge. Un succès HTTP ne suffit pas à valider la facture.
- Avant d'ajouter des nouvelles tentatives, définis comment éviter une double génération ou des numéros de facture en double. Ne journalise pas les données personnelles complètes des factures.
Cas d'usage possibles
Un service de génération approuvé peut compléter un processus de facturation, une gestion de membres ou un traitement de commandes. Un PDF avec QR ne reçoit toutefois aucun paiement et ne prouve pas un encaissement. Le rapprochement exige des données bancaires adaptées et un processus d'attribution testé.
Comprendre QR-IBAN et IBAN classique
Le type de référence doit correspondre au compte utilisé.
Quand utiliser le QR-IBAN
Utilise un QR-IBAN si le processus de paiement convenu repose sur une référence QRR à 27 chiffres. Cette référence facilite l'attribution des paiements, mais le rapprochement nécessite aussi les données bancaires et le logiciel appropriés. Le PDF généré ne marque pas une facture comme payée.
Les caractères 5 à 9 d'un QR-IBAN correspondent à un IID compris entre 30000 et 31999. Vérifie l'IBAN fourni par l'établissement ; n'utilise pas un IBAN d'exemple inventé pour les tests. Les conditions d'obtention d'un QR-IBAN dépendent de ta banque.
Quand utiliser l'IBAN classique
Un IBAN classique CH ou LI peut être utilisé avec SCOR, une référence créancier ISO 11649 commençant par RF, ou NON, sans référence structurée. SCOR peut également faciliter un rapprochement ; celui-ci n'est pas réservé à QRR.
Compatibilité des références
- QR-IBAN → QRR, référence QR à 27 chiffres.
- IBAN classique CH/LI → SCOR ou NON.
Une référence QRR avec un IBAN classique n'est pas une combinaison admise. La manière dont le service signale cette erreur doit figurer dans la spécification approuvée ; aucun code d'erreur particulier n'est promis ici.
Section de paiement suisse et clients internationaux
La section Swiss QR utilise des coordonnées bancaires CH ou LI et les devises CHF ou EUR. Cela ne limite pas les pays de résidence des clients facturés. Pour une autre devise ou un compte non compatible, le document doit comporter un autre bloc de paiement adapté.
La QR-facture a remplacé les anciens bulletins de versement dès le 1er octobre 2022 ; elle n'est pas obligatoire sur chaque facture. Tiens les adresses sous forme structurée et consulte les directives SIX en vigueur ainsi que les dispositions transitoires. Un service de génération ne transforme pas automatiquement des données erronées en facture juridiquement correcte.
Prochaine étape
Demande la spécification prise en charge et un accès de test autorisé à hello@magicheidi.ch. Clarifie d'abord l'accès, la protection des données et la facturation du service. Tu pourras ensuite écrire un client dans ton langage et le valider avec des tests reproductibles.