Skip to content

Invoice Model

C signatures use the C API. See C and C++ bindings for ownership and build instructions. The declarations below come from the generated headers. C++ exposes the same types in namespace fatoora through fatoora/Type.hpp headers.

Core data types for building and inspecting invoices. See Decimal numbers and rounding for numeric inputs, calculation rules and binding representations.

InvoiceBuilder

Rust configuration methods consume and return the builder. Chain calls or assign back to the builder for conditional configuration. line_item appends; other configuration methods replace their corresponding values. build(self) moves owned fields into the invoice and consumes the builder on success or error.

C and Python keep mutable builder handles and their existing setter names. Setters validate their arguments before moving the builder; rejected arguments leave it available for correction. Building consumes the handle on success or validation failure.

let invoice = InvoiceBuilder::new(invoice_type)
    .id("INV-1")
    // Configure the remaining required fields.
    .build()?;

new

Create builder

Create a builder for a specific invoice type/subtype.

InvoiceBuilder::new(invoice_type: InvoiceType) -> InvoiceBuilder
InvoiceBuilder.new(invoice_type: InvoiceTypeKind, invoice_subtype: InvoiceSubType, original_invoice_id: Optional[str] = None, original_invoice_uuid: Optional[str] = None, original_invoice_issue_date: Optional[str] = None, original_invoice_reason: Optional[str] = None) -> InvoiceBuilder
#include "fatoora.h"

FatooraStatus fatoora_invoice_builder_new(const FatooraInvoiceOptions *options,
    FatooraInvoiceBuilder **out,
    FatooraError **error);

id

Set invoice ID
InvoiceBuilder::id(id: impl Into<String>) -> Self
InvoiceBuilder.set_id(invoice_id: str) -> None
#include "fatoora.h"

FatooraStatus fatoora_invoice_builder_set_id(FatooraInvoiceBuilder *self,
    const char *value,
    FatooraError **error);

uuid

Set invoice UUID
InvoiceBuilder::uuid(uuid: impl Into<String>) -> Self
InvoiceBuilder.set_uuid(uuid: str) -> None
#include "fatoora.h"

FatooraStatus fatoora_invoice_builder_set_uuid(FatooraInvoiceBuilder *self,
    const char *value,
    FatooraError **error);

issue_datetime

Set issue datetime
InvoiceBuilder::issue_datetime(value: impl Into<String>) -> Self
InvoiceBuilder.set_issue_datetime(issue_datetime: str) -> None
#include "fatoora.h"

FatooraStatus fatoora_invoice_builder_set_issue_datetime(FatooraInvoiceBuilder *self,
    const char *value,
    FatooraError **error);

currency

Set currency
InvoiceBuilder::currency(code: impl Into<String>) -> Self
InvoiceBuilder.set_currency(currency_code: str) -> None
#include "fatoora.h"

FatooraStatus fatoora_invoice_builder_set_currency(FatooraInvoiceBuilder *self,
    const char *value,
    FatooraError **error);

previous_invoice_hash

Set previous invoice hash
InvoiceBuilder::previous_invoice_hash(hash: impl Into<String>) -> Self
InvoiceBuilder.set_previous_invoice_hash(hash: str) -> None
#include "fatoora.h"

FatooraStatus fatoora_invoice_builder_set_previous_invoice_hash(FatooraInvoiceBuilder *self,
    const char *value,
    FatooraError **error);

invoice_counter

Set invoice counter
InvoiceBuilder::invoice_counter(counter: u64) -> Self
InvoiceBuilder.set_invoice_counter(counter: int) -> None
#include "fatoora.h"

FatooraStatus fatoora_invoice_builder_set_invoice_counter(FatooraInvoiceBuilder *self,
    uint64_t value,
    FatooraError **error);

payment_means_code

Set payment means code
InvoiceBuilder::payment_means_code(code: impl Into<String>) -> Self
InvoiceBuilder.set_payment_means_code(code: str) -> None
#include "fatoora.h"

FatooraStatus fatoora_invoice_builder_set_payment_means_code(FatooraInvoiceBuilder *self,
    const char *value,
    FatooraError **error);

vat_category

Set invoice VAT category
InvoiceBuilder::vat_category(category: VatCategory) -> Self
InvoiceBuilder.set_vat_category(category: VatCategory) -> None
#include "fatoora.h"

FatooraStatus fatoora_invoice_builder_set_vat_category(FatooraInvoiceBuilder *self,
    int32_t value,
    FatooraError **error);

seller

Set seller party
InvoiceBuilder::seller(seller: Seller) -> Self
InvoiceBuilder.set_seller(...) -> None
#include "fatoora.h"

