ExCius.BillingReference (ExCius v0.3.2)

Billing Reference (BG-3) for Croatian e-Invoice (Fiskalizacija 2.0).

This module handles references to preceding invoices, which is critical for:

Corrective Invoices (P10/384) - Must reference the invoice being corrected
Credit Notes (381) - Must reference the invoice being credited
Debit Notes (383) - Must reference the invoice being debited

The BillingReference contains an InvoiceDocumentReference with:

ID: The number/identifier of the original invoice being referenced
IssueDate: The issue date of the original invoice

Reference: EN 16931-1:2017, Business Group BG-3 (PRECEDING INVOICE REFERENCE) Croatian CIUS-2025 Specification

Summary

Functions

new(attrs)

Creates a new BillingReference struct.

new!(attrs)

Creates a new BillingReference struct, raising on error.

required_for_business_process?(arg1)

Checks if a billing reference is required for the given business process.

required_for_invoice_type?(arg1)

Checks if a billing reference is required for the given invoice type and business process.

to_map(billing_ref)

Converts a BillingReference struct to a map suitable for XML generation.

validate(attrs)

Validates billing reference data without creating a struct.

Types

invoice_document_reference()

@type invoice_document_reference() :: %{
  :id => String.t(),
  optional(:issue_date) => Date.t() | String.t()
}

t()

@type t() :: %ExCius.BillingReference{
  invoice_document_reference: invoice_document_reference()
}

Functions

new(attrs)

Creates a new BillingReference struct.

Parameters

attrs - A map containing:
- :invoice_document_reference - A map with :id (required) and :issue_date (optional)

Examples

iex> ExCius.BillingReference.new(%{
...>   invoice_document_reference: %{
...>     id: "INV-2025-001",
...>     issue_date: ~D[2025-01-15]
...>   }
...> })
{:ok, %ExCius.BillingReference{
  invoice_document_reference: %{
    id: "INV-2025-001",
    issue_date: ~D[2025-01-15]
  }
}}

iex> ExCius.BillingReference.new(%{})
{:error, %{invoice_document_reference: "is required"}}

new!(attrs)

Creates a new BillingReference struct, raising on error.

Examples

iex> ExCius.BillingReference.new!(%{
...>   invoice_document_reference: %{id: "INV-2025-001", issue_date: ~D[2025-01-15]}
...> })
%ExCius.BillingReference{...}

required_for_business_process?(arg1)

Checks if a billing reference is required for the given business process.

Examples

iex> ExCius.BillingReference.required_for_business_process?(:p9)
true

iex> ExCius.BillingReference.required_for_business_process?(:p10)
true

iex> ExCius.BillingReference.required_for_business_process?(:p1)
false

required_for_invoice_type?(arg1)

Checks if a billing reference is required for the given invoice type and business process.

Credit notes (381), corrected invoices (384), and debit notes (383) require billing references. Business processes P9 (credit notes) and P10 (corrective invoices) also indicate a billing reference is expected.

Examples

iex> ExCius.BillingReference.required_for_invoice_type?(:credit_note)
true

iex> ExCius.BillingReference.required_for_invoice_type?(:corrected_invoice)
true

iex> ExCius.BillingReference.required_for_invoice_type?(:commercial_invoice)
false

to_map(billing_ref)

Converts a BillingReference struct to a map suitable for XML generation.

Examples

iex> ref = %ExCius.BillingReference{
...>   invoice_document_reference: %{id: "INV-001", issue_date: ~D[2025-01-15]}
...> }
iex> ExCius.BillingReference.to_map(ref)
%{
  invoice_document_reference: %{
    id: "INV-001",
    issue_date: ~D[2025-01-15]
  }
}

validate(attrs)

Validates billing reference data without creating a struct.

Returns :ok if valid, or {:error, errors} if invalid.

Examples

iex> ExCius.BillingReference.validate(%{
...>   invoice_document_reference: %{id: "INV-001"}
...> })
:ok

iex> ExCius.BillingReference.validate(%{})
{:error, %{invoice_document_reference: "is required"}}