Documentation de l'API

Tous les outils de ce site sont disponibles sous forme d'API JSON gratuite. Sans clé API, sans inscription. CORS est activé : vous pouvez l'appeler depuis le navigateur.

URL de base: https://swissinvoice.dev/api/v1
Limite de requêtes: Les requêtes sont limitées par adresse IP : 60 par minute pour la validation, 120 par minute pour la vérification IBAN et la génération. Au-delà, vous recevez une réponse HTTP 429 avec un en-tête Retry-After.
Langue: Ajoutez ?lang=fr pour obtenir les messages d'erreur en français (ou ?lang=de, ?lang=it pour l'allemand ou l'italien). Par défaut, les messages sont en anglais.
Erreurs: Les endpoints de validation renvoient toujours HTTP 200 avec valid: true/false et des listes d'erreurs et d'avertissements. Chaque problème comporte un code stable, le champ concerné, la ligne dans le contenu (le cas échéant) et un message lisible. Les requêtes mal formées renvoient HTTP 4xx avec un objet error.

Valider le contenu d'une QR-facture

POST/api/v1/qr-bill/validate

Envoyez le texte brut du code QR en text/plain (ou en JSON {"payload": "…"}).

curl

curl -X POST "https://swissinvoice.dev/api/v1/qr-bill/validate?lang=fr" \
  -H "Content-Type: text/plain" \
  --data-binary @payload.txt

Réponse

{
  "valid": false,
  "errors": [
    {
      "code": "iban.checksum",
      "field": "account",
      "line": 4,
      "message": "Les chiffres de contrôle ne correspondent pas. L'IBAN contient probablement une faute de frappe."
    },
    {
      "code": "address.combined",
      "field": "creditor",
      "line": 5,
      "message": "Les adresses combinées (type K) ne sont plus acceptées depuis le 21 novembre 2025. Utilisez une adresse structurée (type S)."
    }
  ],
  "warnings": [
    {
      "code": "amount.decimals",
      "field": "amount",
      "line": 19,
      "params": {
        "value": "100.5"
      },
      "message": "Le montant « 100.5 » devrait comporter exactement deux décimales, p. ex. 100.00."
    }
  ],
  "data": {
    "version": "0200",
    "account": "CH4431999123000889013",
    "…": "…"
  }
}

Vérifier un IBAN

GET/api/v1/iban?iban=…

Passez l'IBAN en paramètre de requête. Les espaces sont autorisés.

curl

curl "https://swissinvoice.dev/api/v1/iban?iban=CH0430000001234567890"

Réponse

{
  "valid": true,
  "input": "CH0430000001234567890",
  "iban": "CH0430000001234567890",
  "formatted": "CH04 3000 0001 2345 6789 0",
  "country": "CH",
  "swiss": {
    "iid": "30000",
    "isQrIban": true,
    "referenceTypes": [
      "QRR"
    ],
    "bank": {
      "iid": "30000",
      "name": "PostFinance AG",
      "town": "Bern",
      "bic": "POFICHBEXXX"
    }
  },
  "errors": [],
  "warnings": []
}

Générer une QR-facture

POST/api/v1/qr-bill

Envoyez du JSON, recevez un SVG (par défaut) ou un PDF. Définissez format sur pdf et paperSize sur a4 ou slip.

curl

curl -X POST https://swissinvoice.dev/api/v1/qr-bill \
  -H "Content-Type: application/json" \
  -d '{
  "creditor": {
    "account": "CH04 3000 0001 2345 6789 0",
    "name": "Robert Schneider AG",
    "street": "Rue du Lac",
    "buildingNumber": "1268",
    "postalCode": "2501",
    "town": "Biel",
    "country": "CH"
  },
  "debtor": {
    "name": "Pia-Maria Rutschmann-Schnyder",
    "street": "Grosse Marktgasse",
    "buildingNumber": "28",
    "postalCode": "9400",
    "town": "Rorschach",
    "country": "CH"
  },
  "amount": 1949.75,
  "currency": "CHF",
  "reference": "210000000003139471430009017",
  "message": "Commande du 15 juin 2026",
  "language": "fr",
  "format": "pdf",
  "paperSize": "a4"
}' \
  -o qr-bill.pdf

Champs de la requête

creditor.account	string	IBAN ou QR-IBAN (CH/LI). Espaces autorisés.
creditor.name	string ≤70	Obligatoire.
creditor.street / buildingNumber	string ≤70 / ≤16	Facultatif.
creditor.postalCode / town	string ≤16 / ≤35	Obligatoire.
creditor.country	string	ISO 3166-1 alpha-2, p. ex. CH.
debtor	object	Facultatif. Mêmes champs que creditor, sans account.
amount	number	Facultatif. 0.01–999999999.99, deux décimales au maximum.
currency	"CHF" \| "EUR"	CHF par défaut.
reference	string	Référence QR (27 chiffres) pour les QR-IBAN, sinon référence créancier RF ou vide.
message	string ≤140	Communication non structurée facultative.
billInformation	string ≤140	Informations de facture structurées facultatives, p. ex. Swico S1. Avec message, 140 caractères max.
language	"en" \| "de" \| "fr" \| "it" \| "rm"	Langue de la section paiement. en par défaut.
format	"svg" \| "pdf"	svg par défaut.
paperSize	"a4" \| "slip"	PDF uniquement. a4 par défaut.

Si aucune QR-facture valable ne peut être créée à partir des données, l'endpoint renvoie HTTP 422. error.code vaut invalid_input pour des champs mal formés ou invalid_qr_bill en cas de violation des règles QR-facture ; error.details liste les problèmes avec code, champ et message.