FatooraStatus fatoora_invoice_builder_set_seller(FatooraInvoiceBuilder *self,
    const FatooraPartyOptions *options,
    FatooraError **error);

buyer

Set buyer party
InvoiceBuilder::buyer(buyer: Buyer) -> Self
InvoiceBuilder.set_buyer(...) -> None
#include "fatoora.h"

FatooraStatus fatoora_invoice_builder_set_buyer(FatooraInvoiceBuilder *self,
    const FatooraPartyOptions *options,
    FatooraError **error);

note

Set invoice note
InvoiceBuilder::note(note: InvoiceNote) -> Self
InvoiceBuilder.set_note(language: str, text: str) -> None
#include "fatoora.h"

FatooraStatus fatoora_invoice_builder_set_note(FatooraInvoiceBuilder *self,
    const char *language,
    const char *value,
    FatooraError **error);

allowance

Set allowance reason and amount
InvoiceBuilder::allowance(reason: impl Into<String>, amount: Decimal) -> Self
InvoiceBuilder.set_allowance(reason: str, amount: Decimal | str | int) -> None
#include "fatoora.h"

FatooraStatus fatoora_invoice_builder_set_allowance(FatooraInvoiceBuilder *self,
    const char *reason,
    const char *amount,
    FatooraError **error);

invoice_level_charge

Set invoice-level charge
InvoiceBuilder::invoice_level_charge(charge: Decimal) -> Self
InvoiceBuilder.invoice_level_charge(charge: Decimal | str | int) -> None
#include "fatoora.h"

FatooraStatus fatoora_invoice_builder_invoice_level_charge(FatooraInvoiceBuilder *self,
    const char *value,
    FatooraError **error);

invoice_level_discount

Set invoice-level discount
InvoiceBuilder::invoice_level_discount(discount: Decimal) -> Self
InvoiceBuilder.invoice_level_discount(discount: Decimal | str | int) -> None
#include "fatoora.h"

FatooraStatus fatoora_invoice_builder_invoice_level_discount(FatooraInvoiceBuilder *self,
    const char *value,
    FatooraError **error);

allowance_reason

Set allowance reason
InvoiceBuilder::allowance_reason(reason: impl Into<String>) -> Self
InvoiceBuilder.allowance_reason(reason: str) -> None
#include "fatoora.h"

FatooraStatus fatoora_invoice_builder_allowance_reason(FatooraInvoiceBuilder *self,
    const char *value,
    FatooraError **error);

flags

Set invoice flags
InvoiceBuilder::flags(flags: InvoiceFlags) -> Self
InvoiceBuilder.flags(flags: int) -> None
#include "fatoora.h"

FatooraStatus fatoora_invoice_builder_flags(FatooraInvoiceBuilder *self,
    int32_t value,
    FatooraError **error);

line_item

Add line item
InvoiceBuilder::line_item(item: LineItem) -> Self
InvoiceBuilder.add_line_item(description: str, quantity: Decimal | str | int, unit_code: str, unit_price: Decimal | str | int, vat_rate: Decimal | str | int, vat_category: VatCategory) -> None
#include "fatoora.h"

FatooraStatus fatoora_invoice_builder_add_line_item(FatooraInvoiceBuilder *self,
    const FatooraLineItemOptions *options,
    FatooraError **error);

build

Finalize invoice
InvoiceBuilder::build(self) -> Result<FinalizedInvoice, InvoiceError>
InvoiceBuilder.build() -> FinalizedInvoice
#include "fatoora.h"

FatooraStatus fatoora_invoice_builder_build(FatooraInvoiceBuilder *self,
    FatooraFinalizedInvoice **out,
    FatooraError **error);

Field Groups

id

  • Setter: InvoiceBuilder::id / InvoiceBuilder.set_id / fatoora_invoice_builder_set_id
  • Getters: FinalizedInvoice.id, SignedInvoice.id, fatoora_invoice_data_id, fatoora_invoice_data_id

uuid

  • Setter: InvoiceBuilder::uuid / InvoiceBuilder.set_uuid / fatoora_invoice_builder_set_uuid
  • Getters: FinalizedInvoice.uuid, SignedInvoice.uuid, fatoora_invoice_data_uuid, fatoora_invoice_data_uuid

issue_datetime

  • Setter: InvoiceBuilder::issue_datetime / InvoiceBuilder.set_issue_datetime / fatoora_invoice_builder_set_issue_datetime
  • Getters: FinalizedInvoice.issue_datetime, SignedInvoice.issue_datetime, fatoora_invoice_data_issue_datetime, fatoora_invoice_data_issue_datetime

