创建 SwissQR 账单 API
此端点的作用
PDF4me 创建 SwissQR 账单 瑞士人 QR 符合瑞士规定的付款单 QR-账单标准（瑞士支付标准， SPS）通过单个 REST 拨打电话。发送 债权人和最终债务人的详细信息 IBAN金额、货币、参考类型、语言、分隔符样式和输出格式（可选）包含源文档 Base64，blob ID，或 URL 将滑移层覆盖在现有滑移层上 PDF。 这 API 返回 PDF， PNG， JPEG， 或者 TIFF 根据 格式类型。
相关博客文章
目前尚无关于此功能的博客文章——敬请期待。
在此期间，您可以浏览 PDF4me 博客，查看适用于各平台的教程和工作流程。
访问博客 →
验证您的身份 API 要求
每一个 PDF4me REST API 通话必须包含您的 API 关键在于 Authorization 标题。从开发者控制面板创建或选择一个密钥，并妥善保管。
端点
邮政
/api/v2/CreateSwissQrBill您不容错过的重要事实
瑞士IBAN格式经过严格验证
债权人
他们要走了 必须从 CH 后面跟着19位数字。无效密码。 IBAN 返回错误。生产环境请使用结构化地址类型 (S)。
放
crAddressType 和 udAddressType 到 S 因此，街道、门牌号、邮政编码和城市分别存储。大多数瑞士银行自动对账系统都要求采用这种布局。 K （合并）仅当无法拆分地址分量时才使用。将参考类型与您的对账工作流程相匹配
非 对于没有结构化参考信息的付款。 QRR 用于瑞士国内纸币上的 27 位数字参考编号。 得分 为了 ISO 11649 债权人证明。请提供。 参考 使用时在体内 QRR 或者 SCOR。REST API 端点
方法： 邮政
网址： https://api.pdf4me.com/api/v2/CreateSwissQrBill
放 IsAsync 到 真的 （PascalCase） 为了 202 Accepted 并进行民意调查 地点 URL 和 GET 直到你收到 200 以及该文件 JSON。 使用 错误的 对于同步 200 回复。
Postman 请求设置
| 环境 | 价值 |
|---|---|
| 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). |
参数
始终需要： 他们要走了， crName， crAddressType， crStreetOrAddressLine1， crStreetOrAddressLine2， crPostalCode， crCity， 数量， 货币， udName， udAddressType， udStreetOrAddressLine1， udStreetOrAddressLine2， udPostalCode， udCity， 参考类型， 语言类型， 分隔线， 格式类型， 和 IsAsync。
条件： 文档内容 和 文档名称 在 PDF 上叠加时； 参考 什么时候 参考类型 是 QRR 或者 得分； 分页选项 和 页码 什么时候 格式类型 是 pdf。
选修的： 非结构化消息， 账单信息， av1， av2， 简介。
| 范围 | 必需的 | 适用于 | 它的作用 | 例子 |
|---|---|---|---|---|
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 |
地址类型选项
适用于 crAddressType 和 udAddressType。
S（结构化）推荐用于自动对账将街道、门牌号、邮政编码和城市分别记录在不同的字段中。大多数瑞士银行系统需要这些信息来进行自动对账。
K（综合）两条自由格式地址线将地址存储为两行合并的自由格式文本。这种存储方式更易于填写，但与自动对账的兼容性较差。
分隔线选项（seperatorLine）
用剪刀画线带有剪刀符号的穿孔切割线。瑞士印刷发票的默认样式。
虚线发票和撕取单之间的虚线分隔线。
实线没有剪刀符号的实线分隔线。
参考类型选项
非没有结构化参考简单支付的默认设置。使用
非结构化消息 改为自由格式笔记，而不是 参考。QRR27 位二维码参考瑞士国内纸币 PostFinance 或瑞士银行 IBANs你必须发送
参考 以 27 位数字字符串的形式。得分ISO 11649 债权人参考跨境 SEPA样式匹配。发送
参考 在 ISO 11649 格式（以……开头） RF）。输出格式（formatType） 和 PDF 分页
什么时候 格式类型 是 pdf， 放 分页选项 控制位置 QR 放置滑片。对于图像输出，请省略。 分页选项 或者将其设置为 无效的。
formatType: pdfpagingOptions: firstPlace QR slip on the first page.
formatType: pdfpagingOptions: lastPlace QR slip on the last page.
formatType: pdfpagingOptions: AddPageAtEndAppend a new page with the QR slip at the end.
formatType: pdfpagingOptions: custom + pageNumberPlace on a specific page (e.g. pageNumber: 1).
formatType: png | jpeg | tiffpagingOptions: nullNo paging; returns image bytes.
输出字段
| 场地 | 类型 | 它包含什么 |
|---|---|---|
docName | String | Output file name. |
docContent | Base64 | Generated file (PDF or image per formatType). Decode before saving or streaming. |
请求示例
示例 A：独立式 QR 账单（无输入） PDF）
省略 文档内容 或者发送一个空字符串，仅生成 QR 付款单。
{
"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
}
示例 B：叠加 QR 在现有基础上 PDF （Base64）
代替 文档内容 你的 PDF 作为 Base64 （不 数据： 前缀）。
{
"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
}
示例 C：复制粘贴有效 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
}
引用类型有效载荷
无参考文献（非）：
{ "referenceType": "NON" }
QR参考码（QRR）：
{
"referenceType": "QRR",
"reference": "21000000000313947143000017"
}
债权人参考编号（SCOR，ISO 11649）：
{
"referenceType": "SCOR",
"reference": "RF18539007547034"
}
formatType 和 pageingOptions 代码片段
{ "formatType": "png", "pagingOptions": null }
{ "formatType": "pdf", "pagingOptions": "last" }
{ "formatType": "pdf", "pagingOptions": "AddPageAtEnd" }
{ "formatType": "pdf", "pagingOptions": "custom", "pageNumber": 1 }
代码示例
集成示例
常见的 REST 集成模式Typical ways developers call Create SwissQR Bill.
ERP发票导出 → 瑞士二维码账单PDF
- 您的ERP系统会导出发票数据和PDF文件。
- 将 PDF 文件进行 Base64 编码
文档内容。 - POST 付款字段
参考类型QRR 和 27 位数字参考。 - 解码
文档内容从回复中获取并存储或通过电子邮件发送二维码账单 PDF 文件。
独立式滑套或网钩覆盖层
- 仅需撕取式收据，请附上空白收据并邮寄。
文档内容和格式类型pdf 或 png 格式。 - 对于通过 webhook 发送的发票，将 PDF 文件进行 Base64 编码。
文档内容， 放分页选项到最后的或者风俗以及 POST 付款字段。 - 解读回应
文档内容并上传到对象存储或附加到电子邮件 API。
常见问题解答
相关行动
创造瑞士 QR 账单 （n8n）
与工作流程相同的后端 UI二进制数据 URL独立单据、格式类型和分页选项。
读取 SwissQR 码
从中提取支付数据 PDFs 已经包含一个瑞士 QR-账单。
API 测试员
与您的设备进行交互式测试，尝试使用该端点。 API 关键和示例 PDF。
在其他平台上执行相同的任务
创造瑞士 QR 账单（制作）
具有相同视觉场景 SPS符合规范的字段和 IBAN 验证。
创造瑞士 QR 账单 （Zapier）
瑞士扳机 QR 发票来自 SaaS 应用程序和网络钩子。
创造瑞士 QR 账单 （Power Automate）
Microsoft 365 与……流动 SharePoint， Outlook， 和 Dynamics 集成。
创造瑞士 QR 账单 （n8n）
构建自托管或云平台 n8n 与瑞士相同的流程 QR-账单字段和输出选项。