canonical: https://jentic.com/apis/qr-invoice.cloud/qr-invoice

# QR Invoice REST API

The QR Invoice REST API creates and processes Swiss QR bills: it renders the Payment Part & Receipt slip as PDF or image, generates full QR invoice documents from templates, and merges or appends the slip onto your own PDF invoices. It also parses and validates Swiss QR Codes found in documents, builds and checks QR references and creditor references, and validates and formats IBANs and QR-IBANs. Bulk operations turn a list or a CSV or XLSX file into many payment slips at once.

## For AI agents

Generate Swiss QR bill payment slips and invoice documents, attach them to existing PDFs, parse QR codes from received invoices, and validate IBANs, QR-IBANs, and payment references.

## Scope

Does not send invoices, collect payments, or keep accounting records. Use for generating, parsing, and validating Swiss QR bills and their payment references only.

## Capabilities

- Render a Swiss QR bill Payment Part & Receipt from creditorInformation, paymentAmountInformation, ultimateDebtor, and paymentReference
- Merge the payment slip into an existing PDF invoice or append it on a new page
- Create complete QR invoice documents from the available templates, with language set via Accept-Language
- Parse and validate the Swiss QR Code in a received PDF or image, including all codes in a document
- Create, validate, and format QR references and RF creditor references with their check digits
- Validate, normalize, and format IBANs and check whether an IBAN is a QR-IBAN
- Generate many payment slips in bulk from a list or an uploaded CSV or XLSX file

## Use cases

### Agent-issued Swiss QR bills through Jentic

A bookkeeping agent issues invoices for a Swiss business: it builds a QR reference, then calls the Payment Part & Receipt operation and merges the slip into the invoice PDF. Through Jentic the X-API-Key is injected by the developer's own Jentic One instance, so the agent never holds the key.

Example prompt: POST `/v2/qr-reference/create` for customer reference '1234', then POST `/v2/payment-part-receipt/merge` with the invoice PDF and a QrInvoice carrying creditorInformation, paymentAmountInformation of CHF 450, and the new paymentReference

### Accounts payable QR code intake

Incoming supplier bills carry a Swiss QR Code with the payee, amount, and reference. POST `/v2/swiss-qr-code/parse` extracts the first code from a document and `/v2/swiss-qr-code/parseAll` returns every code, so an agent can prefill payments without retyping IBANs.

Example prompt: POST the supplier PDF to `/v2/swiss-qr-code/parse` and return the creditor IBAN, amount, currency, and reference

### Bulk payment slip generation

Monthly membership or rent runs need hundreds of slips. POST `/v2/payment-part-receipt/bulk/file` accepts a CSV or XLSX input and returns a multi-page PDF or a ZIP of files, while `/v2/payment-part-receipt/bulk/list` takes a JSON list of invoices.

Example prompt: POST the member CSV to `/v2/payment-part-receipt/bulk/file` and save the returned PDF

### Payment data validation

Bad references and IBANs make bills unpayable. The API validates IBANs and QR-IBANs, QR references with modulo 10 recursive check digits, and RF creditor references with modulo 97, so an agent can check data before an invoice is sent.

Example prompt: POST the IBAN to `/v2/qr-iban/validate` and the reference to `/v2/qr-reference/validate`, and report whether both are valid

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v2/payment-part-receipt` | Create Payment Part & Receipt |
| POST | `/v2/payment-part-receipt/merge` | Create a slip and merge it with a PDF |
| POST | `/v2/invoice-document` | Create a QR invoice document |
| POST | `/v2/swiss-qr-code/parse` | Parse a Swiss QR Code from a document |
| POST | `/v2/qr-reference/create` | Create a QR reference |
| POST | `/v2/qr-iban/validate` | Validate a QR-IBAN |
| POST | `/v2/payment-part-receipt/bulk/file` | Bulk slips from CSV or XLSX |

## Key resources

- **Payment Part & Receipt** — Create, merge, append, clone, and bulk-generate Swiss QR bill payment slips
- **Invoice documents** — Full QR invoice documents from templates, with customer resources
- **Swiss QR Code and Swiss Payments Code** — Create, parse, and validate the QR code and its payload
- **References** — QR references and creditor references: create, validate, normalize, format, extract
- **IBAN** — Validate, normalize, and format IBANs and QR-IBANs
- **Bill information and alternative schemes** — Swico S1 v1.2 and eBill structures

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 52 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 74 / 100
  - Developer Experience & Jentic Compatibility: 64 / 100
  - AI-Readiness & Agent Experience: 38 / 100
  - Agent Usability: 89 / 100
  - Security: 33 / 100
  - AI Discoverability: 46 / 100
- **View full report:** https://jentic.com/apis/qr-invoice.cloud/qr-invoice/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring QR Invoice by hand means picking between its X-API-Key header and api_key query parameter, building the nested QrInvoice payload, and handling PDF and image responses yourself. Through Jentic you install once, import QR Invoice from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** QR Invoice carries invoice data in the request body rather than in resource paths, so rules bound which operations your agent may call, not which invoice. You choose the operations it may call, so bill generation, bulk runs, or customer resource uploads are not included unless you add them.
- **Credential handling:** Your QR Invoice API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a Swiss QR bill' or 'parse a QR code from an invoice', and Jentic returns the matching QR Invoice operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **bexio API** — Swiss business accounting and invoicing software
- **Invoice Ninja API** — Invoicing and billing platform with clients, invoices, and payments
- **goQR.me API** — Generic QR code generation and reading

## FAQ

### What authentication does the QR Invoice REST API use?

The QR Invoice REST API declares two API key schemes in its OpenAPI spec: the X-API-Key header and the api_key query parameter, either of which is accepted. Through Jentic the key is stored encrypted by your own Jentic One instance and injected at execution time, so it never enters the agent's context.

### Can I add a Swiss QR bill to an invoice PDF I already have?

Yes. POST `/v2/payment-part-receipt/merge` creates the Payment Part & Receipt and merges it with your PDF, and POST `/v2/payment-part-receipt/append` adds it on a new page instead. Query parameters such as pageSize and fontFamily control the output.

### What are the rate limits for the QR Invoice REST API?

The OpenAPI spec does not specify rate limits; it notes that the demo key carries restrictions. Check the vendor site at https://www.qr-invoice.ch for the limits that apply to your key.

### How do I create a QR bill payment slip through Jentic?

Install Jentic One, import the QR Invoice REST API from the Jentic API Directory, and store your API key. Your agent searches for 'create a Swiss QR bill', Jentic returns POST `/v2/payment-part-receipt` with its QrInvoice schema, and the agent calls it with creditorInformation, paymentAmountInformation, and paymentReference. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Is there a QR Invoice MCP server?

You don't need an MCP server to give your agent the QR Invoice REST API. Jentic connects it directly from the API Directory: import it, store your credential once, and your agent calls it, discovering operations on demand rather than loading every tool definition into its context.

### Can I limit what my agent is allowed to do with the QR Invoice REST API?

Yes. For an accounts-payable agent, write a rule that allows only POST `/v2/swiss-qr-code/parse`, `/v2/swiss-qr-code/validate`, and `/v2/qr-iban/validate`, so it can read and check incoming bills but cannot generate bills or upload customer resources. Every call it makes is logged.

### Can the QR Invoice REST API parse QR codes from received invoices?

Yes. POST `/v2/swiss-qr-code/parse` returns the first Swiss QR Code found in a document, and POST `/v2/swiss-qr-code/parseAll` returns all of them in an array. Use `/v2/swiss-qr-code/validate` to check a file containing a single code.