SwissQR-Rechnung erstellen API

Was dieser Endpunkt bewirkt

PDF4me SwissQR-Rechnung erstellen generiert Schweizer QR Zahlungsbelege, die den Schweizer Standards entsprechen QR-Rechnungsstandard (Schweizer Zahlungsnormen, SPS) durch einen einzigen REST Anrufen. Senden. Angaben zum Gläubiger und zum letztendlichen Schuldner, IBANBetrag, Währung, Referenztyp, Sprache, Trennzeichenstil und AusgabeformatOptional kann ein Quelldokument hinzugefügt werden als Base64, Blob-ID oder URL um die Gleitfläche auf eine bestehende PDF. Der API Rückgaben PDF, PNG, JPEG, oder TIFF abhängig von formatTypeDie

Verwandte Blog-Beiträge

Zu dieser Funktion gibt es noch keinen Blogbeitrag – folgt in Kürze.

Schauen Sie sich in der Zwischenzeit im PDF4me-Blog Tutorials und Arbeitsabläufe für alle Plattformen an.

Besuchen Sie den Blog →

Authentifizierung Ihres API Anfrage

Jeder PDF4me REST API Der Anruf muss Ihre API Schlüssel im Authorization Kopfzeile. Erstellen oder wählen Sie einen Schlüssel im Entwickler-Dashboard aus und halten Sie ihn geheim.

Get your API Key

Endpunkt

POST/api/v2/CreateSwissQrBill

Postman-URLhttps://api.pdf4me.com/api/v2/CreateSwissQrBill

Wichtige Fakten, die Sie nicht verpassen sollten

Das Schweizer IBAN-Format wird streng validiert.

Der Gläubiger Sie gingen muss beginnen mit CH gefolgt von 19 Ziffern. Ungültig IBAN Gibt einen Fehler zurück.

Verwenden Sie für die Produktion den strukturierten Adresstyp (S).

Satz crAddressType Und udAddressType Zu S Straße, Hausnummer, Postleitzahl und Ort werden daher separat gespeichert. Dieses Layout ist für die meisten automatisierten Bankabstimmungen in der Schweiz erforderlich. K (Kombiniert) nur dann, wenn Sie die Adresskomponenten nicht aufteilen können.

Ordnen Sie den Referenztyp Ihrem Abstimmungsworkflow zu.

NICHT für Zahlungen ohne strukturierten Referenzcode. QRR für eine 27-stellige numerische Referenz auf Schweizer Inlandsrechnungen. PUNKTZAHL für ISO 11649 Gläubigerreferenzen. Einschließen Referenz im Körper bei Verwendung QRR oder SCORDie

REST API Endpunkt

Verfahren: POST
URL: https://api.pdf4me.com/api/v2/CreateSwissQrBill

Satz IstAsynchron Zu WAHR (PascalCase) für 202 Accepted und befragen Sie die Standort URL mit GET bis Sie erhalten 200 und die Datei in JSON. Verwenden FALSCH für eine synchrone 200 Antwort.

Postman-Anfrage einrichten

Einstellung	Wert
Method	POST
URL	https://api.pdf4me.com/api/v2/CreateSwissQrBill
Headers	Content-Type: application/json
Authorization	Basic Auth with your API key, or header Authorization: Basic YOUR_API_KEY
Async	If the response is 202, poll the URL in the Location header (GET) until you get 200 and the file bytes (or JSON with document fields, depending on API version).

Parameter

Immer erforderlich: Sie gingen, crName, crAddressType, crStreetOrAddressLine1, crStreetOrAddressLine2, Postleitzahl, crCity, Menge, Währung, udName, udAddressType, udStreetOrAddressLine1, udStreetOrAddressLine2, Postleitzahl, udCity, Referenztyp, Sprachtyp, Trennlinie, formatType, Und IstAsynchronDie

Bedingt: docContent Und docName beim Überlagern einer PDF-Datei; Referenz Wann Referenztyp Ist QRR oder PUNKTZAHL; Paging-Optionen Und Seitenzahl Wann formatType Ist PDFDie

Optional: unstrukturierte Nachricht, Abrechnungsinformationen, av1, av2, ProfileDie