currency

  • Setter: InvoiceBuilder::currency / InvoiceBuilder.set_currency / fatoora_invoice_builder_set_currency
  • Getters: FinalizedInvoice.currency, SignedInvoice.currency, fatoora_invoice_data_currency, fatoora_invoice_data_currency

previous_invoice_hash

  • Setter: InvoiceBuilder::previous_invoice_hash / InvoiceBuilder.set_previous_invoice_hash / fatoora_invoice_builder_set_previous_invoice_hash
  • Getters: FinalizedInvoice.previous_invoice_hash, SignedInvoice.previous_invoice_hash, fatoora_invoice_data_previous_invoice_hash, fatoora_invoice_data_previous_invoice_hash

invoice_counter

  • Setter: InvoiceBuilder::invoice_counter / InvoiceBuilder.set_invoice_counter / fatoora_invoice_builder_set_invoice_counter
  • Getters: FinalizedInvoice.invoice_counter, SignedInvoice.invoice_counter, fatoora_invoice_data_invoice_counter, fatoora_invoice_data_invoice_counter

payment_means_code

  • Setter: InvoiceBuilder::payment_means_code / InvoiceBuilder.set_payment_means_code / fatoora_invoice_builder_set_payment_means_code
  • Getters: FinalizedInvoice.payment_means_code, SignedInvoice.payment_means_code, fatoora_invoice_data_payment_means_code, fatoora_invoice_data_payment_means_code

vat_category

  • Setter: InvoiceBuilder::vat_category / InvoiceBuilder.set_vat_category / fatoora_invoice_builder_set_vat_category
  • Getters: FinalizedInvoice.vat_category, SignedInvoice.vat_category, fatoora_invoice_data_vat_category, fatoora_invoice_data_vat_category

Parties (seller, buyer)

  • Setters: InvoiceBuilder::seller, InvoiceBuilder::buyer and matching Python/C builder methods.
  • Getters: FinalizedInvoice.seller, FinalizedInvoice.buyer, SignedInvoice.seller, SignedInvoice.buyer, fatoora_invoice_data_seller, fatoora_invoice_data_buyer, fatoora_invoice_data_seller, fatoora_invoice_data_buyer

Notes and Allowance (note, allowance_reason, charge/discount)

  • Setters: set_note, set_allowance, invoice_level_charge, invoice_level_discount, allowance_reason and matching Python/C builder methods.
  • Getters: note, allowance_reason, invoice_level_charge, invoice_level_discount on finalized/signed invoices and fatoora_invoice_data_* getters on an owned snapshot.

Flags and Type

  • Setter: InvoiceBuilder::flags / InvoiceBuilder.flags / fatoora_invoice_builder_flags
  • Getters: flags, is_third_party, is_nominal, is_export, is_summary, is_self_billed, is_simplified, invoice_type_kind, invoice_sub_type on finalized/signed invoices and matching C getters.

Line Items and Totals

  • Setter: InvoiceBuilder::line_item / InvoiceBuilder.add_line_item / fatoora_invoice_builder_add_line_item
  • Getters: line_items, totals on finalized/signed invoices and C getters on owned InvoiceData, InvoiceLineItem, and InvoiceTotals snapshots.

C field getters operate on an owned InvoiceData snapshot obtained with fatoora_finalized_invoice_data or fatoora_signed_invoice_data. Check the result, read the fields, then call fatoora_invoice_data_free. Totals follow the same pattern with InvoiceTotals. Snapshots survive destruction of their invoice.

FinalizedInvoice

hash_base64

Get finalized invoice hash (Base64)
FinalizedInvoice::hash_base64(&self) -> Result<String, SigningError>
FinalizedInvoice.hash_base64() -> str
#include "fatoora.h"

FatooraStatus fatoora_finalized_invoice_hash_base64(const FatooraFinalizedInvoice *self,
    char **out,
    FatooraError **error);

sign

Sign finalized invoice
FinalizedInvoice::sign(self, signer: &InvoiceSigner) -> Result<SignedInvoice, SigningError>
FinalizedInvoice.sign(signer: Signer) -> SignedInvoice
#include "fatoora.h"

FatooraStatus fatoora_signer_sign(const FatooraSigner *self,
    FatooraFinalizedInvoice *invoice,
    FatooraSignedInvoice **out,
    FatooraError **error);

field accessors

Read finalized invoice fields

Accessors for identity, parties, references, flags, line items, and totals are available per field in Python and C.

