# `UblEx.Generator.Helpers`
[🔗](https://github.com/Octarion/ubl_ex/blob/v0.8.1/lib/ubl_ex/generator/helpers.ex#L1)

Helper functions for UBL generation.

Contains utility functions for calculating totals, formatting values,
and generating XML fragments.

# `allowance_charge_xml`

Generate AllowanceCharge XML for a detail with discount.

# `billing_reference`

Generate BillingReference XML elements.

Accepts a list of invoice numbers and generates BillingReference elements.

# `city_name_xml`

Generate optional CityName XML element.

# `delivery_terms`

Generate Delivery terms XML for invoices.

# `escape`

Escape XML special characters.

# `format`

Format a Decimal amount as a string with 2 decimal places.

# `infer_scheme`

Infer Peppol scheme ID from country code.

Returns the country-specific scheme if known, otherwise returns "0088" (EAN/GLN).

## Examples

    iex> UblEx.Generator.Helpers.infer_scheme("BE")
    "0208"

    iex> UblEx.Generator.Helpers.infer_scheme("US")
    "0088"

# `infer_tax_category`

Infer tax category from detail, defaulting based on VAT percentage.

If `tax_category` is explicitly set, use it. Otherwise:
- VAT 6%, 12%, 21% → :standard
- VAT 0% → :zero_rated

# `party_legal_entity_xml`

Generate PartyLegalEntity XML with optional CompanyID.

# `party_scheme`

Get scheme for a party, using explicit scheme if provided, otherwise inferring from country.

# `party_tax_scheme_xml`

Generate optional PartyTaxScheme XML element for supplier.

# `peppol_code_to_category`

Convert a Peppol tax category code to a descriptive atom.

Returns `:standard` for unknown codes.

# `postal_address_xml`

Generate PostalAddress XML with optional elements.
Only Country > IdentificationCode is required.

# `postal_zone_xml`

Generate optional PostalZone XML element.

# `street_address`

Format street address with optional house number.

# `street_name_xml`

Generate optional StreetName XML element.

# `tax`

Generate tax category XML (ID and Percent).

Accepts VAT percentage (integer or Decimal) and tax category atom.

# `tax`

Generate tax category XML with optional exemption fields.

Includes TaxExemptionReasonCode and TaxExemptionReason when provided.

# `tax_sub_total`

Generate a TaxSubtotal XML element.

# `tax_totals`

Generate tax totals XML for all tax categories.

Groups details by VAT percentage and tax category, then generates TaxSubtotal elements.
VAT is calculated on the grouped subtotal to avoid rounding errors.

# `ubl_line_total`

Calculate UBL-compliant line total for a detail item.

Ensures consistency with AllowanceCharge calculations.

# `ubl_totals`

Calculate UBL-compliant totals with proper rounding for Peppol validation.

Ensures:
- BR-CO-15: TaxInclusiveAmount = TaxExclusiveAmount + TaxAmount
- BR-CO-10: LineExtensionAmount = Σ InvoiceLine/LineExtensionAmount
- PEPPOL-EN16931-R120: Line net amounts are correctly calculated

VAT is calculated by grouping lines with the same VAT rate, summing their totals,
then applying VAT to the sum. This prevents rounding errors from accumulating
when multiple lines have the same VAT rate.

Returns a map with:
- `:subtotal` - Sum of all line totals
- `:vat` - Sum of all VAT amounts
- `:grand_total` - Subtotal + VAT

# `vat_number`

Extract numeric VAT number (remove country code and non-digits).

---

*Consult [api-reference.md](api-reference.md) for complete listing*