ExCius.InvoiceTemplateXML (ExCius v0.3.2)

View Source

Generates UBL 2.1 Invoice XML documents from validated request parameters.

This module takes validated parameters from ExCius.RequestParams and transforms them into a complete UBL 2.1 Invoice XML document that complies with the Croatian e-Invoice (CIUS-2025) specification.

Features

  • Generates valid UBL 2.1 Invoice XML
  • Complies with Croatian CIUS-2025 specification
  • Supports all required and optional invoice elements
  • Proper namespace declarations and XML structure
  • Automatic formatting for monetary amounts and quantities
  • Mandatory operator notes per Croatian specification with operator name, OIB, and proper date formatting
  • Embedded document attachments (PDF visualization, images, etc.) via AdditionalDocumentReference

Usage

# Create invoice parameters
params = %{
  id: "INV-001",
  issue_datetime: "2025-05-01T12:00:00",
  currency_code: "EUR",
  supplier: %{
    oib: "12345678901",
    registration_name: "Company d.o.o.",
    postal_address: %{...},
    party_tax_scheme: %{...},
    seller_contact: %{
      id: "12345678901",    # Operator's OIB (HR-BT-5)
      name: "Operator1"     # Operator's name (HR-BT-4)
    }
  },
  customer: %{...},
  tax_total: %{...},
  legal_monetary_total: %{...},
  invoice_lines: [...],
  attachments: [                     # Optional embedded documents
    %{
      id: "1",
      filename: "invoice.pdf",
      mime_code: "application/pdf",
      content: "BASE64_ENCODED_CONTENT"
    }
  ]
}

# Validate parameters
{:ok, validated_params} = ExCius.RequestParams.new(params)

# Generate XML
xml = ExCius.InvoiceTemplateXML.build_xml(validated_params)

The generated XML includes:

  • UBL Extensions for signatures
  • Croatian customization and profile IDs
  • Complete supplier and customer party information
  • Tax calculations and categories
  • Payment terms and methods (optional)
  • Multiple invoice lines support
  • Proper XML namespaces and schema locations
  • Mandatory operator and issue time notes
  • Embedded document attachments (AdditionalDocumentReference with EmbeddedDocumentBinaryObject)

XML Structure

The generated XML follows this structure:

  • XML declaration
  • Invoice root element with all namespaces
  • UBL Extensions
  • Invoice identification and dates
  • Notes (operator and user notes)
  • Document currency code
  • Additional document references (embedded attachments)
  • Supplier party (AccountingSupplierParty)
  • Customer party (AccountingCustomerParty)
  • Payment means (optional)
  • Tax totals and subtotals
  • Legal monetary totals
  • Invoice lines with items and pricing

Embedded Attachments

Attachments (like PDF visualizations of the invoice) can be embedded directly in the XML using the AdditionalDocumentReference element with an EmbeddedDocumentBinaryObject. The content must be base64-encoded. Supported MIME types include:

  • application/pdf
  • image/png, image/jpeg, image/gif
  • text/csv, application/xml, text/xml
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet

Summary

Functions

build_xml(params)

Generates UBL Invoice XML from validated request parameters.

Functions

build_xml(params)

Generates UBL Invoice XML from validated request parameters.

Takes the output from ExCius.RequestParams.new/1 and generates a complete UBL 2.1 Invoice XML document as a string.

Parameters

  • params - Validated parameters map from ExCius.RequestParams.new/1

Returns

Returns the complete XML document as a string, including XML declaration.

Examples

iex> invoice_data = %{
...>   id: "5-P1-1",
...>   issue_datetime: "2025-05-01T12:00:00",
...>   currency_code: "EUR",
...>   supplier: %{
...>     oib: "12345678901",
...>     registration_name: "Test Supplier",
...>     postal_address: %{...},
...>     party_tax_scheme: %{...},
...>     seller_contact: %{id: "12345678901", name: "Operator1"}
...>   },
...>   customer: %{...},
...>   tax_total: %{...},
...>   legal_monetary_total: %{...},
...>   invoice_lines: [...]
...> }
iex> {:ok, params} = ExCius.RequestParams.new(invoice_data)
iex> xml = ExCius.InvoiceTemplateXML.build_xml(params)
iex> String.starts_with?(xml, "<?xml version=")
true
iex> String.contains?(xml, "<Invoice xmlns=")
true

The generated XML will be a complete UBL 2.1 Invoice document with all required elements properly formatted and namespace-qualified.