Parameter	Erforderlich	Gilt, wenn	Was es tut	Beispiel
docContent	Conditional	Overlay on existing PDF	Omit or empty string = standalone QR slip only. Otherwise Base64 PDF/image bytes (no data: prefix), blob id from POST /api/v2/UploadBlob, or HTTPS URL to the source file.	""
docName	Conditional	With docContent	File name for input/output context. Omit or empty when no source document.	invoice.pdf
iban	Yes	Every request	Creditor Swiss IBAN.	CH0200700110003765824
crName	Yes	Every request	Creditor name or company as registered with the bank.	Test AG
crAddressType	Yes	Every request	S = structured (street + building) or K = combined address lines.	S
crStreetOrAddressLine1	Yes	Every request	If S: street name (max ~70 chars). If K: first address line.	Test Strasse
crStreetOrAddressLine2	Yes	Every request	If S: house number (max ~16). If K: second address line.	1
crPostalCode	Yes	Every request	Creditor postal code (max ~16).	8000
crCity	Yes	Every request	Creditor city (max ~35).	Zurich
amount	Yes	Every request	Payment amount without leading zeros (string). Example: "1000" = 1000.00.	1000
currency	Yes	Every request	CHF or EUR.	CHF
udName	Yes	Every request	Ultimate debtor name or company (required by API; may be empty strings if unused).	Test Debt AG
udAddressType	Yes	Every request	S or K; same rules as crAddressType.	S
udStreetOrAddressLine1	Yes	Every request	Debtor street or address line 1.	Test Deb Strasse
udStreetOrAddressLine2	Yes	Every request	Debtor street number or address line 2.	2
udPostalCode	Yes	Every request	Debtor postal code.	8000
udCity	Yes	Every request	Debtor city.	Zurich
referenceType	Yes	Every request	NON = no reference, QRR = QR reference, SCOR = creditor reference.	NON
reference	Conditional	referenceType = QRR or SCOR	Required for QRR or SCOR; max 27 characters. Omit for NON.	21000000000313947143000017
languageType	Yes	Every request	English, German, French, or Italian.	English
seperatorLine	Yes	Every request	API spelling is seperatorLine (one a). LineWithScissor, DottedLine, or SolidLine.	LineWithScissor
formatType	Yes	Every request	Output format: pdf, png, jpeg, tiff, or null (default PDF behavior).	pdf
pagingOptions	Conditional	formatType = pdf	first, last, AddPageAtEnd, or custom. Omit or null for non-PDF formats.	first
pageNumber	Conditional	pagingOptions = custom	Integer >= 1; single page index when pagingOptions is custom.	1
unstructuredMessage	No	Optional	Free-form payment note. Max 140 characters.	Thank you for your business
billingInfo	No	Optional	Customer billing information.	Invoice for services rendered
av1	No	Optional	Alternative scheme parameter 1.
av2	No	Optional	Alternative scheme parameter 2.
profiles	No	Optional	Custom API profile JSON string. See API documentation for profile options.	{ "someOption": true }
IsAsync	Yes	Every request	PascalCase IsAsync. true = HTTP 202 and poll Location. false = synchronous HTTP 200.	true

Optionen für Adresstypen

Gilt für crAddressType Und udAddressTypeDie

S (Strukturiert)Empfohlen für den automatisierten Abgleich

Speichert Straße, Hausnummer, Postleitzahl und Ort in separaten Feldern. Wird von den meisten Schweizer Bankensystemen für den automatisierten Abgleich benötigt.

K (Kombiniert)Zwei frei gestaltbare Adresszeilen

Speichert die Adresse als zwei kombinierte Freitextzeilen. Einfacher zu befüllen, aber weniger kompatibel mit automatisiertem Abgleich.

Optionen für Trennlinien (seperatorLine)

LinieMitSchere

Perforierte Schnittlinie mit Scheren-Symbolen. Standard für gedruckte Schweizer Rechnungen.

Gepunktete Linie

Gepunktete Trennlinie zwischen Rechnung und Abreißabschnitt.

Durchgezogene Linie

Durchgezogene Trennlinie ohne Scheren-Symbole.

Optionen für Referenztypen

NICHTKeine strukturierte Referenz

Standardeinstellung für einfache Zahlungen. Verwenden unstrukturierte Nachricht für eine freie Notiz anstelle von ReferenzDie

QRR27-stellige QR-Referenz

Schweizer Inlandsrechnungen mit PostFinance oder Schweizer Bank IBANsSie müssen senden Referenz als 27-stellige Zahlenfolge.

PUNKTZAHLISO 11649 Gläubigerreferenz

Grenzüberschreitend SEPA-Stilübereinstimmung. Senden Referenz In ISO 11649 Format (beginnt mit RF).

Ausgabeformat (formatType) Und PDF Paging

Wann formatType Ist PDF, Satz Paging-Optionen um zu kontrollieren, wo die QR Der Zettel wird platziert. Für die Bildausgabe weglassen. Paging-Optionen oder stellen Sie es ein auf nullDie

formatType: pdfpagingOptions: first

Place QR slip on the first page.

formatType: pdfpagingOptions: last

Place QR slip on the last page.

formatType: pdfpagingOptions: AddPageAtEnd

Append a new page with the QR slip at the end.

formatType: pdfpagingOptions: custom + pageNumber

