Crea fattura SwissQR API

Cosa fa questo endpoint

PDF4me Crea fattura SwissQR genera svizzero QR ricevute di pagamento conformi alla normativa svizzera QR-standard di fatturazione (standard di pagamento svizzeri, SPS) attraverso un singolo REST chiama. Invia dettagli del creditore e del debitore finale, IBAN, importo, valuta, tipo di riferimento, lingua, stile del separatore e formato di output. Facoltativamente, includi un documento sorgente come Base64, ID blob, o URL sovrapporre lo slip a uno esistente PDF. IL API resi PDF, PNG, JPEG, O TIFF a seconda di tipo di formattazione.

Articoli correlati del blog

Non ci sono ancora post sul blog dedicati a questa funzionalità — in arrivo a breve.

Nel frattempo, dai un'occhiata al blog di PDF4me per trovare tutorial e procedure operative su tutte le piattaforme.

Visita il blog →

Autenticazione del tuo API Richiesta

Ogni PDF4me REST API la chiamata deve includere il tuo API chiave nel Authorization Intestazione. Crea o seleziona una chiave dalla dashboard dello sviluppatore e mantienila segreta.

Get your API Key

Punto finale

INVIARE/api/v2/CreateSwissQrBill

URL di Postmanhttps://api.pdf4me.com/api/v2/CreateSwissQrBill

Informazioni importanti da non perdere

Il formato IBAN svizzero è rigorosamente validato

Il creditore stavano andando deve iniziare con CH seguito da 19 cifre. Un numero non valido IBAN restituisce un errore.

Utilizzare il tipo di indirizzo strutturato (S) per la produzione

Impostato crAddressType E udAddressType A S quindi via, numero civico, codice postale e città vengono memorizzati separatamente. Questo formato è richiesto per la maggior parte delle riconciliazioni bancarie automatizzate svizzere. Utilizzare K (Combinato) solo quando non è possibile separare i componenti dell'indirizzo.

Abbina referenceType al tuo flusso di lavoro di riconciliazione

NON per pagamenti senza un riferimento strutturato. QRR per un riferimento numerico di 27 cifre sulle banconote svizzere nazionali. SCOR per ISO 11649 Referenze dei creditori. Includere riferimento nel corpo quando si utilizza QRR O SCOR.

REST API endpoint

Metodo: INVIARE
URL: https://api.pdf4me.com/api/v2/CreateSwissQrBill

Impostato IsAsync A VERO PascalCase) per 202 Accepted e sondare il Posizione URL con GET fino a quando non riceverai 200 e il file in JSON. Utilizzo falso per un sincrono 200 risposta.

configurazione della richiesta Postman

Collocamento	Valore
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).

Parametri

Sempre richiesto: stavano andando, crName, crAddressType, crStreetOrAddressLine1, crStreetOrAddressLine2, crPostalCode, crCity, quantità, valuta, udName, udAddressType, udStreetOrAddressLine1, udStreetOrAddressLine2, udPostalCode, udCity, tipo di riferimento, Lingua tipo, linea di separazione, tipo di formattazione, E IsAsync.

Condizionale: docContent E docName quando si sovrappone a un PDF; riferimento Quando tipo di riferimento È QRR O SCOR; Opzioni di paginazione E numero di pagina Quando tipo di formattazione È pdf.

Opzionale: messaggio non strutturato, informazioni di fatturazione, av1, av2, profili.

Parametro	Necessario	Si applica quando	Cosa fa	Esempio
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

Opzioni del tipo di indirizzo

Si applica a crAddressType E udAddressType.

S (strutturato)Consigliato per la riconciliazione automatizzata

Il sistema memorizza via, numero civico, codice postale e città in campi separati. Richiesto dalla maggior parte dei sistemi bancari svizzeri per la riconciliazione automatica.

K (Combinato)Due righe di indirizzo a forma libera

Memorizza l'indirizzo come due righe a formato libero combinate. Più semplice da compilare, ma meno compatibile con la riconciliazione automatica.

Opzioni della linea di separazione (seperatorLine)

LineaConForbici

Linea di taglio perforata con simbolo di forbici. Impostazione predefinita per le fatture svizzere stampate.

