Invora Invoicing API Guide¶

Invora is a multi-country electronic invoicing platform. It lets you create, manage, validate, and submit business documents to tax authorities across multiple jurisdictions from a single API. Whether you need to issue invoices in Saudi Arabia under ZATCA, send e-invoices across Europe via Peppol, or comply with Egypt's ETA system, the Invoicing API handles the regulatory complexity so your application does not have to.

This guide explains what the Invoicing API can do for you as a developer integrating invoicing into your application. It covers the document types you can work with, how documents move through their lifecycle, which countries and standards are supported, and the key workflows you will use day to day.

API Overview¶

The Invoicing API is organized into the following areas that together cover the complete invoicing lifecycle.

All document types are created and managed through a single DocumentsService. The categories below are a conceptual grouping of those document types, not separate services:

Document category (all via `DocumentsService`)	Document types
Financial Documents	Invoices, credit notes, debit notes, self-billed invoices, freight invoices
Commercial Documents	Purchase orders, quotations, order responses
Operational Documents	Despatch advices (delivery notes), receipt advices, reminders, statements

The remaining services each own a distinct part of the lifecycle:

Service	Purpose
Allowances	Discounts and rebates that reduce amounts
Charges	Surcharges and fees that increase amounts
Validation	Check documents for correctness before freezing, with auto-fix capabilities
PDF	Generate branded PDF renditions of any document
Regulations	Query available regulations, check submission status, retry failures
ZATCA	Saudi Arabia-specific onboarding and QR code operations
Settings	Tenant configuration: default currency, number prefixes, branding, self-party identity
Parties	Supplier and customer address book with import/export
People	Individual contact persons linked to parties
Code Lists / Code Items	Configurable reference data (unit codes, tax categories, payment methods)
Exchange Rates	Currency conversion rates with date-based lookup

Every service is available over both gRPC and REST (via gRPC-JSON transcoding). JSON field names use camelCase (for example, freezeImmediately in JSON corresponds to freeze_immediately in proto).

All documents are built on the UBL 2.1 (Universal Business Language) standard, giving you full interoperability with any system that speaks UBL XML.

Document Types¶

Financial Documents¶

Financial documents represent monetary obligations between parties. These are the core of any invoicing system.

Type	Business Use
Invoice	A request for payment from a supplier to a customer for goods or services delivered. The most common document type.
Credit Note	Reduces or cancels a previously issued invoice. Used for returns, billing corrections, or agreed discounts after the fact.
Debit Note	Increases the amount owed beyond the original invoice. Used for undercharges, additional fees, or price adjustments upward.
Self-Billed Invoice	An invoice created by the buyer (customer) rather than the seller. Used in consignment arrangements or when the buyer has better data about what was delivered.
Self-Billed Credit Note	A credit note issued by the buyer against a self-billed invoice.
Freight Invoice	A specialized invoice for freight and logistics charges, with carrier-specific fields.

Commercial Documents¶

Commercial documents represent the pre-sale negotiation and ordering process.

Type	Business Use
Order (Purchase Order)	A formal request from a buyer to a supplier to deliver goods or services. Typically initiates the order-to-cash cycle.
Quotation	A supplier's price proposal in response to a request. Contains pricing, terms, and a validity period. Can be converted into an order.
Order Response	The supplier's formal acceptance, rejection, or modification of a received order.

Operational Documents¶

Operational documents track fulfillment and post-sale activities.

Type	Business Use
Despatch Advice (Delivery Note)	Notification from the supplier that goods have been shipped. Lists what was sent, quantities, and shipping details.
Receipt Advice	Confirmation from the buyer that goods were received. Documents what arrived versus what was expected.
Reminder	A payment reminder sent to a customer for overdue invoices.
Statement	A periodic summary of all transactions between two parties over a date range, showing opening balance, transactions, and closing balance.

Document Lifecycle¶

Every document in Invora follows a defined lifecycle. Understanding this lifecycle is essential because certain operations are only available in specific states, and regulatory submission is triggered by state transitions.

Document State Model¶

A document's editability is tracked by a single editState field. Regulatory submission is tracked separately, per regulation, inside regulationMetadata.

editState — can the document be modified?

Value	Meaning
`EDIT_STATE_DRAFT`	Work in progress. Editable and deletable.
`EDIT_STATE_VALIDATED`	Passed validation. Still editable.
`EDIT_STATE_FROZEN`	Locked permanently. Regulation pipeline runs (signing, QR, submission).

