ExCius.RequestParams (ExCius v0.3.2)
View SourceValidates and formats input parameters for UBL 2.1 Invoice generation.
Ensures all required fields for a UBL 2.1 invoice are present and properly formatted, based on the Croatian e-Invoice (CIUS-2025) specification.
Required Fields
:id- Invoice identifier (string):issue_datetime- Date and time of issue (ISO 8601 string, DateTime, or NaiveDateTime):currency_code- Document currency, only "EUR" supported (string):supplier- Supplier party information (map):customer- Customer party information (map):tax_total- Tax total information (map):legal_monetary_total- Monetary totals (map):invoice_lines- List of invoice lines (list)
Optional Fields
:business_process- Business process, defaults to :p1 (atom/string). SeeExCius.Enums.BusinessProcessfor all values (P1-P12, P99):invoice_type_code- Type of invoice, defaults to "commercial_invoice" (atom/string):due_date- Payment due date (Date or ISO 8601 string):delivery_date- Actual delivery date (Date or ISO 8601 string):invoice_period_start- Invoice period start date (Date or ISO 8601 string):invoice_period_end- Invoice period end date (Date or ISO 8601 string):payment_method- Payment information (map):notes- List of free-form notes (list of strings):attachments- List of embedded document attachments (list of maps):allowance_charges- List of document-level allowances/charges (list of maps):billing_reference- Reference to preceding invoice (map), required for credit notes (381), corrected invoices (384), and debit notes (383):order_reference- Reference to purchase order and/or sales order (map), see Order Reference Structure below:vat_cash_accounting- VAT cash accounting flag for Croatian "Obračun PDV po naplati" (boolean or string):hr_tax_extension- Croatian HRFISK20Data tax extension for exempt/out-of-scope scenarios (boolean, generates HRTaxTotal):out_of_scope_amount- Amount outside VAT scope for HRLegalMonetaryTotal extension (string, e.g., "0.00")
Billing Reference Structure (BG-3)
Required for Corrective Invoices (P10/384), Credit Notes (381), and Debit Notes (383).
The :billing_reference map must contain:
:invoice_document_reference- A map with::id- The number/identifier of the original invoice being referenced (required):issue_date- The issue date of the original invoice (optional, Date or ISO 8601 string)
Order Reference Structure (BT-13, BT-14)
Optional reference to purchase orders and sales orders/quotations.
The :order_reference map may contain:
:buyer_reference- BT-13: The buyer's purchase order number (optional):sales_order_id- BT-14: The seller's sales order or quotation number (optional)
At least one of these fields must be present when order_reference is provided.
Scenarios:
- Both fields: Buyer's purchase order references seller's quotation
- Only buyer_reference: Direct order from buyer without prior quotation
- Only sales_order_id: Buyer accepted quotation but didn't provide their order number
- Neither (nil): No order reference in the invoice
Allowance/Charge Structure (Document Level)
Each allowance/charge in the :allowance_charges list requires:
:charge_indicator- Boolean.false= Discount/Allowance,true= Charge/Surcharge (required):amount- Decimal string for the total amount (required):allowance_charge_reason_code- Code from UNTDID 5189 (allowances) or 7161 (charges) (optional):allowance_charge_reason- Text description (optional):multiplier_factor_numeric- Percentage as decimal (optional):base_amount- Base amount the percentage applies to (optional):tax_category- Tax category map (required for document level)::id- Tax category code (e.g., :standard_rate, :exempt, :outside_scope):percent- Tax percentage:tax_scheme_id- Tax scheme (e.g., :vat):tax_exemption_reason- (optional) Reason for exemption (Croatian HR extension):tax_exemption_reason_code- (optional) Code for exemption reason
Allowance/Charge Structure (Line Level)
Line-level allowances/charges in invoice lines use the same structure but WITHOUT :tax_category
(they inherit tax settings from the line item). Add them as :allowance_charges within each invoice line.
Tax Category Structure
Tax categories in :tax_subtotals and :classified_tax_category support:
:id- Tax category code (e.g., "standard_rate", "reverse_charge", "exempt"):percent- Tax percentage (number):tax_scheme_id- Tax scheme identifier (e.g., "vat"):tax_exemption_reason- (optional) Reason for tax exemption, required for reverse_charge (AE) and exempt (E) categories
Attachment Structure
Each attachment in the :attachments list requires:
:id- Document reference identifier (string, e.g., "1", "2"):filename- Name of the attached file (string, e.g., "invoice.pdf"):mime_code- MIME type of the attachment (string, e.g., "application/pdf"):content- Base64-encoded content of the file (string)
Supplier Structure
Supplier requires:
:oib- Croatian OIB (11-digit string):registration_name- Legal name (string):postal_address- Address map with:street_name,:city_name,:postal_zone,:country_code:party_tax_scheme- Tax scheme map with:company_id,:tax_scheme_id:seller_contact- Operator information (required for Croatian CIUS compliance)::id- Operator's OIB (HR-BT-5):name- Operator's name (HR-BT-4)
Customer Structure
Customer requires:
:oib- Croatian OIB (11-digit string):registration_name- Legal name (string):postal_address- Address map with:street_name,:city_name,:postal_zone,:country_code:party_tax_scheme- Tax scheme map with:company_id,:tax_scheme_id
Summary
Functions
Creates and validates UBL 2.1 invoice parameters from an input map.
Validates UBL 2.1 invoice parameters.
Functions
Creates and validates UBL 2.1 invoice parameters from an input map.
Returns {:ok, validated_params} on success or {:error, errors} on validation failure.
Examples
iex> params = %{
...> id: "INV-001",
...> issue_datetime: "2025-05-01T12:00:00",
...> currency_code: "EUR",
...> supplier: %{
...> oib: "12345678901",
...> registration_name: "Supplier d.o.o.",
...> postal_address: %{
...> street_name: "Street 1",
...> city_name: "Zagreb",
...> postal_zone: "10000",
...> country_code: "HR"
...> },
...> party_tax_scheme: %{
...> company_id: "HR12345678901",
...> tax_scheme_id: "vat"
...> },
...> seller_contact: %{
...> id: "12345678901",
...> name: "Operator1"
...> }
...> },
...> customer: %{
...> oib: "11111111119",
...> registration_name: "Customer d.o.o.",
...> postal_address: %{
...> street_name: "Street 2",
...> city_name: "Rijeka",
...> postal_zone: "51000",
...> country_code: "HR"
...> },
...> party_tax_scheme: %{
...> company_id: "HR11111111119",
...> tax_scheme_id: "vat"
...> }
...> },
...> tax_total: %{
...> tax_amount: "25.00",
...> tax_subtotals: [
...> %{
...> taxable_amount: "100.00",
...> tax_amount: "25.00",
...> tax_category: %{id: "standard_rate", percent: 25, tax_scheme_id: "vat"}
...> }
...> ]
...> },
...> legal_monetary_total: %{
...> line_extension_amount: "100.00",
...> tax_exclusive_amount: "100.00",
...> tax_inclusive_amount: "125.00",
...> payable_amount: "125.00"
...> },
...> invoice_lines: [
...> %{
...> id: "1",
...> quantity: 1.0,
...> unit_code: "piece",
...> line_extension_amount: "100.00",
...> item: %{
...> name: "Product",
...> classified_tax_category: %{id: "standard_rate", percent: 25, tax_scheme_id: "vat"},
...> commodity_classification: %{item_classification_code: "73211200", list_id: "CG"}
...> },
...> price: %{price_amount: "100.00"}
...> }
...> ]
...> }
iex> {:ok, result} = ExCius.RequestParams.new(params)
iex> result.id
"INV-001"
iex> result.issue_date
~D[2025-05-01]
iex> result.issue_time
~T[12:00:00]
iex> {:error, errors} = ExCius.RequestParams.new(%{})
iex> errors.id
"is required"Validates UBL 2.1 invoice parameters.
This function is called automatically by new/1 but can be used separately
if you want to validate params that have already been atomized and have defaults set.