Which currencies does Create SwissQR Bill accept?

Use CHF for domestic Swiss invoicing and EUR for cross-border payments. Set the currency field to match the invoice and the creditor IBAN.

What is the difference between reference types NON, QRR, and SCOR?

NON omits a structured reference in the QR code. QRR embeds a 27-digit numeric QR reference for domestic Swiss reconciliation with PostFinance or Swiss bank IBANs; you must send a valid reference in the request body. SCOR embeds an ISO 11649 creditor reference (RF prefix) for SEPA-style matching; you must send reference as well. Use unstructuredMessage for a free-form note when referenceType is NON.

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

Use S (Structured) for production. Map street to crStreetOrAddressLine1, house number to crStreetOrAddressLine2, plus crPostalCode and crCity (same pattern for ud fields). K (Combined) uses two free-form lines only. Structured is required for most automated Swiss bank reconciliation.

Is the API response binary or Base64?

The API returns JSON, not raw binary. On success you receive docName and docContent where docContent is the PDF as a Base64 string. Decode before saving. With IsAsync true you first get 202 Accepted and a Location header to poll until the same JSON is returned.

SwissQR Faturası Oluşturun API

Q: What IBAN format is required?

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

Bu uç noktanın işlevi

PDF4me SwissQR Faturası Oluşturun İsviçre'yi üretir QR İsviçre yönetmeliklerine uygun ödeme fişleri QR-fatura standardı (İsviçre Ödeme Standartları, SPS) tek bir REST Çağrı. Gönder Alacaklı ve nihai borçluya ait detaylar, IBANMiktar, para birimi, referans türü, dil, ayırıcı stili ve çıktı formatıİsteğe bağlı olarak kaynak belgeyi de ekleyebilirsiniz. Base64, blob kimliği veya URL mevcut olanın üzerine yeni bir kaplama yapmak PDF. O API iadeler PDF, PNG, JPEG, veya TIFF bağlı olarak formatType.

İlgili Blog Yazıları

Bu özellik için henüz bir blog yazısı yok — yakında yayınlanacak.

Bu arada, her platforma yönelik eğitimler ve iş akışları için PDF4me bloguna göz atın.

Blogu ziyaret edin →

Kimliğinizi Doğrulama API Rica etmek

Her PDF4me REST API Çağrınızda mutlaka sizin de bulunmanız gerekiyor. API anahtara Authorization Başlık. Geliştirici kontrol panelinden bir anahtar oluşturun veya seçin ve gizli tutun.

Get your API Key

Uç nokta

POSTALAMAK/api/v2/CreateSwissQrBill

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

Kaçırmamanız Gereken Önemli Bilgiler

İsviçre IBAN formatı titizlikle doğrulanmaktadır.

Alacaklı gidiyorlardı ile başlamalı CH 19 rakamla takip edilir. Geçersiz bir numara. IBAN Bir hata döndürüyor.

Üretim için Yapılandırılmış adres türünü (S) kullanın.

Ayarlamak crAdresTipi Ve udAdresTipi ile S Bu nedenle sokak, ev numarası, posta kodu ve şehir ayrı ayrı saklanır. Bu düzen, çoğu otomatik İsviçre banka mutabakatı için gereklidir. Kullanın K (Birleştirilmiş) yalnızca adres bileşenlerini ayıramadığınız durumlarda kullanılır.

Referans türünü mutabakat iş akışınızla eşleştirin.

OLMAYAN Yapılandırılmış referans içermeyen ödemeler için. QRR İsviçre iç piyasa banknotlarında kullanılan 27 haneli sayısal referans için. PUAN için ISO 11649 Alacaklı referansları. Dahil edin. referans vücutta kullanım sırasında QRR veya SCOR.

REST API uç nokta

Yöntem: POSTALAMAK
URL: https://api.pdf4me.com/api/v2/CreateSwissQrBill

Ayarlamak IsAsync ile doğru (PascalCase) için 202 Accepted ve anket yapın Konum URL ile GET alana kadar 200 ve dosyada JSON. Kullanmak YANLIŞ senkron için 200 cevap.

Postman isteği kurulumu

Ayar	Değer
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).

Parametreler

Her zaman gerekli: gidiyorlardı, crName, crAdresTipi, crSokakOrAdresSatırı1, crSokakOrAdresSatırı2, crPostalCode, crCity, miktar, para birimi, udName, udAdresTipi, udStreetOrAddressLine1, udStreetOrAddressLine2, udPostalCode, udCity, referansTürü, dilTürü, ayırıcıÇizgi, formatType, Ve IsAsync.