Regulation submission is tracked independently of editState. Each active regulation has an entry in regulationMetadata.entries[regulationId] carrying a cross-regulation RegulationSubmissionStatus (ACCEPTED, ACCEPTED_WITH_WARNINGS, REJECTED, PENDING, ERROR, NOT_SUBMITTED), regulation-native metadata, diagnostics, and artifacts (signed XML, QR code, clearance response). See Regulation Metadata on Documents.

Delivery (Send) and payment are operations rather than fields on the document. Payment is owned by the billing surface; the invoicing document itself exposes only editState and regulationMetadata.

Key Lifecycle Rules¶

Only drafts can be edited or deleted. Once a document is frozen (EDIT_STATE_FROZEN), its content is locked permanently.
Freezing is the critical transition. This is when regulation processing happens. You can freeze a document explicitly with the Freeze endpoint, or set freezeImmediately: true on Create to do both in one call.
Correct a frozen document by issuing another. Frozen content cannot be edited; issue a credit note to lower the amount owed or a debit note to raise it.
Concurrency stamps prevent conflicts. Every mutation (update, freeze, send, etc.) requires the current concurrencyStamp from the document, ensuring no one else modified it since you last read it.

Regulation Support¶

Invora uses a per-country plugin architecture. Each regulation is identified by a string ID and operates independently. A single document can have multiple regulations active simultaneously (for example, a cross-border invoice might need both ZATCA and Peppol compliance).

Available Regulations¶

Regulation ID	Country/Standard	Authority	Submission Model
`zatca`	Saudi Arabia	ZATCA (Zakat, Tax and Customs Authority)	Clearance -- the tax authority must approve the invoice before it is valid. Blocking: the freeze operation waits for ZATCA's response.
`egy-eta`	Egypt	Egyptian Tax Authority (ETA)	Clearance -- similar to ZATCA, invoices must be cleared before issuance.
`peppol-*`	EU / International	OpenPeppol network	Network Delivery -- documents are submitted asynchronously via the Peppol network to the recipient's access point. Country-specific variants (e.g., `peppol-be`, `peppol-de`, `peppol-sg`).
`jo-*`	Jordan	Jordan Income and Sales Tax Department	Reporting -- invoices are reported to the tax authority asynchronously with a compliance deadline.
`uae-*`	UAE	Federal Tax Authority	Reporting -- similar reporting model to Jordan.

Submission Models Explained¶

Clearance (blocking): When you freeze a document, the API calls the tax authority in real time and waits for approval. The frozen document includes the authority's response (acceptance, digital stamp, or rejection). If rejected, the freeze fails and you must correct the document.
Network Delivery (async): The document is submitted to a delivery network (like Peppol) after freezing. Submission happens asynchronously. You can check the status via RegulationSubmissionStatus on the document's regulation metadata.
Reporting (async with deadline): The document is reported to the tax authority after freezing, but there is a regulatory deadline for reporting (e.g., within 24 hours of issuance). Submission is asynchronous.

Regulation Metadata on Documents¶

Every frozen document carries a regulationMetadata object with per-regulation entries. Each entry includes:

Generic status -- ACCEPTED, REJECTED, PENDING, ERROR, or ACCEPTED_WITH_WARNINGS (for cross-regulation queries)
Typed metadata -- Per-regulation status with native fields:
ZATCA: ZatcaSubmissionStatus (CLEARED, NOT_CLEARED, REPORTED, ACCEPTED_WITH_WARNING, etc.) + clearance ID, invoice hash
Egypt ETA: EgyptEtaSubmissionStatus (VALID, INVALID, REJECTED, CANCELLED) + submission ID, long ID
Peppol: PeppolSubmissionStatus (DELIVERED, ACKNOWLEDGED, FAILED) + message ID, recipient participant ID
Artifact hash -- For integrity verification. Artifact bytes are NOT inline — download via GetArtifact or ListDocumentArtifacts RPCs

QR Codes¶

Regulations like ZATCA require QR codes on invoices. When a document is frozen and submitted, the API generates the QR code automatically and exposes it as an artifact under the regulation's entry — regulationMetadata.entries["zatca"].artifacts — alongside the signed XML and clearance response. Artifact bytes are not inline; download them with the GetArtifact RPC using the artifact id.

Managing Regulation Status¶

The Regulations service provides operational endpoints for managing submissions:

List/Get Regulations -- Discover which regulations are available and their configuration.
Get Regulation Status -- Check whether your tenant is onboarded and active for a specific regulation.
Retry Submission -- If a submission failed due to a transient error, retry it without re-freezing the document.
Override Submission Status -- For administrative corrections, manually set the submission status of a document for a specific regulation (requires a reason).
Get Artifact -- Download the regulation-native artifact (signed XML, etc.) for a specific document and regulation.

