POST /v1/qr-bill

Render a Swiss QR-bill — SPC v0200 payload + PDF / SVG / PNG / JSON output.

Encodes a Swiss QR-bill and renders to one of four output formats: payload (just the SPC v0200 text), svg, pdf, png. IBAN mod-97 + QR-IBAN range check + QRR mod-10 (Lührmann) all validated at submit. Payload capped at 997 bytes per SPC spec.

The renderer is V8-isolate-pure; the PDF path uses a stripped-down pdf-lib that ships in the Workers bundle. Same renderer runs at POST /v1/qr-bill and at the free browser-side /qrbill page.

Multilingual labels: pass language as en / de / fr / it. Default en.

See apps/api/src/routes/qrbill.ts and apps/api/src/lib/spc.ts + qrbill-pdf.ts + qrbill-svg.ts.

Request

Request body

{
  "output_format": "'payload' | 'svg' | 'pdf' | 'png'",
  "creditor": "{ name, iban, address }",
  "debtor": "{ name, address } (optional)",
  "amount": "number (optional; if absent, the slip has an empty amount box)",
  "currency": "'CHF' | 'EUR'",
  "reference": "{ type: \"QRR\" | \"SCOR\" | \"NON\", value? }",
  "message": "string (optional, unstructured)",
  "bill_info": "string (optional, Swico encoding)",
  "language": "'en' | 'de' | 'fr' | 'it'"
}

Response

Response body

{
  "output_format": "string",
  "payload": "string (SPC v0200)",
  "data": "string (base64 if pdf/png/svg)",
  "sha256": "hex string"
}

Idempotency

Mandatory header `Idempotency-Key` (UUID or other opaque ≤64 char string). A second request with the same key and the same body returns the cached response and the header `X-Iso-Compliant-Idempotent-Replay: true`. A second request with the same key but a different body returns 409.

Rate limit

Sandbox: 60 requests / minute, 1000 / day. Production: 600 requests / minute soft cap, lifted per tenant on request.

← All docs