ExCius.OrderReference (ExCius v0.3.2)

View Source

Order Reference (BT-13, BT-14) for Croatian e-Invoice (CIUS-2025).

This module handles references to purchase orders and sales orders:

  • BT-13 (Buyer Order Reference): The buyer's purchase order number
  • BT-14 (Sales Order Reference): The seller's sales order/quotation number

These fields are independent and can exist in any combination:

  • Both: Buyer sends a purchase order referencing seller's quotation
  • Only BT-13: Direct order from buyer without prior quotation
  • Only BT-14: Buyer accepted quotation but didn't send their own order number
  • Neither: No order reference needed

The OrderReference maps to UBL 2.1 structure:

  • cac:OrderReference
    • cbc:ID - Buyer's order reference (BT-13)
    • cbc:SalesOrderID - Seller's order/quotation reference (BT-14)

Reference: EN 16931-1:2017, BT-13 (Purchase order reference) and BT-14 (Sales order reference) Croatian CIUS-2025 Specification

Summary

Types

t()

Functions

new(attrs)

Creates a new OrderReference struct.

new!(attrs)

Creates a new OrderReference struct, raising on error.

should_generate?(attrs)

Checks if an order reference should be generated based on provided data.

to_map(order_ref)

Converts an OrderReference struct to a map suitable for XML generation.

validate(attrs)

Validates order reference data without creating a struct.

Types

t()

@type t() :: %ExCius.OrderReference{
  buyer_reference: String.t() | nil,
  sales_order_id: String.t() | nil
}

Functions

new(attrs)

Creates a new OrderReference struct.

Parameters

  • attrs - A map containing:
    • :buyer_reference - BT-13: Buyer's purchase order number (optional)
    • :sales_order_id - BT-14: Seller's sales order/quotation number (optional)

At least one of the fields must be present.

Examples

iex> ExCius.OrderReference.new(%{
...>   buyer_reference: "PO-2025-001",
...>   sales_order_id: "QUO-2025-100"
...> })
{:ok, %ExCius.OrderReference{
  buyer_reference: "PO-2025-001",
  sales_order_id: "QUO-2025-100"
}}

iex> ExCius.OrderReference.new(%{buyer_reference: "PO-2025-001"})
{:ok, %ExCius.OrderReference{buyer_reference: "PO-2025-001", sales_order_id: nil}}

iex> ExCius.OrderReference.new(%{sales_order_id: "QUO-2025-100"})
{:ok, %ExCius.OrderReference{buyer_reference: nil, sales_order_id: "QUO-2025-100"}}

iex> ExCius.OrderReference.new(%{})
{:error, %{order_reference: "at least one of buyer_reference (BT-13) or sales_order_id (BT-14) is required"}}

new!(attrs)

Creates a new OrderReference struct, raising on error.

Examples

iex> ExCius.OrderReference.new!(%{buyer_reference: "PO-2025-001"})
%ExCius.OrderReference{buyer_reference: "PO-2025-001", sales_order_id: nil}

should_generate?(attrs)

Checks if an order reference should be generated based on provided data.

Returns true if at least one of buyer_reference or sales_order_id is present.

Examples

iex> ExCius.OrderReference.should_generate?(%{buyer_reference: "PO-001"})
true

iex> ExCius.OrderReference.should_generate?(%{})
false

iex> ExCius.OrderReference.should_generate?(nil)
false

to_map(order_ref)

Converts an OrderReference struct to a map suitable for XML generation.

Examples

iex> ref = %ExCius.OrderReference{
...>   buyer_reference: "PO-001",
...>   sales_order_id: "QUO-001"
...> }
iex> ExCius.OrderReference.to_map(ref)
%{buyer_reference: "PO-001", sales_order_id: "QUO-001"}

validate(attrs)

Validates order reference data without creating a struct.

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

Examples

iex> ExCius.OrderReference.validate(%{buyer_reference: "PO-001"})
:ok

iex> ExCius.OrderReference.validate(%{sales_order_id: "QUO-001"})
:ok

iex> ExCius.OrderReference.validate(%{})
{:error, %{order_reference: "at least one of buyer_reference (BT-13) or sales_order_id (BT-14) is required"}}