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.

Criar fatura SwissQR 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.

O que este endpoint faz

PDF4me Criar fatura SwissQR gera suíço QR Comprovantes de pagamento que estejam em conformidade com a legislação suíça. QR-padrão de fatura (Padrões de Pagamento Suíços, SPS) através de um único REST ligar. Enviar Detalhes do credor e do devedor final, IBAN, valor, moeda, tipo de referência, idioma, estilo do separador e formato de saídaOpcionalmente, inclua um documento de origem como Base64, blob id, ou URL sobrepor o deslizamento a um existente PDF. O API retornos PDF, PNG, JPEG, ou TIFF dependendo de tipo de formato.

Autenticando seu API Solicitar

Todo PDF4me REST API A chamada deve incluir o seu API chave no Authorization Crie ou selecione uma chave no painel do desenvolvedor e mantenha-a em segredo.

Get your API Key

Ponto final

PUBLICAR/api/v2/CriarFaturaSuíçaQr

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

Fatos importantes que você não deve perder

O formato IBAN suíço é rigorosamente validado.

O credor eles iam deve começar com CH seguido por 19 dígitos. Um valor inválido. IBAN Retorna um erro.

Use o tipo de endereço estruturado (S) para produção.

Definir crAddressType e udAddressType para S Assim, rua, número da casa, código postal e cidade são armazenados separadamente. Este formato é necessário para a maioria das conciliações bancárias automatizadas na Suíça. K (Combinado) somente quando não for possível dividir os componentes do endereço.

Associe o referenceType ao seu fluxo de trabalho de reconciliação.

NÃO para pagamentos sem referência estruturada. QRR para uma referência numérica de 27 dígitos em faturas domésticas suíças. PONTUAÇÃO para ISO 11649 Referências de credores. Inclua. referência no corpo ao usar QRR ou SCOR.

REST API ponto final

Método: PUBLICAR
URL: https://api.pdf4me.com/api/v2/CreateSwissQrBill

Definir É assíncrono para verdadeiro (PascalCase) para 202 Accepted e pesquisar o Localização URL com GET até você receber 200 e o arquivo em JSON. Usar falso para um síncrono 200 resposta.

Configuração de solicitação do Postman

Contexto	Valor
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).

Parâmetros

Sempre necessário: eles iam, crName, crAddressType, crStreetOrAddressLine1, crStreetOrAddressLine2, crCódigoPostal, crCity, quantia, moeda, udName, udAddressType, udStreetOrAddressLine1, udStreetOrAddressLine2, udPostalCode, udCity, tipo de referência, tipo de idioma, linha separadora, tipo de formato, e É assíncrono.

Condicional: conteúdo do documento e nomeDoDocumento ao sobrepor em um PDF; referência quando tipo de referência é QRR ou PONTUAÇÃO; Opções de paginação e Número da página quando tipo de formato é pdf.

Opcional: mensagem não estruturada, informações de faturamento, av1, av2, perfis.

Parâmetro	Obrigatório	Aplica-se quando	O que faz	Exemplo
`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`

Opções de tipo de endereço

Aplica-se a crAddressType e udAddressType.

S (Estruturado)Recomendado para reconciliação automatizada

Armazena rua, número da casa, código postal e cidade em campos separados. Exigido pela maioria dos sistemas bancários suíços para conciliação automática.

K (Combinado)Duas linhas de endereço de formato livre

Armazena o endereço como duas linhas de formato livre combinadas. Mais simples de preencher, mas menos compatível com a reconciliação automatizada.

Opções de linha separadora (`seperatorLine`)

Linha com tesoura

Linha de corte perfurada com símbolos de tesoura. Padrão para faturas impressas na Suíça.

Linha pontilhada

Linha pontilhada separa a fatura do comprovante destacável.

Linha sólida

Linha separadora sólida sem símbolos de tesoura.

Opções de tipo de referência

NÃONenhuma referência estruturada

Padrão para pagamentos simples. Use mensagem não estruturada para uma nota de formato livre em vez de referência.

QRRReferência QR de 27 dígitos

Contas domésticas suíças com PostFinance ou banco suíço IBANsVocê deve enviar referência como uma sequência numérica de 27 dígitos.

PONTUAÇÃOReferência do credor ISO 11649

Transfronteiriço SEPA-correspondência de estilo. Enviar referência em ISO 11649 formato (começa com RF).

Formato de saída (`formatType`) e PDF chamada

Quando tipo de formato é pdf, definir Opções de paginação para controlar onde o QR O comprovante é colocado. Para saída de imagem, omita. Opções de paginação ou defina-o como nulo.

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.

Campos de saída

Campo	Tipo	O que contém
`docName`	String	Output file name.
`docContent`	Base64	Generated file (PDF or image per formatType). Decode before saving or streaming.

Solicitar exemplos

Exemplo A: Independente QR conta (sem entrada) PDF)

Omitir conteúdo do documento ou envie uma string vazia para gerar apenas o QR Comprovante de 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
}

Exemplo B: Sobreposição QR em um existente PDF (Base64)

Substituir conteúdo do documento com o seu PDF como Base64 (não dados: prefixo).

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

Exemplo C: Copiar e colar válido 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
}

cargas úteis de tipo de referência

Sem referência (NON):

{ "referenceType": "NON" }

Referência QR (QRR):

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

Referência do credor (SCOR, ISO 11649):

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

trechos de formatType e pagingOptions

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

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

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

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

Exemplos de código

Exemplos de integração

Padrões comuns de integração RESTTypical ways developers call Create SwissQR Bill.

Exportação de fatura ERP → PDF da fatura QR suíça

Seu sistema ERP exporta dados de faturas e um PDF.
Codifique o PDF em Base64. conteúdo do documento.
campos de pagamento POST com tipo de referência QRR e um código de 27 dígitos referência.
Decodificar conteúdo do documento A partir da resposta, armazene ou envie por e-mail a fatura em PDF com código QR.

sobreposição independente de deslizamento ou webhook

Para obter apenas um comprovante destacável, envie pelo correio com o envelope vazio. conteúdo do documento e tipo de formato pdf ou png.
Para faturas provenientes de um webhook, codifique o PDF em Base64. conteúdo do documento, definir Opções de paginação para durar ou personalizadoe campos de pagamento POST.
Decodifique a resposta conteúdo do documento e fazer o upload para o armazenamento de objetos ou anexá-lo a uma API de e-mail.

Perguntas frequentes

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.