qrid 1.0.1

Decode and encode MergeID electronic invoice QR codes

qrid — Python

Decode and encode MergeID electronic invoice QR codes.

Python port of qrid/codec (PHP). All three implementations (PHP, Node.js, Python) share the same payload format and function signatures, so QR codes generated by any one of them scan correctly in the others.

Typical usage flow

sequenceDiagram
    actor Staff as Billing Staff
    participant ERP as Billing / ERP System
    participant Lib as qrid
    participant QR as Invoice QR Code
    participant App as MergeID App

    Staff->>ERP: create invoice
    ERP->>Lib: encode_qr_id(code, id, company, email, address)
    Lib-->>ERP: SVG QR code
    ERP->>QR: print / embed on invoice

    Note over App,QR: later, at point of scan
    App->>QR: scan with camera
    QR-->>App: base64 payload string
    App->>Lib: decode_qr_id(encoded)
    Lib-->>App: { v, code, id, company, email, address }
    App-->>Staff: display verified invoice identity

Installation

# Decode only (no extra dependencies)
pip install qrid

# Decode + encode SVG
pip install 'qrid[encode]'

Usage

Decode

from qrid import decode_qr_id

# `encoded` is the raw string value scanned from a MergeID QR code
payload = decode_qr_id(encoded)

print(payload["v"])       # Payload schema version (int, currently 1)
print(payload["code"])    # Installation / activity code  (e.g. "ACT-001")
print(payload["id"])      # Tax or company ID              (e.g. "3101679980")
print(payload["company"]) # Company legal name
print(payload["email"])   # Billing e-mail address
print(payload["address"]) # Physical address

decode_qr_id strips surrounding whitespace before decoding, so strings copied with accidental padding are handled transparently.

Exceptions raised:

Exception	Cause
ValueError	Input is not valid base64
json.JSONDecodeError	Decoded bytes are not valid JSON

import json
from qrid import decode_qr_id

try:
    payload = decode_qr_id(raw)
except ValueError:
    # QR data was not base64
    ...
except json.JSONDecodeError:
    # QR data decoded but was not the expected JSON structure
    ...

Encode (requires qrid[encode])

from qrid import encode_qr_id

svg = encode_qr_id(
    code="ACT-001",
    id="3101679980",
    company="Acme Corp S.A.",
    email="[e-mail]",
    address="123 Main St, San José, Costa Rica",
)

# Write to a file
with open("invoice_qr.svg", "w") as f:
    f.write(svg)

# Or serve directly
# Content-Type: image/svg+xml

Exceptions raised:

Exception	Cause
ImportError	segno is not installed (pip install 'qrid[encode]')

Payload format

The QR code data is a UTF-8 JSON object encoded as standard base64 (no line-breaks):

{
  "v": 1,
  "code": "ACT-001",
  "id": "3101679980",
  "company": "Acme Corp S.A.",
  "email": "[e-mail]",
  "address": "123 Main St, San José, Costa Rica"
}

Field	Type	Description
v	int	Payload schema version. Currently always 1.
code	str	Installation or activity code that links the QR to an internal record.
id	str	Tax / company registration ID.
company	str	Legal company name (UTF-8, including accented characters).
email	str	Primary billing or contact e-mail address.
address	str	Physical address of the company.

Requirements

Dependency	Version	Required for
Python	>= 3.9	Always
segno	>= 1.6	encode_qr_id() only

Running tests

pip install 'qrid[dev]'
pytest

License

MIT