Place on a specific page (e.g. pageNumber: 1).

formatType: png | jpeg | tiffpagingOptions: null

No paging; returns image bytes.

Ausgabefelder

Feld	Typ	Was es enthält
docName	String	Output file name.
docContent	Base64	Generated file (PDF or image per formatType). Decode before saving or streaming.

Beispiele anfordern

Beispiel A: Standalone QR Rechnung (keine Eingabe) PDF)

Auslassen docContent oder senden Sie eine leere Zeichenkette, um nur die zu generieren QR Zahlungsbeleg.

{
  "docContent": "",
  "docName": "",
  "iban": "CH0200700110003765824",
  "crName": "Test AG",
  "crAddressType": "S",
  "crStreetOrAddressLine1": "Test Strasse",
  "crStreetOrAddressLine2": "1",
  "crPostalCode": "8000",
  "crCity": "Zurich",
  "amount": "1000",
  "currency": "CHF",
  "udName": "Test Debt AG",
  "udAddressType": "S",
  "udStreetOrAddressLine1": "Test Deb Strasse",
  "udStreetOrAddressLine2": "2",
  "udPostalCode": "8000",
  "udCity": "Zurich",
  "referenceType": "NON",
  "languageType": "English",
  "seperatorLine": "LineWithScissor",
  "formatType": "pdf",
  "pagingOptions": "first",
  "IsAsync": true
}

Beispiel B: Überlagerung QR auf einem bestehenden PDF (Base64)

Ersetzen docContent mit Ihrem PDF als Base64 (NEIN Daten: Präfix).

{
  "docContent": "JVBERi0xLjQKJeLjz9MKMy...",
  "docName": "invoice.pdf",
  "iban": "CH0200700110003765824",
  "crName": "Test AG",
  "crAddressType": "S",
  "crStreetOrAddressLine1": "Test Strasse",
  "crStreetOrAddressLine2": "1",
  "crPostalCode": "8000",
  "crCity": "Zurich",
  "amount": "1000",
  "currency": "CHF",
  "udName": "Test Debt AG",
  "udAddressType": "S",
  "udStreetOrAddressLine1": "Test Deb Strasse",
  "udStreetOrAddressLine2": "2",
  "udPostalCode": "8000",
  "udCity": "Zurich",
  "referenceType": "NON",
  "languageType": "English",
  "seperatorLine": "LineWithScissor",
  "formatType": "pdf",
  "pagingOptions": "custom",
  "pageNumber": 1,
  "IsAsync": true
}

Beispiel C: Gültiges Kopieren und Einfügen JSON

{
  "docContent": "",
  "docName": "",
  "iban": "CH0200700110003765824",
  "crName": "Test AG",
  "crAddressType": "S",
  "crStreetOrAddressLine1": "Test Strasse",
  "crStreetOrAddressLine2": "1",
  "crPostalCode": "8000",
  "crCity": "Zurich",
  "amount": "1000",
  "currency": "CHF",
  "udName": "Test Debt AG",
  "udAddressType": "S",
  "udStreetOrAddressLine1": "Test Deb Strasse",
  "udStreetOrAddressLine2": "2",
  "udPostalCode": "8000",
  "udCity": "Zurich",
  "referenceType": "NON",
  "languageType": "English",
  "seperatorLine": "LineWithScissor",
  "formatType": "pdf",
  "pagingOptions": "first",
  "IsAsync": true
}

Referenztyp-Nutzdaten

Keine Referenz (NON):

{ "referenceType": "NON" }

QR-Referenz (QRR):

{
  "referenceType": "QRR",
  "reference": "21000000000313947143000017"
}

Gläubigerreferenz (SCOR, ISO 11649):

{
  "referenceType": "SCOR",
  "reference": "RF18539007547034"
}

formatType- und pagingOptions-Snippets

{ "formatType": "png", "pagingOptions": null }

{ "formatType": "pdf", "pagingOptions": "last" }

{ "formatType": "pdf", "pagingOptions": "AddPageAtEnd" }

{ "formatType": "pdf", "pagingOptions": "custom", "pageNumber": 1 }

Codebeispiele

C# Sample

Java Sample

JavaScript Sample

Python Sample

n8n Sample

All API Samples

Integrationsbeispiele

Gängige REST-IntegrationsmusterTypical ways developers call Create SwissQR Bill.

ERP-Rechnungsexport → Schweizer QR-Rechnung (PDF)

1. Ihr ERP-System exportiert Rechnungsdaten und eine PDF-Datei.
2. Base64-kodieren Sie das PDF in docContentDie
3. POST-Zahlungsfelder mit Referenztyp QRR und eine 27-stellige ReferenzDie
4. Entschlüsseln docContent Aus der Antwort wird die QR-Rechnung als PDF gespeichert oder per E-Mail versendet.

