einvoicing-zatca-peppol-compliance

E-Invoicing (ZATCA Phase 2 & Peppol BIS) Compliance Skill Guide

This skill specifies technical standards, cryptographic stamping algorithms, and UBL 2.1 XML schema compliance for statutory e-invoicing systems.

1. Statutory E-Invoicing Cryptographic Flow

[ Business ERP / Billing System ]
                |
                v
[ UBL 2.1 XML Invoice Generation ]
                |
                +---> Compute Canonical Hash: SHA-256(Canonicalized XML)
                +---> Sign Hash using Private Key: ECDSA (secp256k1)
                +---> Generate TLV-Encoded QR Code (Tag-Length-Value Base64)
                +---> Inject Digital Signature & Certificate into XML Extension
                |
                v
[ Government Tax Authority API (ZATCA Clearance / Peppol Access Point) ]

2. Production Code Implementations

A. TLV (Tag-Length-Value) QR Code Generator (Python)

For tax authorities like ZATCA, QR codes must be encoded using strict sequential Tag-Length-Value (TLV) byte structures converted to Base64.

import base64


def encode_tlv_field(tag: int, value: str) -> bytes:
    val_bytes = value.encode("utf-8")
    length = len(val_bytes)
    return bytes([tag, length]) + val_bytes


def generate_zatca_qr_code(
    seller_name: str,
    vat_registration_number: str,
    invoice_timestamp_iso: str,
    invoice_total_with_vat: str,
    vat_amount: str,
    invoice_hash_sha256: str = "",
    digital_signature: bytes = b"",
    public_key: bytes = b"",
) -> str:
    """Generates standard Base64-encoded TLV string for Phase 2 Tax Invoices."""
    tlv_bytes = bytearray()

    # Tag 1: Seller Name
    tlv_bytes.extend(encode_tlv_field(1, seller_name))
    # Tag 2: VAT Registration Number (15 digits)
    tlv_bytes.extend(encode_tlv_field(2, vat_registration_number))
    # Tag 3: Time Stamp (ISO 8601: YYYY-MM-DDTHH:MM:SSZ)
    tlv_bytes.extend(encode_tlv_field(3, invoice_timestamp_iso))
    # Tag 4: Invoice Total (with VAT)
    tlv_bytes.extend(encode_tlv_field(4, invoice_total_with_vat))
    # Tag 5: VAT Amount
    tlv_bytes.extend(encode_tlv_field(5, vat_amount))

    # Phase 2 Cryptographic Extensions
    if invoice_hash_sha256:
        tlv_bytes.extend(encode_tlv_field(6, invoice_hash_sha256))
    if digital_signature:
        tlv_bytes.extend(bytes([7, len(digital_signature)]) + digital_signature)
    if public_key:
        tlv_bytes.extend(bytes([8, len(public_key)]) + public_key)

    return base64.b64encode(tlv_bytes).decode("ascii")