Generate a ZATCA-compliant TLV-encoded QR code.

Creates a Base64-encoded QR code payload following ZATCA's Tag-Length-Value (TLV) format for Phase 1 and Phase 2 compliance. The resulting string can be used to generate a scannable QR code on printed invoices.

Args: seller_name: Business/taxpayer name (Arabic or English) vat_number: 15-digit Saudi VAT registration number (starts and ends with 3) timestamp: Invoice date/time in ISO 8601 format (e.g., "2024-01-15T10:30:00Z") total_amount: Invoice total including VAT as string (e.g., "1150.00") vat_amount: Total VAT charged as string (e.g., "150.00")

Returns: JSON with qr_base64 (the encoded string) and decoded verification data

Generate a ZATCA-compliant UBL 2.1 XML e-invoice.

Creates a complete XML invoice following Saudi Arabia's ZATCA e-invoicing standard. Supports Standard (B2B), Simplified (B2C), Credit Note, and Debit Note invoice types. Automatically calculates VAT, line totals, and embeds QR code data.

Args: invoice_type: "standard" (B2B), "simplified" (B2C), "credit_note", or "debit_note" invoice_number: Unique invoice identifier (e.g., "INV-2024-001") issue_date: Invoice date in YYYY-MM-DD format seller_name: Seller business name seller_vat: Seller 15-digit VAT number (e.g., "300000000000003") seller_address: Seller street address seller_city: Seller city name buyer_name: Buyer/customer name items: JSON array of line items. Each item: {"name": "Product", "quantity": 1, "unit_price": 100.00, "vat_rate": 0.15} currency: ISO currency code (default: "SAR") buyer_vat: Buyer VAT number (required for standard invoices) buyer_address: Buyer street address (optional) buyer_city: Buyer city (optional) note: Optional note to include on the invoice billing_reference_id: Original invoice ID (required for credit/debit notes) billing_reference_date: Original invoice date (for credit/debit notes) instruction_note: Reason for credit/debit note (recommended)

Returns: Complete UBL 2.1 XML invoice string

Validate an invoice XML against ZATCA business rules.

Runs comprehensive checks including: required fields, VAT number format, mathematical accuracy of line totals and VAT calculations, and structural integrity of the UBL 2.1 XML.

Args: invoice_xml: Complete UBL 2.1 XML invoice string to validate

Returns: JSON with is_valid (boolean), errors (list of issues), warnings (list), and checks_run (number of rules checked)

Decode a ZATCA TLV-encoded QR code string.

Useful for verifying or inspecting existing QR codes from ZATCA-compliant invoices. Extracts all encoded tag values.

Args: qr_base64: Base64-encoded TLV string from a ZATCA QR code

Returns: JSON with decoded tag names and their values

Generate a ZATCA-compliant Certificate Signing Request (CSR).

Creates an ECDSA key pair and CSR with ZATCA-required subject fields. The CSR is used to obtain a compliance certificate from ZATCA.

Args: common_name: Common name for the certificate (e.g., device or taxpayer name) organization: Organization name organizational_unit: Organizational unit (e.g., "Invoicing", "IT") country: Country code (default: "SA") serial_number: ZATCA device serial number invoice_type: ZATCA invoice type code (e.g., "1100") location: Business location industry: Business industry category

Returns: JSON with csr_pem, private_key_pem, and next steps

Digitally sign a ZATCA invoice with XAdES-BES.

Takes an unsigned invoice XML and applies a digital signature using the provided certificate and private key. Produces a signed XML with embedded XAdES-BES signature in UBLExtensions, and rebuilds the QR code with Phase 2 tags (hash, signature, public key).

Args: invoice_xml: Unsigned UBL 2.1 XML invoice string certificate_pem: PEM-encoded X.509 certificate from ZATCA private_key_pem: PEM-encoded ECDSA private key

Returns: JSON with signed_xml, invoice_hash, qr_base64, and compliance status

Submit a signed invoice to ZATCA for reporting or clearance.

Sends the signed invoice to ZATCA's Fatoora API. Use "reporting" mode for simplified invoices (B2C) and "clearance" mode for standard invoices (B2B).

Args: signed_invoice_xml: Signed UBL 2.1 XML invoice string invoice_hash: Base64-encoded SHA-256 hash of the invoice invoice_uuid: Invoice UUID certificate: Base64-encoded compliance/production certificate secret: API secret from ZATCA mode: "reporting" (simplified) or "clearance" (standard) environment: "sandbox" or "production"

Returns: JSON with ZATCA's response (status, validation results)

Check a signed invoice against ZATCA compliance rules.

Validates the invoice with ZATCA's server-side checks before actual submission. Useful for testing compliance without affecting production records.

Args: signed_invoice_xml: Signed UBL 2.1 XML invoice string invoice_hash: Base64-encoded SHA-256 hash of the invoice invoice_uuid: Invoice UUID certificate: Base64-encoded compliance certificate secret: API secret from ZATCA environment: "sandbox" or "production"

Returns: JSON with ZATCA validation results

Render a ZATCA invoice XML as a professional HTML document.

Takes a UBL 2.1 XML invoice (as generated by generate_invoice) and produces a styled HTML page with embedded QR code image, ready for viewing in a browser or printing.

Args: invoice_xml: Complete UBL 2.1 XML invoice string

Returns: Complete HTML document string with embedded styles and QR code image