ZuloOne
English
CabinetAccount
Sign in
Menu

🧾 E-invoice envelope

Updated

ZuloOne keeps the country-neutral e-invoice document in Tax and lets each country package fill the legal XML, signature and channel details.

← Business process wiki

How the process works#

The core object is TaxDocument: a sealed envelope with the source document, legal entity, authority, document kind, country document class, UUID, payload, hash, external id, and status. Country packages decide when to create the envelope and what to put in Payload.

The country-neutral states are:

State Meaning
Draft Envelope exists but is not yet released to the authority channel.
Issued The package has completed the payload and queued or prepared sending.
Cleared The authority accepted a clearance-style document.
Reported The authority accepted a reporting-style document.
Rejected The authority or channel rejected the envelope; Rejection reason holds the text when available.

Core does not block handing a document to the buyer. It exposes IEInvoiceRelease; a country package wraps it. Saudi Arabia is the delivered package: a Standard invoice is blocked until the TaxDocument is Cleared, while a Simplified invoice can be handed over after Issued and is reported after the fact.

Settings#

Tax document envelope#

Open Ribbon → Tax → Documents → Tax documents to inspect envelopes. Users normally do not create them by hand.

Field Values and behaviour
Legal entity The issuer. Empty is allowed in core but country packages usually need it.
Authority Optional authority reference stamped by an outcome service.
Source type / Source Required source object name and source record id. Examples are SalesRealization, SalesCreditNote, and SalesDebitNote in the Saudi package.
Kind Required generic kind, such as INVOICE, CREDIT_NOTE, or DEBIT_NOTE.
Document class Optional country refinement, for example Saudi Standard or Simplified. Empty is valid for a country without that taxonomy.
UUID Required envelope UUID.
External id Optional id returned by the outbound queue or authority channel.
Chain counter Optional country sequence. Saudi uses it as ICV per legal entity.
Previous hash / Invoice hash Optional country chain values. Empty is valid for regimes without chaining.
Payload Country payload, usually XML or JSON. Core stores it as text and does not interpret it.
Rejection reason Optional authority reason copied to the envelope when rejected or suspended.

Authority connection#

Open Ribbon → Tax → Settings → Authority connections. The country package reads the row for the legal entity to find the logical connection, credentials reference, environment, and mock rejection flag. Secrets stay in server configuration; do not store private keys or tokens in metadata.

Country settings#

Country-specific settings live under the localization package, not in the core envelope. For Saudi Arabia, see ZATCA setup. For Ukraine, see the local e-invoice page under wiki/business/localization/ukraine/.

Example with numbers#

A Saudi invoice has one line: net 1,000.00 SAR, VAT 15%, gross 1,150.00 SAR.

Input Envelope result
Buyer has a VAT registration number Document class = Standard; channel = clearance; buyer release is blocked until Cleared.
Buyer has no VAT registration number Document class = Simplified; channel = reporting; buyer release is allowed after Issued.
Source line amount Payload totals: taxable 1,000.00, VAT 150.00, payable 1,150.00.
Legal entity chain counter previous value 42 New Chain counter is 43, Previous hash stores the prior hash, Invoice hash stores the current payload hash.

The same core envelope can also represent a credit note or debit note. The Saudi package uses CREDIT_NOTE and DEBIT_NOTE and writes references to the original invoice in the payload.

Boundaries and edge cases#

  • TaxDocument is country-blind. Do not put Saudi, Ukrainian or any other legal rule into core setup.
  • The payload is immutable evidence after clearance/reporting. Correct a source invoice with a credit note or debit note, not by editing the envelope.
  • A missing channel does not delete the envelope. The payload remains on the TaxDocument for retry or support.
  • Core tax calculation and e-invoice are related but separate. TaxCalculation explains the tax ledger; TaxDocument is the authority-facing envelope.

What is posted#

TaxDocument itself does not post money to the general ledger. The taxable amount, receivable, VAT and revenue are already posted by the source document and TaxCalculation. The e-invoice process writes the envelope status and, through the outbound gateway, authority outcomes.

What's not there yet#

  • The country-neutral core has the envelope and service seam, not a universal e-invoice format.
  • Saudi: live gw-fatoora, full schematron validation and C14N 1.1 are not in the delivered channel.
  • Saudi credit and debit notes carry one VAT category for the whole note. Invoices support mixed rates per line — Saudi Arabia.
  • There is no generic end-user button to resend any envelope to any authority.

Same topic for other readers: User

Where next#

Was this page helpful?