API-Dokumentation

Alle Tools dieser Website stehen als kostenlose JSON-API zur Verfügung. Kein API-Schlüssel, keine Anmeldung. CORS ist aktiviert, Aufrufe direkt aus dem Browser sind also möglich.

Basis-URL: https://swissinvoice.dev/api/v1
Rate-Limit: Anfragen sind pro IP-Adresse begrenzt: 60 pro Minute für die Validierung, 120 pro Minute für IBAN-Prüfung und Generierung. Darüber erhalten Sie HTTP 429 mit einem Retry-After-Header.
Sprache: Mit ?lang=de erhalten Sie die Fehlermeldungen auf Deutsch, mit ?lang=fr bzw. ?lang=it auf Französisch oder Italienisch. Standard ist Englisch.
Fehler: Prüf-Endpunkte antworten immer mit HTTP 200 und liefern valid: true/false sowie Listen von Fehlern und Warnungen. Jeder Befund enthält einen stabilen Code, das betroffene Feld, die Zeile im Inhalt (falls zutreffend) und eine verständliche Meldung. Fehlerhafte Anfragen erhalten HTTP 4xx mit einem error-Objekt.

QR-Rechnungsinhalt prüfen

POST/api/v1/qr-bill/validate

Senden Sie den rohen QR-Code-Text als text/plain (oder als JSON {"payload": "…"}).

curl

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

Antwort

{
  "valid": false,
  "errors": [
    {
      "code": "iban.checksum",
      "field": "account",
      "line": 4,
      "message": "Die Prüfziffern stimmen nicht. Wahrscheinlich enthält die IBAN einen Tippfehler."
    },
    {
      "code": "address.combined",
      "field": "creditor",
      "line": 5,
      "message": "Kombinierte Adressen (Typ K) werden seit dem 21. November 2025 nicht mehr akzeptiert. Verwenden Sie eine strukturierte Adresse (Typ S)."
    }
  ],
  "warnings": [
    {
      "code": "amount.decimals",
      "field": "amount",
      "line": 19,
      "params": {
        "value": "100.5"
      },
      "message": "Der Betrag «100.5» sollte genau zwei Dezimalstellen haben, z. B. 100.00."
    }
  ],
  "data": {
    "version": "0200",
    "account": "CH4431999123000889013",
    "…": "…"
  }
}

IBAN prüfen

GET/api/v1/iban?iban=…

Übergeben Sie die IBAN als Query-Parameter. Leerzeichen sind erlaubt.

curl

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

Antwort

{
  "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": []
}

QR-Rechnung erstellen

POST/api/v1/qr-bill

JSON senden, SVG (Standard) oder PDF zurückerhalten. Setzen Sie format auf pdf und paperSize auf a4 oder 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": "Bestellung vom 15. Juni 2026",
  "language": "de",
  "format": "pdf",
  "paperSize": "a4"
}' \
  -o qr-bill.pdf

Felder der Anfrage

creditor.account	string	IBAN oder QR-IBAN (CH/LI). Leerzeichen erlaubt.
creditor.name	string ≤70	Pflichtfeld.
creditor.street / buildingNumber	string ≤70 / ≤16	Optional.
creditor.postalCode / town	string ≤16 / ≤35	Pflichtfeld.
creditor.country	string	ISO 3166-1 Alpha-2, z. B. CH.
debtor	object	Optional. Gleiche Felder wie creditor, ohne account.
amount	number	Optional. 0.01–999999999.99, höchstens zwei Dezimalstellen.
currency	"CHF" \| "EUR"	Standard CHF.
reference	string	QR-Referenz (27 Ziffern) für QR-IBANs, sonst RF-Creditor-Reference oder leer.
message	string ≤140	Optionale unstrukturierte Mitteilung.
billInformation	string ≤140	Optionale strukturierte Rechnungsinformationen, z. B. Swico S1. Zusammen mit message max. 140.
language	"en" \| "de" \| "fr" \| "it" \| "rm"	Sprache des Zahlteils. Standard en.
format	"svg" \| "pdf"	Standard svg.
paperSize	"a4" \| "slip"	Nur PDF. Standard a4.

Lässt sich aus den Angaben keine gültige QR-Rechnung erstellen, antwortet der Endpoint mit HTTP 422. error.code ist invalid_input bei fehlerhaften Feldern oder invalid_qr_bill bei Verstössen gegen die QR-Rechnungs-Regeln; error.details listet die Probleme mit Code, Feld und Meldung.