FinalizedInvoice.id() -> str
FinalizedInvoice.uuid() -> str
FinalizedInvoice.issue_datetime() -> str
FinalizedInvoice.currency() -> str
FinalizedInvoice.previous_invoice_hash() -> str
FinalizedInvoice.invoice_counter() -> int
FinalizedInvoice.payment_means_code() -> str
FinalizedInvoice.vat_category() -> VatCategory
FinalizedInvoice.invoice_level_charge() -> Decimal
FinalizedInvoice.invoice_level_discount() -> Decimal
FinalizedInvoice.allowance_reason() -> Optional[str]
FinalizedInvoice.invoice_type_kind() -> InvoiceTypeKind
FinalizedInvoice.invoice_sub_type() -> InvoiceSubType
FinalizedInvoice.original_invoice_ref() -> Optional[OriginalInvoiceRef]
FinalizedInvoice.original_invoice_reason() -> Optional[str]
FinalizedInvoice.seller() -> Party
FinalizedInvoice.buyer() -> Optional[Party]
FinalizedInvoice.note() -> Optional[InvoiceNote]
FinalizedInvoice.line_items() -> list[InvoiceLineItem]
FinalizedInvoice.totals() -> InvoiceTotals
FinalizedInvoice.flags() -> set[InvoiceFlag]
FinalizedInvoice.is_third_party() -> bool
FinalizedInvoice.is_nominal() -> bool
FinalizedInvoice.is_export() -> bool
FinalizedInvoice.is_summary() -> bool
FinalizedInvoice.is_self_billed() -> bool
FinalizedInvoice.is_simplified() -> bool
FinalizedInvoice.xml() -> str
#include "fatoora.h"

FatooraStatus fatoora_finalized_invoice_data(const FatooraFinalizedInvoice *self,
    FatooraInvoiceData **out,
    FatooraError **error);

FatooraStatus fatoora_invoice_data_id(const FatooraInvoiceData *self,
    char **out,
    FatooraError **error);

FatooraStatus fatoora_invoice_data_uuid(const FatooraInvoiceData *self,
    char **out,
    FatooraError **error);

FatooraStatus fatoora_finalized_invoice_xml(const FatooraFinalizedInvoice *self,
    char **out,
    FatooraError **error);

FatooraStatus fatoora_invoice_data_line_items_len(const FatooraInvoiceData *self,
    size_t *out,
    FatooraError **error);

FatooraStatus fatoora_finalized_invoice_totals(const FatooraFinalizedInvoice *self,
    FatooraInvoiceTotals **out,
    FatooraError **error);

FatooraStatus fatoora_invoice_totals_tax_inclusive(const FatooraInvoiceTotals *self,
    char **out,
    FatooraError **error);

SignedInvoice

For exact XML preservation and consuming into_xml() access, see XML ownership.

xml

Get signed invoice XML
SignedInvoice::xml(&self) -> &str
SignedInvoice.xml() -> str
#include "fatoora.h"

FatooraStatus fatoora_signed_invoice_xml(const FatooraSignedInvoice *self,
    char **out,
    FatooraError **error);

to_xml_base64

Get signed XML as Base64
SignedInvoice::to_xml_base64(&self) -> String
SignedInvoice.to_xml_base64() -> str
#include "fatoora.h"

FatooraStatus fatoora_signed_invoice_to_xml_base64(const FatooraSignedInvoice *self,
    char **out,
    FatooraError **error);

hash_base64

Get signed invoice hash (Base64)
SignedInvoice::hash_base64(&self) -> Result<String, SigningError>
SignedInvoice.hash_base64() -> str
#include "fatoora.h"

FatooraStatus fatoora_signed_invoice_hash_base64(const FatooraSignedInvoice *self,
    char **out,
    FatooraError **error);

signature metadata accessors

Read signature metadata
SignedInvoice::invoice_hash(&self) -> &str
SignedInvoice::signature(&self) -> &str
SignedInvoice::public_key(&self) -> &str
SignedInvoice::zatca_key_signature(&self) -> Option<&str>
SignedProperties::issuer(&self) -> &str
SignedProperties::serial(&self) -> &str
SignedInvoice.invoice_hash() -> str
SignedInvoice.signature() -> str
SignedInvoice.public_key() -> str
SignedInvoice.zatca_key_signature() -> Optional[str]
SignedInvoice.cert_hash() -> str
SignedInvoice.signed_props_hash() -> str
SignedInvoice.signing_time() -> str
SignedInvoice.issuer() -> str
SignedInvoice.serial() -> str
#include "fatoora.h"

FatooraStatus fatoora_signed_invoice_invoice_hash(const FatooraSignedInvoice *self,
    char **out,
    FatooraError **error);