Linea tratteggiata

Linea di separazione tratteggiata tra la fattura e la ricevuta da staccare.

Linea solida

Linea di separazione continua senza simbolo di forbici.

Opzioni del tipo di riferimento

NONNessun riferimento strutturato

Predefinito per pagamenti semplici. Utilizzare messaggio non strutturato per una nota a forma libera invece di riferimento.

QRRCodice QR di 27 cifre

Bollette svizzere nazionali con PostFinance o banca svizzera IBANs. Devi inviare riferimento come una stringa numerica di 27 cifre.

SCORRiferimento del creditore ISO 11649

Transfrontaliero SEPA-abbinamento di stile. Invia riferimento In ISO 11649 formato (inizia con RF).

Formato di output (formatType) E PDF cercapersone

Quando tipo di formattazione È pdf, impostato Opzioni di paginazione per controllare dove QR è posizionato il foglio. Per l'output dell'immagine, omettere Opzioni di paginazione o impostalo su nulla.

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.

Campi di output

Campo	Tipo	Cosa contiene
docName	String	Output file name.
docContent	Base64	Generated file (PDF or image per formatType). Decode before saving or streaming.

Esempi di richieste

Esempio A: Autonomo QR fattura (nessun input) PDF)

Omettere docContent o inviare una stringa vuota per generare solo il QR ricevuta di pagamento.

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

Esempio B: Sovrapposizione QR su un esistente PDF Base64)

Sostituire docContent con il tuo PDF COME Base64 (NO dati: prefisso).

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

Esempio C: Copia-incolla valido 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
}

Payload di tipo di riferimento

Nessun riferimento (NON):

{ "referenceType": "NON" }

Codice QR (QRR):

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

Riferimento del creditore (SCOR, ISO 11649):

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

Frammenti di codice per formatType e pagingOptions

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

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

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

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

Esempi di codice

C# Sample

Java Sample

JavaScript Sample

Python Sample

n8n Sample

All API Samples

Esempi di integrazione

Modelli comuni di integrazione RESTTypical ways developers call Create SwissQR Bill.

Esportazione fattura ERP → Fattura in formato PDF con codice QR svizzero

1. Il tuo sistema ERP esporta i dati delle fatture e un file PDF.
2. Codificare il PDF in Base64 docContent.
3. campi di pagamento POST con tipo di riferimento QRR e un codice di 27 cifre riferimento.
4. decodificare docContent dalla risposta e salva o invia tramite e-mail il PDF della fattura QR.

Sovrapposizione autonoma a scorrimento o a gancio

1. Solo per una ricevuta a strappo, POSTARE con vuoto docContent E tipo di formattazione pdf o png.
2. Per le fatture provenienti da un webhook, codificare il PDF in Base64 docContent, impostato Opzioni di paginazione A scorso O costumee campi di pagamento POST.
3. Decodifica la risposta docContent e caricare i dati nell'archivio oggetti o allegarli a un'API di posta elettronica.

Domande frequenti

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.

Azioni correlate

Creare svizzero QR Conto (n8n)

Stesso backend con flusso di lavoro UI: Dati binari, URL, foglietti autonomi, tipi di formato e opzioni di impaginazione.

Leggi il codice SwissQR

Estrarre i dati di pagamento da PDFs che contengono già uno svizzero QR-conto.

API Tester

Prova l'endpoint in modo interattivo con il tuo API chiave e esempio PDF.

Stessa attività su altre piattaforme

Creare svizzero QR Fattura (Make)

Scenari visivi con lo stesso SPS-campi conformi e IBAN convalida.

Creare svizzero QR Conto (Zapier)

Grilletto svizzero QR fatturazione da SaaS applicazioni e webhook.

Creare svizzero QR Conto (Power Automate)

Microsoft 365 scorre con SharePoint, Outlook, E Dynamics integrazioni.

Creare svizzero QR Conto (n8n)

Crea un'installazione self-hosted o cloud n8n flussi di lavoro con lo stesso svizzero QR- Campi della fattura e opzioni di output.

Richiedi assistenza

Get Your API KeyAPI SamplesAPI TesterGetting Started