Invoice QR Code and Seller UUID

Marmin automatically generates a Seller UUID and QR code when you create invoice-family documents. Both follow the latest rules and regulations defined by Oman Tax Authority.

Overview

The following document types receive QR code and Seller UUID generation on create:

• Sales invoices

• Sales credit notes

• Sales debit notes

• Purchase invoices

• Purchase credit notes

Two fields are returned in the API response:

You may optionally supply seller_uuid in the create request. If provided, Marmin preserves your value and uses it in the QR TLV payload (tag 9 or 10). If omitted, Marmin derives the Seller UUID deterministically from document fields.

Note: seller_uuid (BTOM-004 / QR identity) is distinct from uuid (Peppol network integration identifier).

Generation pipeline

1. Extract and format QR input fields from the document.

2. Generate or preserve the Seller UUID.

3. Build ordered TLV bytes and Base64-encode them — this string is the QR content.

4. Render a 300×300 PNG QR image and Base64-encode it as qr_code_base64.

Required input fields

Missing required fields cause a validation error at document create time.

Standard vs profit margin invoice type

• QR version is always 1.1 (TLV tag 1).

• Invoice type (TLV tag 2): 01 for standard invoices, 02 for profit margin invoices.

• Profit margin is detected when the transaction_type character at index 9 or 10 is 1 (positions 10–11 in the transaction type table).

When profit margin applies, the QR schema switches: tag 8 carries total amount due (payable_amount) instead of tax-inclusive total and VAT total, and the Seller UUID moves to tag 9.

Seller UUID generation rules

• Algorithm: UUID v5 (RFC 4122), name-based, SHA-1

• Namespace UUID: e0bc4ac8-b025-46e5-a76d-0c893fc3027e

• Input string: Pipe-separated (|) field values, then uppercased

• The Seller UUID itself is excluded from the input string

• Deterministic: identical inputs always produce the same UUID

Standard invoice input (9 fields)

1.1|01|{invoiceNumber}|{sellerName}|{sellerVatin}|{issueDate}|{issueTime}|{taxInclusiveAmount}|{vatTotal}

Profit margin input (8 fields)

1.1|02|{invoiceNumber}|{sellerName}|{sellerVatin}|{issueDate}|{issueTime}|{payableAmount}

Golden example — standard invoice

Golden example — profit margin invoice

QR code TLV encoding rules

Each TLV field is encoded as:

[tag: 1 byte][length: 1 byte][value: UTF-8 bytes]

Additional constraints:

• Maximum value length: 255 UTF-8 bytes per tag

• Field order is fixed (see tables below)

• TLV bytes are Base64-encoded; the resulting string is encoded into the QR image

• Maximum TLV Base64 length: 700 characters

Standard invoice TLV tags (`01`)

Profit margin TLV tags (`02`)

Tags 1–7 match the standard schema. Differences:

There is no tag 10 and no separate VAT total tag in the profit margin schema.

Golden TLV Base64 examples

Standard invoice:

AQMxLjECAjAxAwpJTlZPSUNFLTAxBAjYqNin2KbYuQUMT00xMjM0NTY3ODkxBgoyMDI2LTA1LTEzBwgxODozMTowMAgHMzAyLjM0MAkGMTQuNTIwCiQ0NTRjYjdlYS1mMWY3LTViNjktOWUwYi03NTZmMDAyZWZhNTI=

Profit margin invoice:

AQMxLjECAjAyAwpJTlZPSUNFLTAxBAjYqNin2KbYuQUMT00xMjM0NTY3ODkyBgoyMDI2LTA1LTEzBwgxODozMDowMAgIMTAzMi4yMTAJJDk3MjRhNzgwLTIzNjAtNTAyYS1iNmEyLTIwMWJmMGYwNjhjNg==

Amount formatting

All monetary values in the TLV payload use 3 decimal places with half-up rounding (HALF_UP). Null amounts are formatted as 0.000.

API response and UBL mapping

Downloaded PDFs render the QR code from qr_code_base64.

Validation and compliance notes

When required QR input fields are missing, the API returns a validation error. Common field paths:

IBR-173-OM: When the buyer electronic address (IBT-049) is 997770000099, the Seller UUID (BTOM-004) must be present and match ^[A-Za-z0-9-]+$.

If the TLV Base64 string exceeds 700 characters, the API returns a validation error on qr_code.

Recommended practices (Do's)

• Do supply a complete seller party (party_name, VATIN) and issue date/time before create.

• Do set profit-margin flags in transaction_type when applicable so the correct QR schema is used.

• Do treat qr_code_base64 as the PNG image for display, PDF, and UBL embedding.

Behaviours to avoid (Don'ts)

• Don't confuse qr_code_base64 (PNG image Base64) with the TLV Base64 string encoded inside the QR code.

• Don't manually set seller_uuid without reason — Marmin derives it deterministically from the same fields used in the QR payload.

• Don't omit issue_time — it is required for QR generation even when optional elsewhere.

• Don't mix up uuid (Peppol) and seller_uuid (BTOM-004) — they serve different purposes.