Crear factura SwissQR API

Lo que hace este punto final

PDF4me Crear factura SwissQR genera suizo QR Comprobantes de pago que cumplen con la normativa suiza QR-estándar de factura (Estándares de pago suizos, SPS) a través de un único REST Llamar. Enviar Datos del acreedor y del deudor final, IBAN, importe, moneda, tipo de referencia, idioma, estilo de separador y formato de salida. Opcionalmente, incluya un documento fuente como Base64, ID de blob o URL superponer el deslizamiento sobre uno existente PDF. El API devoluciones PDF, PNG, JPEG, o TIFF Dependiendo de tipo de formato.

Entradas de blog relacionadas

Aún no hay ninguna entrada de blog sobre esta función; estará disponible próximamente.

Mientras tanto, echa un vistazo al blog de PDF4me para encontrar tutoriales y flujos de trabajo para todas las plataformas.

Visita el blog →

Autenticando su API Pedido

Cada PDF4me REST API La llamada debe incluir su API clave en el Authorization Encabezado. Crea o selecciona una clave desde el panel de control del desarrollador y mantenla en secreto.

Get your API Key

Punto final

CORREO/api/v2/CreateSwissQrBill

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

Datos importantes que no debes perderte

El formato IBAN suizo está estrictamente validado.

El acreedor iban debe comenzar con CH seguido de 19 dígitos. Un valor no válido IBAN devuelve un error.

Utilice el tipo de dirección estructurada (S) para la producción.

Colocar crAddressType y udAddressType a S Por lo tanto, la calle, el número de casa, el código postal y la ciudad se almacenan por separado. Este formato es necesario para la mayoría de las conciliaciones bancarias automatizadas en Suiza. K (Combinado) solo cuando no se pueden separar los componentes de la dirección.

Haga coincidir referenceType con su flujo de trabajo de conciliación

NO para pagos sin una referencia estructurada. QRR para una referencia numérica de 27 dígitos en billetes suizos nacionales. PUNTUACIÓN para ISO 11649 Referencias de acreedores. Incluir referencia en el cuerpo cuando se utiliza QRR o SCOR.

REST API punto final

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

Colocar Es asíncrono a verdadero (PascalCase) para 202 Accepted y encuestar el Ubicación URL con GET hasta que reciba 200 y el archivo en JSON. Usar FALSO para un síncrono 200 respuesta.

Configuración de solicitudes de Postman

Configuración	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

Siempre requerido: iban, crName, crAddressType, crCalleODirecciónLínea1, crCalleODirecciónLínea2, código postal, crCity, cantidad, divisa, udName, udAddressType, udCalleODirecciónLínea1, udCalleODirecciónLínea2, Código postal, udCity, tipo de referencia, tipo de idioma, Línea separadora, tipo de formato, y Es asíncrono.

Condicional: docContent y Nombre del documento al superponerlo sobre un PDF; referencia cuando tipo de referencia es QRR o PUNTUACIÓN; opciones de paginación y Número de página cuando tipo de formato es PDF.

Opcional: Mensaje no estructurado, información de facturación, av1, av2, perfiles.

Parámetro	Requerido	Se aplica cuando	Lo que hace	Ejemplo
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

Opciones de tipo de dirección

Se aplica a crAddressType y udAddressType.

S (Estructurado)Recomendado para la conciliación automatizada

Almacena la calle, el número de casa, el código postal y la ciudad en campos separados. Requerido por la mayoría de los sistemas bancarios suizos para la conciliación automatizada.

K (combinado)Dos líneas de dirección de formato libre

Almacena la dirección como dos líneas de formato libre combinadas. Es más sencillo de completar, pero menos compatible con la conciliación automatizada.

Opciones de línea separadora (seperatorLine)

Línea con tijeras

Línea de corte perforada con símbolos de tijeras. Indicación predeterminada para facturas suizas impresas.

Línea punteada

Línea separadora de puntos entre la factura y el comprobante desprendible.

Línea sólida

Línea separadora sólida sin símbolos de tijeras.

Opciones de tipo de referencia

NOSin referencia estructurada

Predeterminado para pagos simples. Usar Mensaje no estructurado para una nota de formato libre en lugar de referencia.

QRRReferencia QR de 27 dígitos

Billetes suizos nacionales con PostFinance o banco suizo IBANsDebes enviar referencia como una cadena numérica de 27 dígitos.

PUNTUACIÓNReferencia del acreedor ISO 11649

Transfronterizo SEPACoincidencia de estilo. Enviar referencia en ISO 11649 formato (comienza con RF).

Formato de salida (formatType) y PDF paginación

Cuando tipo de formato es PDF, colocar opciones de paginación para controlar dónde el QR Se coloca el deslizamiento. Para la salida de la imagen, omitir opciones de paginación o configurarlo en 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 salida

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

Ejemplos de solicitud

Ejemplo A: Independiente QR factura (sin entrada) PDF)

Omitir docContent o envíe una cadena vacía para generar solo la QR Comprobante de pago.

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

Ejemplo B: Superposición QR en un existente PDF (Base64)

Reemplazar docContent con tu PDF como Base64 (No datos: prefijo).

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

Ejemplo C: Copiar y pegar 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 útiles de tipo de referencia

Sin referencia (NON):

{ "referenceType": "NON" }

Código QR de referencia (QRR):

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

Referencia del acreedor (SCOR, ISO 11649):

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

Fragmentos de formato y opciones de paginación

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

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

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

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

Ejemplos de código

C# Sample

Java Sample

JavaScript Sample

Python Sample

n8n Sample

All API Samples

Ejemplos de integración

Patrones comunes de integración RESTTypical ways developers call Create SwissQR Bill.

Exportación de facturas ERP → Factura suiza en formato PDF con código QR

1. Su sistema ERP exporta los datos de las facturas y un archivo PDF.
2. Codifique el PDF en Base64 docContent.
3. Campos de pago POST con tipo de referencia QRR y un número de 27 dígitos referencia.
4. Decodificar docContent a partir de la respuesta y almacenar o enviar por correo electrónico el PDF de la factura con código QR.

Superposición de webhook o deslizamiento independiente

1. Solo para un formulario desprendible, ENVÍE con espacio vacío. docContent y tipo de formato pdf o png.
2. Para facturas de un webhook, codifique el PDF en Base64. docContent, colocar opciones de paginación a último o costumbrey campos de pago POST.
3. Decodifica la respuesta docContent y cargarlo al almacenamiento de objetos o adjuntarlo a una API de correo electrónico.

Preguntas frecuentes

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.

Acciones relacionadas

Crear suizo QR Factura (n8n)

Mismo backend con flujo de trabajo UI: Datos binarios, URL, formularios independientes, tipos de formato y opciones de paginación.

Lea el código SwissQR

Extraer datos de pago de PDFs que ya contienen un suizo QR-factura.

API probador

Pruebe el punto final de forma interactiva con su API clave y muestra PDF.

La misma tarea en otras plataformas.

Crear suizo QR Factura (Hacer)

Escenarios visuales con el mismo SPS-campos compatibles y IBAN validación.

Crear suizo QR Factura (Zapier)

Trigger Swiss QR facturación de SaaS aplicaciones y webhooks.

Crear suizo QR Factura (Power Automate)

Microsoft 365 fluye con SharePoint, Outlook, y Dynamics integraciones.

Crear suizo QR Factura (n8n)

Construya una solución autoalojada o en la nube. n8n flujos de trabajo con el mismo suizo QR-Campos de facturación y opciones de salida.

Obtén ayuda

Get Your API KeyAPI SamplesAPI TesterGetting Started