Şartlı: belge içeriği Ve belge adı PDF üzerine bindirildiğinde; referans Ne zaman referansTürü dır QRR veya PUAN; sayfalamaSeçenekleri Ve sayfa numarası Ne zaman formatType dır pdf.

İsteğe bağlı: yapılandırılmamışMesaj, fatura bilgileri, av1, av2, profiller.

Parametre	Gerekli	Şu durumlarda geçerlidir:	Ne işe yarar?	Örnek
`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`

Adres türü seçenekleri

Şunlar için geçerlidir: crAdresTipi Ve udAdresTipi.

S (Yapılandırılmış)Otomatik mutabakat için önerilir.

Mağaza, sokak adresini, ev numarasını, posta kodunu ve şehri ayrı alanlarda belirtmelidir. Bu bilgiler, çoğu İsviçre bankacılık sisteminde otomatik mutabakat için gereklidir.

K (Birleşik)İki adet serbest biçimli adres satırı

Adresi iki birleştirilmiş serbest biçimli satır olarak saklar. Doldurulması daha kolaydır ancak otomatik mutabakatla daha az uyumludur.

Ayırıcı çizgi seçenekleri (`seperatorLine`)

Makasla Çizgi

Makas sembolleriyle delikli kesim çizgisi. Basılı İsviçre faturaları için varsayılan ayar.

Noktalı Çizgi

Fatura ile fiş arasında noktalı ayırıcı çizgi.

Düz Çizgi

Makas sembolü bulunmayan düz ayırıcı çizgi.

Referans türü seçenekleri

OLMAYANYapılandırılmış referans yok

Basit ödemeler için varsayılan ayar. Kullanın yapılandırılmamışMesaj serbest biçimli bir not yerine referans.

QRR27 haneli QR referansı

İsviçre iç piyasası faturaları ile PostFinance veya İsviçre bankası IBANsGöndermeniz gerekiyor. referans 27 haneli sayısal bir dizi olarak.

PUANISO 11649 alacaklı referansı

Sınır ötesi SEPA-stil eşleştirme. Gönder referans içinde ISO 11649 format (ile başlar) RF).

Çıktı formatı (`formatType`) Ve PDF sayfalama

Ne zaman formatType dır pdf, ayarlamak sayfalamaSeçenekleri kontrol etmek için QR Fiş yerleştirildi. Görüntü çıktısı için, atlayın. sayfalamaSeçenekleri veya şunu ayarlayın hükümsüz.

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.

Çıkış alanları

Alan	Tip	İçeriğinde neler var?
`docName`	String	Output file name.
`docContent`	Base64	Generated file (PDF or image per formatType). Decode before saving or streaming.

Örnekler isteyin

Örnek A: Bağımsız QR fatura (giriş yok) PDF)

Atla belge içeriği veya yalnızca şunu oluşturmak için boş bir dize gönderin QR Ödeme fişi.

{
  "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
}

Örnek B: Üst Üste Bindirme QR mevcut bir PDF (Base64)

Yer değiştirmek belge içeriği sizinle PDF gibi Base64 (HAYIR veri: önek).

{
  "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
}

Örnek C: Kopyala-yapıştır geçerli 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
}

Referans tipi yükler

Referans yok (DEĞİL):

{ "referenceType": "NON" }

QR referansı (QRR):

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

Alacaklı referansı (SCOR, ISO 11649):

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

formatType ve pagingOptions kod parçacıkları

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

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

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

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

Kod örnekleri

Entegrasyon örnekleri

Yaygın REST entegrasyon kalıplarıTypical ways developers call Create SwissQR Bill.

ERP fatura dışa aktarımı → İsviçre QR fatura PDF

Kurumsal kaynak planlama (ERP) sisteminiz fatura verilerini ve bir PDF dosyasını dışa aktarır.
PDF dosyasını Base64 kodlamasıyla dönüştürün. belge içeriği.
POST ödeme alanları ile referansTürü QRR ve 27 haneli referans.
Kodu çöz belge içeriği Yanıtı inceleyin ve QR kodlu fatura PDF dosyasını kaydedin veya e-posta ile gönderin.

Bağımsız kaydırma veya web kancası kaplaması

Sadece yırtılabilir fiş için, boş olarak POST edin. belge içeriği Ve formatType PDF veya PNG.
Webhook üzerinden gelen faturalar için PDF dosyasını Base64 kodlamasıyla dönüştürün. belge içeriği, ayarlamak sayfalamaSeçenekleri ile son veya gelenekve POST ödeme alanları.
Yanıtı çözümleyin belge içeriği ve nesne depolama alanına yükleyin veya bir e-posta API'sine ekleyin.

Sıkça Sorulan Sorular

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.