ZATCA-Specific Operations¶

Saudi Arabia's ZATCA has dedicated endpoints for:

Onboarding -- Initiate the ZATCA integration by providing the OTP from the ZATCA portal and selecting the environment (sandbox, simulation, or production).
Integration Status -- Check whether your tenant is onboarded and in which environment.
QR Code Explanation -- Decode a ZATCA QR code and extract the embedded data (seller name, VAT number, amounts, signatures).

Key Workflows¶

1. Initial Setup¶

Before creating documents, configure your tenant:

Set up your self-party (Settings service) -- Define your organization's legal name, tax ID, address, and other UBL party details. This identity is used as the supplier on outgoing documents.
Upload branding assets -- Upload your logo, signature image, and stamp image for PDF generation.
Configure defaults -- Set your default currency, invoice/credit note/debit note number prefixes, and PDF display preferences.
Onboard with regulations -- For each country you operate in, complete the regulation onboarding (e.g., ZATCA onboarding with an OTP).
Set up your address book -- Create party records for your customers and suppliers using the Parties service. You can import them in bulk from CSV or XML.

2. Create and Issue an Invoice¶

Step-by-step:

Create a draft invoice -- Call Documents.Create with invoice content. You can provide the content as typed fields (structured UBL objects) or as raw XML for interoperability with legacy systems.
Edit as needed -- While in draft, update the invoice with Documents.Update. Use field masks to update specific sections without overwriting the entire document.
Validate before freezing -- Call Documents.Validate to check the document for errors. If issues are found, use Documents.Fix to auto-correct common problems (rounding errors, missing default values, etc.).
Freeze the invoice -- Call Documents.Freeze. This locks the content, sets editState to EDIT_STATE_FROZEN, and triggers the regulation pipeline (signing, QR generation, submission to tax authorities). The frozen document carries the per-regulation submission status in regulationMetadata.
Generate a PDF -- Call Pdf.Generate to create a branded PDF. Configure what to show (logo, signature, QR code, stamp, contact info, bank details).
Send to the recipient -- Call Documents.Send to record that the document has been delivered.

Shortcut: create-and-freeze in one call. Set freezeImmediately: true on the Create request to skip the draft stage entirely. The document is created, validated, frozen, and submitted to regulators in a single API call. This is ideal for automated invoice generation from billing systems.

3. Issue a Credit Note for a Correction¶

When you need to correct or partially reverse an invoice:

Create a credit note draft -- Call Documents.Create with credit note content, or Documents.Clone (POST /api/v2/documents/{source_key}/clone) to pre-populate a new draft from the original invoice. Reference the original invoice through the UBL BillingReference so the documents stay linked.
Adjust the credit note -- Modify the amounts, line items, or other details as needed.
Freeze and submit -- Freeze the credit note to lock it and submit it to tax authorities. The regulation pipeline handles the credit note just like an invoice.

4. Apply Allowances and Charges¶

Allowances (discounts) and charges (surcharges) can be applied at three levels:

Scope	Effect
Unit Price	Adjusts the price of a single unit before quantity multiplication.
Line Item	Applied to a specific line after quantity calculation.
Document	Applied to the document total, affecting all lines.

Workflow:

Create reusable allowance/charge templates -- Use the Allowances or Charges service to define named, reusable configurations (e.g., "10% Early Payment Discount", "Shipping Surcharge"). Optionally attach coupon codes.
Apply to documents -- When creating or updating a document, reference the allowance/charge in the UBL content. The UBL AllowanceCharge structure supports both percentage-based and fixed-amount adjustments.

5. Generate PDFs¶

PDFs are generated on demand with configurable options:

Per-document configuration -- Each PDF generation request lets you control: logo, signature, QR code, stamp, contact info, seller address, and bank info visibility.
Template support -- Optionally specify a template key for different PDF layouts.
Bulk generation -- Generate PDFs for multiple documents in a single call with Pdf.BulkGenerate.
Entry management -- List, retrieve, and delete previously generated PDFs. Each entry includes a download URL and an MD5 hash for integrity verification.

6. Handle Regulatory Submission Failures¶

When a regulation submission fails (network timeout, authority error, etc.):

Check the document's regulation metadata -- The regulationMetadata.entries[regulationId].status field shows ERROR or REJECTED. For detailed status, check the typed metadata (e.g., zatca.status = ZATCA_SUBMISSION_STATUS_NOT_CLEARED).
Retry the submission -- Call Regulations.RetrySubmission with the regulation ID and document key. This re-attempts the submission without requiring you to re-freeze the document.
Override if necessary -- In exceptional cases (manual approval from the authority, out-of-band resolution), use Regulations.OverrideSubmissionStatus to manually set the status. This requires a reason for audit purposes.

