13. FAQ

Is the E-Invoicing Framework a Golden Reference module, like Notification or Background Jobs? No. Its status is Framework Candidate. It has no standalone repository, no ADR, no ERP-owned integration layer, and certification has not started. See Chapter 1 — Overview § 1.6.

Is it safe to use in production today? The Critical/High security defects confirmed in Phase 0/0.1 (auth not attached, secrets logged in plaintext, an unpermissioned OTP-read endpoint, a path-traversal risk) were fixed in Phase 0.2 — see Chapter 7 — Security for exactly what changed and what remains open (plaintext storage at rest, no test coverage of the cryptographic core, and the items in Chapter 12 — Known Limitations). This documentation does not certify the framework as production-ready; it summarizes what is and isn't fixed.

Does approving a Sales Invoice in the ERP automatically submit it to ZATCA? No. No Sales/Purchase invoice service calls into this SDK. The only way to submit an invoice is a direct call to POST /api/EInvoicing/Generate with an already-built UblInvoiceDto. See Chapter 1 — Overview § 1.4.

If a ZATCA submission fails, will it retry automatically? No. There is no retry mechanism, no background job, and no queue. The original caller receives a synchronous Rejected result or an HTTP 500 and is responsible for deciding whether to retry. See Chapter 4 — Runtime Flow § 4.5.

Will anyone be notified if an invoice is rejected or a certificate is about to expire? No. No notification of any kind fires anywhere in the e-invoicing flow — not email, SMS, WhatsApp, or in-app. See Chapter 12 — Known Limitations § 12.3.

Why does the core SDK and the Tenancy fork behave slightly differently in a few places? The Tenancy fork (Shumoul.Framework.EInvoicing.Tenancy) is a duplicated copy of the core SDK, not a shared- core-plus-adapter design, and it has already drifted from its source in confirmed ways (an OTP-logging difference, a CSR field OID difference, and others). See Chapter 11 — Technical Debt § 1.

Which package do I reference — .EInvoicing.Api or .EInvoicing.TenancyApi? Shumoul.Saas.Api (the single-tenant ERP host) references Shumoul.Framework.EInvoicing.Api. Shumoul.MultiTenancyApi references Shumoul.Framework.EInvoicing.TenancyApi. Both expose the same 12 endpoints under different route prefixes (api/EInvoicing/* vs. api/Saas/EInvoicing/*). See Chapter 3 — Package Structure and Chapter 5 — Controllers & Endpoints § 5.5.

Do the EInvoicing endpoints use the platform's usual [MustHavePermission] permission gating? No. All 12 endpoints are [Authorize]-only (authenticated, not permission-gated) — a confirmed deviation from every other Shumoul controller convention. See Chapter 5 — Controllers & Endpoints.

Where does the OTP come from during onboarding? The tenant admin retrieves it directly from ZATCA's own portal, out of band, and supplies it as an HTTP header on the onboarding call. It is never sourced from configuration. See Chapter 9 — Onboarding § 9.1.

Can I see the OTP again after I've entered it? No, not through the API. As of Phase 0.2, GET api/EInvoicing/Settings/Integration redacts the OTP field to null in its response. See Chapter 7 — Security § 7.4.

Is the private key encrypted at rest? No. It is stored as a plaintext string in the same generic AppSetting table every other tenant setting uses, with no encryption applied at the persistence layer. This was not changed by Phase 0.2 — see Chapter 7 — Security § 7.6.