Eigenständige Slip- oder Webhook-Überlagerung

1. Nur für einen Abreißabschnitt, POST mit leerem docContent Und formatType pdf oder png.
2. Bei Rechnungen aus einem Webhook muss das PDF Base64-kodiert werden in docContent, Satz Paging-Optionen Zu zuletzt oder Brauchund POST-Zahlungsfelder.
3. Entschlüsseln Sie die Antwort docContent und in einen Objektspeicher hochladen oder an eine E-Mail-API anhängen.

Häufig gestellte Fragen

Which currencies does the API accept?+

Set currency to CHF for domestic Swiss payments or EUR for cross-border transactions. The amount and currency must match what you print on the slip.

What is the difference between NON, QRR, and SCOR?+

They are values for the referenceType field. NON means no structured reference is encoded in the QR code; you can still add unstructuredMessage such as an invoice number. QRR is for domestic Swiss QR-bills: send reference as a 27-digit numeric string when referenceType is QRR. SCOR follows ISO 11649 (starts with RF); send reference when referenceType is SCOR.

Should I use Structured (S) or Combined (K) addresses?+

Use S (Structured) for almost all production integrations. Set crAddressType to S, put the street in crStreetOrAddressLine1, the house number in crStreetOrAddressLine2, and fill crPostalCode and crCity. Use the same pattern for the ultimate debtor with udAddressType and udStreetOrAddressLine fields. Use K (Combined) only when you cannot split the address into separate fields.

Is docContent required?+

No. Omit docContent or send an empty string to generate a standalone QR payment slip. To embed the slip on an invoice, send docContent as Base64 PDF bytes, a blob id from UploadBlob, or a direct HTTPS URL, and set docName when needed for context.

What do formatType and pagingOptions control?+

formatType sets the output: pdf, png, jpeg, or tiff. When formatType is pdf, pagingOptions chooses where the slip is placed: first page, last page, AddPageAtEnd, or custom with pageNumber. For image formats, omit pagingOptions or set it to null.

What does IsAsync do?+

IsAsync controls how the response is delivered. When IsAsync is false (or omitted in samples that use synchronous mode), a successful call returns HTTP 200 with docName and docContent in one JSON body. When IsAsync is true, the API returns HTTP 202 Accepted and a Location header with a poll URL. Send GET requests to that URL until you receive 200 with the same docName and docContent fields. Use async for large batches or slow networks; use sync for simple request-response scripts.

How do I test the API without writing code?+

Open the Create SwissQR Bill API Tester, paste your API key, then fill payment, creditor, and debtor fields, referenceType, languageType, seperatorLine, and IsAsync. Add docContent only when overlaying on a PDF. Use the parameter table on this page as a checklist.

Is the response binary or Base64?+

The response is always JSON, never a raw application/pdf stream. On success the body contains docName (output filename) and docContent (the full PDF encoded as a Base64 string). Decode docContent in your language (for example Buffer.from in Node.js, base64.b64decode in Python, Convert.FromBase64String in C#) before writing the file. Invalid IBAN, missing required fields, or malformed Base64 in docContent typically produce HTTP 400 with an error message in JSON.

What IBAN format is required?+

The iban field must be a valid Swiss creditor IBAN: CH followed by 19 digits (21 characters total), linked to a PostFinance or Swiss bank account. Invalid IBANs cause the request to fail.

Ähnliche Aktionen

Schweizer Fabrikaten QR Rechnung (n8n)

Gleiches Backend mit Workflow UIBinärdaten, URL, eigenständige Belege, Formattypen und Paging-Optionen.

SwissQR-Code lesen

Zahlungsdaten extrahieren aus PDFs die bereits eine Schweizer QR-Rechnung.

API Tester

Testen Sie den Endpunkt interaktiv mit Ihrem API Schlüssel und Beispiel PDFDie

Dieselbe Aufgabe auf anderen Plattformen

Schweizer Fabrikaten QR Rechnung (Herstellen)

Visuelle Szenarien mit dem gleichen SPS-konforme Felder und IBAN Validierung.

Schweizer Fabrikaten QR Rechnung (Zapier)

Trigger Swiss QR Rechnungsstellung von SaaS Apps und Webhooks.

Schweizer Fabrikaten QR Rechnung (Power Automate)

Microsoft 365 fließt mit SharePoint, Outlook, Und Dynamics Integrationen.

Schweizer Fabrikaten QR Rechnung (n8n)

Erstellen Sie eine selbstgehostete oder Cloud-Lösung. n8n Workflows mit denselben Schweizer QR-Rechnungsfelder und Ausgabeoptionen.

Hilfe erhalten

Get Your API KeyAPI SamplesAPI TesterGetting Started