7. Work with the Full Order-to-Cash Cycle¶

The three document services together support the complete business document flow:

flowchart TD
    Q[Quotation<br/>Commercial] --> O[Order / Purchase Order<br/>Commercial]
    O --> OR[Order Response<br/>Commercial]
    OR --> DA[Despatch Advice / Delivery Note<br/>Operational]
    DA --> RA[Receipt Advice<br/>Operational]
    RA --> INV[Invoice<br/>Financial]
    INV --> CN[Credit Note / Debit Note<br/>Financial]
    CN --> REM[Reminder<br/>Operational]
    REM --> ST[Statement<br/>Operational]

Documents are linked through billing references and order references, allowing you to trace the full chain from quote to payment. Use the GetRelatedDocuments endpoint on any document to navigate these relationships.

8. Bulk and Streaming Operations¶

For high-volume scenarios, every document service supports three processing modes:

Mode	Use Case
Single	One document at a time. Simplest integration.
Bulk	Send a batch of documents in one request. The response contains per-item success/failure results. Ideal for periodic batch imports.
Streaming (bidirectional gRPC)	Client sends a stream of requests, server responds with a stream of results. Best for real-time high-throughput pipelines where you want to process documents as fast as possible without waiting for each batch to complete.

Bulk create requests support per-item freezeImmediately, letting you mix draft and immediate-freeze documents in a single batch.

Supporting Services¶

Parties (Address Book)¶

Manage your suppliers and customers:

Each party has a role (supplier, customer, or both) and full UBL-compliant details (legal name, tax ID, postal address, contacts).
Import from CSV, XML, or JSON to bulk-load your address book.
Export your parties in the same formats for backup or migration.
Filter by role, country, tax ID, or full-text search.

People (Contacts)¶

Manage individual contact persons, optionally linked to parties. Useful for tracking who at a customer organization handles invoices.

Code Lists and Code Items¶

Configurable reference data used across documents:

Code Lists are named collections (e.g., "unit-codes", "tax-categories", "payment-methods").
Code Items are the individual entries within a list (e.g., "KGM" for kilograms, "VAT" for value-added tax).
System-defined lists are read-only and maintained by the platform. You can create your own custom lists.

Exchange Rates¶

Manage currency conversion rates:

Create rate entries with source currency, target currency, rate, and effective date.
Look up rates for a specific currency pair on a given date. The API returns the most recent rate on or before the requested date, and indicates whether it was an exact match.

Validation¶

The Validation service is stateless -- you can validate documents without persisting them first. This is useful for client-side pre-validation before submitting to the API.

Validate individual invoices, credit notes, or debit notes, or use the generic ValidateDocument endpoint.
Auto-fix common issues with the Fix endpoints. The response includes a list of applied fixes with descriptions.
Bulk validate for batch checking.
Validate by key to check a persisted document without re-sending its content.

API Access Patterns¶

Input Flexibility¶

All document creation and update endpoints accept content in two formats:

Typed content -- Structured protobuf/JSON objects following the UBL schema. Provides full type safety and field-level validation.
Raw XML -- UBL XML string for interoperability with external systems that already produce XML. The API parses and validates the XML on ingestion.

Responses always include both formats: the typed content and the serialized XML. This means you can create documents with structured objects and still extract the XML for archival or forwarding to systems that expect it.

Real-Time Subscriptions¶

Document services offer gRPC streaming endpoints for real-time updates:

ListStream -- Subscribe to a filtered list and receive change notifications (additions, updates, removals, reordering) as they happen.
GetStream -- Subscribe to a specific document and receive updates whenever it changes.

These are useful for building dashboards or notification systems that react to document changes without polling.

Pagination and Filtering¶

All list endpoints use a consistent pattern:

Structured filters -- Type-safe filter conditions (creation/update/freeze date ranges, document type, edit state, branch, plus arbitrary UBL field filters).
Text search -- Fuzzy search across key, party names, notes, and other text fields.
Cursor-based pagination -- Use nextPageCursor from the response to fetch the next page.
Field masks -- Request only the fields you need to reduce payload size.
Sorting -- Multi-rule sorting on common fields (date, amount, sequence ID).

Concurrency Control¶

All mutation operations use optimistic concurrency via concurrencyStamp. Read the document, pass the stamp back on your update/freeze/cancel call, and the API rejects the operation if someone else modified the document in between. This prevents lost updates in multi-user scenarios.