Skip to main content
ShumoulShumoul Developer Portalplatform.shumoul.com
Version: Latest

1. Overview

1.1 What is the E-Invoicing Framework?​

Saudi Arabia's ZATCA (Zakat, Tax and Customs Authority) mandates electronic invoicing ("Fatoora") for all VAT-registered businesses, in two phases:

  • Phase 1 (Generation): invoices must be generated as structured UBL 2.1 XML with a QR code.
  • Phase 2 (Integration): invoices must additionally be cryptographically signed, hash-chained to the previous invoice, and either cleared (B2B, real-time, before delivery to the buyer) or reported (B2C, within 24 hours) to ZATCA's Fatoora platform via an onboarded, certificate-authenticated device.

Shumoul.Framework.EInvoicing is the Shumoul platform's implementation of the full Phase 2 mechanic set: UBL generation, the previous-invoice-hash (PIH) chain, QR/TLV encoding, ECDSA (secp256k1) digital signing, the OTP-based Compliance/Production CSID onboarding lifecycle, and both clearance and reporting submission flows.

1.2 Where it lives​

Unlike the Notification Framework, Background Jobs Framework, and WhatsApp Integration Library — each its own standalone Git repository — E-Invoicing has no standalone repository. It lives entirely inside E:\SaaS\Shumoul.Framework\, the same repository as the platform's other Shumoul.Framework.* base packages, as four NuGet-packaged projects plus one test project, built and versioned via the same release-framework-packages.ps1 workflow used for the Framework's other packages.

ProjectRole
Shumoul.Framework.EInvoicingCore SDK — UBL model, ZATCA portal client, signing, QR, onboarding — for single-tenant/ERP-host use
Shumoul.Framework.EInvoicing.ApiThin MVC controllers (api/EInvoicing/*) wrapping the core SDK — the variant actually consumed by Shumoul.Saas.Api
Shumoul.Framework.EInvoicing.TenancyA near-line-for-line duplicate of the core SDK, for SaaS/multi-tenant host use
Shumoul.Framework.EInvoicing.TenancyApiThin controllers (api/Saas/EInvoicing/*) over the Tenancy SDK — consumed by Shumoul.MultiTenancyApi

Plus Shumoul.Framework.EInvoicing.Test — 217 xUnit test cases covering only the non-Tenancy validators; the Tenancy fork has no test coverage of its own.

1.3 Who consumes it​

ConsumerPackageRole
Shumoul.Saas.Api (Shumoul.Infrastructure.csproj)Shumoul.Framework.EInvoicing.ApiERP host — consumes via PackageReference only, zero project references
Shumoul.MultiTenancyApi (Shumoul.Framework.MultiTenancy.Api.csproj)Shumoul.Framework.EInvoicing.TenancyApiMulti-tenant host — consumes the Tenancy fork the same way

1.4 What it is not (yet)​

Compared to the platform's three certified/split subsystems, three things are confirmed absent:

  • No ERP business workflow calls into it. A repository-wide search of every Shumoul.Api controller and Shumoul.Application service for ZATCA-related types found zero matches — SalesInvoiceService has no awareness of IInvoiceProcessFlowService. The only way to reach the SDK today is the standalone POST /api/EInvoicing/Generate endpoint, called by whatever external caller already has a fully-formed UblInvoiceDto.
  • No ERP-owned integration/business layer exists between the ERP and the SDK, unlike WhatsApp Integration's TenantWhatsAppSender/WhatsAppOtpMessageService pattern. The SDK's own generic controllers are the only entry point.
  • No background job, retry mechanism, or notification integration exists anywhere in the e-invoicing flow. Submission is fully synchronous, in-request. See Chapter 12 — Known Limitations.

1.5 Key numbers​

  • 4 production projects + 1 test project, all net9.0, package version 1.0.48 (post Phase 0.2).
  • 217 test cases, validation rules only.
  • 3 controllers, 12 endpoints, all [Authorize]-only — no [MustHavePermission] gating, a deviation from every other Shumoul controller convention (see Chapter 5).
  • 0 background jobs. Submission is fully synchronous, in-request.

1.6 Certification status​

Status: Framework Candidate. This is deliberately not "Golden Reference" and not "Certified." The Notification Framework and Background Jobs Framework hold Level 3 / Golden Reference / LTS certification; E-Invoicing does not, and this documentation does not claim otherwise. Concretely, as of this writing:

  • No standalone repository exists for it (unlike all three certified/split subsystems).
  • No ADR documents its packaging or boundary decisions (WhatsApp has ADR-001; E-Invoicing has none).
  • The Tenancy fork is a duplicated copy that has already drifted from its source in confirmed, security-relevant ways — not a shared-core-plus-adapter design.
  • It has no ERP-owned business integration layer and is not wired into any real Sales/Purchase invoice workflow.
  • Certification (Level 1 → 2 → 3, Golden Reference designation) has not started and is not scheduled by this documentation effort.

What has happened: a Phase 0 architecture discovery, a Phase 0.1 security verification, and a Phase 0.2 critical-fix pass that closed the highest-severity confirmed defects (see Chapter 7 — Security). Publishing this documentation is not a certification step and does not change this status.

1.7 Relationship to the other frameworks​

No package-level dependency exists between E-Invoicing and the Notification Framework, Background Jobs Framework, or WhatsApp Integration, in either direction — confirmed by direct dependency search. The only external system E-Invoicing talks to is ZATCA's Fatoora platform itself, over HTTPS.