FatooraStatus fatoora_signed_invoice_signature(const FatooraSignedInvoice *self,
    char **out,
    FatooraError **error);

FatooraStatus fatoora_signed_invoice_public_key(const FatooraSignedInvoice *self,
    char **out,
    FatooraError **error);

FatooraStatus fatoora_signed_invoice_zatca_key_signature(const FatooraSignedInvoice *self,
    char **out,
    FatooraError **error);

FatooraStatus fatoora_signed_invoice_cert_hash(const FatooraSignedInvoice *self,
    char **out,
    FatooraError **error);

FatooraStatus fatoora_signed_invoice_signed_props_hash(const FatooraSignedInvoice *self,
    char **out,
    FatooraError **error);

FatooraStatus fatoora_signed_invoice_signing_time(const FatooraSignedInvoice *self,
    char **out,
    FatooraError **error);

FatooraStatus fatoora_signed_invoice_issuer(const FatooraSignedInvoice *self,
    char **out,
    FatooraError **error);

FatooraStatus fatoora_signed_invoice_serial(const FatooraSignedInvoice *self,
    char **out,
    FatooraError **error);

Address.new

district is the single city-district field and maps to XML cbc:CitySubdivisionName. Replace the removed subdivision field, accessor, and constructor argument with district, including in serialized address JSON. C callers must rebuild against the matching header and library.

Create address value
Address.new(
    country_code: str,
    city: str,
    street: str,
    building_number: str,
    postal_code: str,
    additional_street: Optional[str] = None,
    additional_number: Optional[str] = None,
    district: Optional[str] = None,
) -> Address
#include "fatoora.h"

FatooraStatus fatoora_address_new(const FatooraAddressOptions *options,
    FatooraAddress **out,
    FatooraError **error);

field accessors

Read signed invoice data fields

Signed invoices expose the same business-field accessors as finalized invoices, plus signature metadata.

SignedInvoice.id() -> str
SignedInvoice.uuid() -> str
SignedInvoice.issue_datetime() -> str
SignedInvoice.currency() -> str
SignedInvoice.previous_invoice_hash() -> str
SignedInvoice.invoice_counter() -> int
SignedInvoice.payment_means_code() -> str
SignedInvoice.vat_category() -> VatCategory
SignedInvoice.invoice_level_charge() -> Decimal
SignedInvoice.invoice_level_discount() -> Decimal
SignedInvoice.allowance_reason() -> Optional[str]
SignedInvoice.invoice_type_kind() -> InvoiceTypeKind
SignedInvoice.invoice_sub_type() -> InvoiceSubType
SignedInvoice.original_invoice_ref() -> Optional[OriginalInvoiceRef]
SignedInvoice.original_invoice_reason() -> Optional[str]
SignedInvoice.seller() -> Party
SignedInvoice.buyer() -> Optional[Party]
SignedInvoice.note() -> Optional[InvoiceNote]
SignedInvoice.line_items() -> list[InvoiceLineItem]
SignedInvoice.totals() -> InvoiceTotals
SignedInvoice.flags() -> set[InvoiceFlag]
SignedInvoice.is_third_party() -> bool
SignedInvoice.is_nominal() -> bool
SignedInvoice.is_export() -> bool
SignedInvoice.is_summary() -> bool
SignedInvoice.is_self_billed() -> bool
SignedInvoice.is_simplified() -> bool
#include "fatoora.h"

FatooraStatus fatoora_signed_invoice_data(const FatooraSignedInvoice *self,
    FatooraInvoiceData **out,
    FatooraError **error);

FatooraStatus fatoora_invoice_data_id(const FatooraInvoiceData *self,
    char **out,
    FatooraError **error);

FatooraStatus fatoora_invoice_data_uuid(const FatooraInvoiceData *self,
    char **out,
    FatooraError **error);

FatooraStatus fatoora_invoice_data_line_items_len(const FatooraInvoiceData *self,
    size_t *out,
    FatooraError **error);

FatooraStatus fatoora_signed_invoice_totals(const FatooraSignedInvoice *self,
    FatooraInvoiceTotals **out,
    FatooraError **error);

FatooraStatus fatoora_invoice_totals_tax_inclusive(const FatooraInvoiceTotals *self,
    char **out,
    FatooraError **error);

Supporting Types

Types

  • CountryCode, CurrencyCode, InvoiceTimestamp, InvoiceDate, VatId, OtherId.
  • InvoiceNote, OriginalInvoiceRef, LineItem, Party (Seller/Buyer roles).

See also: Invoice Signing Reference