Electronic Fiscal Taxing

This engineering skill builds the software boundary between a commercial system and an electronic fiscal authority. It supports one-client deployments and multi-tenant systems without mixing tax identities, credentials, devices, catalogues, queues, or evidence. It is general by design; Uganda EFRIS is the detailed reference implementation.

Prerequisites

Load system-architecture-design, api-design-first, database-design-engineering, distributed-systems-patterns, reliability-engineering, observability-monitoring, and vibe-security-skill as applicable. For accounting, tax, or statutory output, also load the external chwezi-accounting-doctrine electronic fiscal taxing skill and the finance quality gate.

Use When

• An ERP, POS, billing, e-commerce, or mobile-backed system must fiscalise invoices, receipts, credit notes, debit notes, or cancellations.
• A provider requires signed/encrypted requests, device registration, rotating keys, acknowledgements, or authority-specific dictionaries.
• A system must support multiple tenants, each with a distinct TIN/tax ID, fiscal profile, branch/device mapping, and credentials.
• A remote fiscal service needs an outbox, idempotent retries, dead-letter, replay, reconciliation, or controlled offline mode.
• A mobile client needs fiscal status and receipt artefacts without direct access to authority credentials.

Do Not Use When

Do not use for tax-law interpretation without the accounting doctrine and current source register, for generic payment integrations, or for visual receipt/UI styling without the design engine. Do not call a third-party fiscal API directly from an untrusted browser or mobile client.

Inputs

If the technical pack or credentials are absent, build contracts and test fixtures only; block production activation and mark the gap explicitly.

Outputs

• jurisdiction-neutral fiscal port and adapter contract;
• tenant/client fiscal-profile and isolation map;
• versioned API/OpenAPI and error/idempotency contract;
• schema and expand-contract migration plan;
• canonical fiscal-document builder and validation rules;
• outbox/queue/retry/dead-letter/replay/reconciliation design;
• security, secrets, audit, observability, runbook, rollback, and UAT pack;
• client/mobile read model that exposes status and authority artefacts safely.

Acceptance requires executable or recorded contract evidence, negative tenant tests, duplicate/replay tests, redacted evidence, rollback instructions, and an explicit release state.

Non-negotiables

1. The authenticated session or service context determines tenant scope; never accept tenant_id, TIN, or fiscal profile from a request body/query as the authority for routing.
2. A single-client deployment may use an implicit profile, but the same profile interface must exist so it can be isolated later.
3. Every fiscal side effect has a stable tenant-scoped idempotency key. A timeout is an unknown result; reconcile before retrying.
4. Store raw authority responses only under explicit retention and redaction rules. Never log private keys, tokens, passwords, or symmetric keys.
5. Provider FDN/verification/QR artefacts are persisted atomically with the fiscal result and are never fabricated by a fake client in production.
6. Online, authority-approved offline, manual exception, rejected, and disabled states are distinct. Offline is bounded by current authority rules.
7. A queue is at-least-once unless the provider proves otherwise. Workers must be concurrency-safe, bounded, observable, replayable, and quarantine poison messages.
8. A mobile app consumes ERP fiscal projections; it does not contain URA credentials/private keys or become a second fiscalisation writer.

Decision Rules

Core Workflow

1. Inventory writers and ownership. Find every invoice, receipt, payment, stock, correction, print, queue, and mobile sync path; select one canonical fiscalisation hook.
2. Define the domain port. Use provider-neutral commands/results for fiscalise, query, correct, cancel, sync catalogue, and reconcile. Preserve provider codes and payload hashes alongside normalized states.
3. Prove identity isolation. Resolve tenant/profile from trusted auth, validate branch/device/product ownership, and test wrong-tenant requests as indistinguishable not-found outcomes.
4. Design contract first. Specify request/response schemas, auth, version, time, idempotency, rate limits, errors, telemetry, and consumer projections.
5. Build durable state. Add additive schema changes, unique keys, immutable evidence, outbox claims, retry policy, dead-letter, replay authorization, and retention.
6. Implement adapter. Keep EFRIS cryptography, envelope, dictionary IDs, endpoint, and response parsing inside the Uganda adapter; do not leak them through domain or mobile APIs.
7. Integrate commercial paths. Route POS, manual, order, and agent sales through the canonical service; preserve accounting/stock transaction truth.
8. Verify and release. Run unit, contract, integration, failure, isolation, offline, load, security, migration, UAT, and rollback checks. Activate only after current source-register and authority onboarding gates pass.
9. Kaizen. Record the baseline, smallest experiment, evidence, standardised learning, owner, rollback, and next re-measurement in the engine.

Anti-Patterns

• Direct URA calls from Android or browser code. Fix: ERP gateway and safe read-only projection.
• Client-supplied tenant/TIN routing. Fix: derive profile from verified context.
• One global AES/key cache or offline store. Fix: tenant/profile-scoped key and device lifecycle with explicit isolation tests.
• New idempotency key after timeout. Fix: reconcile and reuse the original key.
• Storing the authority's fiscal number in the tenant's invoice-number column, or letting it advance the tenant counter. Fix: keep the fiscal number in its own column; the tenant series stays contiguous (tenant-document-numbering).
• FakeEfrisClient in production wiring. Fix: fail closed unless a configured, authorized adapter is selected.
• Storing only normalized status. Fix: retain redacted provider code/message, hashes, version, and attempt evidence.
• Retrying validation or authorization failures. Fix: classify deterministic, transient, unknown, and manual-review outcomes.
• Adding tenant_id to a table without backfill/index/rollback evidence. Fix: use expand-contract and prove zero unowned rows before enforcement.

Read Next

• chwezi-accounting-doctrine electronic fiscal taxing for tax and ledger rules
• api-design-first, database-design-engineering, distributed-systems-patterns, and reliability-engineering
• multi-tenant-saas-architecture, saas-erp-system-design, and pos-sales-operations-engineering
• android-development (including its persistence and TDD guidance) for downstream mobile projections

References

• Architecture and tenant isolation
• Adapter, API, and queue contract
• Uganda EFRIS source register
• Uganda EFRIS interface catalogue
• Uganda offline and device deployment
• Testing, observability, and release
• ERP mapping example

Evidence Produced