Installation & Setup

Get FiscGuy running in an existing Django project in four steps.

Install

Copypip install fiscguy

Or install from source:

Copygit clone https://github.com/digitaltouchcode/fisc.git
cd fisc
pip install -e ".[dev]"

Django setup

1 · INSTALLED_APPS

Copy# settings.py
INSTALLED_APPS = [
    "django.contrib.contenttypes",
    "django.contrib.auth",
    "rest_framework",
    "fiscguy",
    # ... your other apps
]

2 · Migrations

Copypython manage.py migrate

3 · URL routing

Copy# your_project/urls.py
from django.urls import path, include

urlpatterns = [
    path("fiscguy/", include("fiscguy.urls")),
]

All FiscGuy endpoints will be available under /fiscguy/.

4 · Media files (QR codes)

Copy# settings.py
MEDIA_URL  = "/media/"
MEDIA_ROOT = BASE_DIR / "media"

Copy# urls.py (development only)
from django.conf import settings
from django.conf.urls.static import static

urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

Device initialisation

Run this once per device before using any other feature. This registers the device with ZIMRA, generates an RSA key pair, and issues a certificate.

Copypython manage.py init_device

Prompts

Verify setup

Copyfrom fiscguy.models import Device, Configuration, Taxes

device = Device.objects.first()
print(device)                    # "Acme Ltd - 78412"

config = Configuration.objects.first()
print(config.tax_payer_name)

print(Taxes.objects.all())

Development dependencies

Copypip install -e ".[dev]"

Includes: pytest, pytest-django, pytest-cov, black, isort, flake8, pylint, mypy, django-stubs.

Copypre-commit install    # runs black, isort, flake8 on every commit

Receipt Types

FiscGuy supports three receipt types as defined by the ZIMRA Fiscal Device Gateway API: fiscal invoices, credit notes, and debit notes.

Fiscal Invoice

A standard sale receipt. The most common receipt type.

CopyPOST /fiscguy/receipts/

{
  "receipt_type": "fiscalinvoice",
  "currency": "USD",
  "total_amount": "115.00",
  "payment_terms": "Cash",
  "lines": [
    {
      "product": "Product Name",
      "quantity": "1",
      "unit_price": "115.00",
      "line_total": "115.00",
      "tax_amount": "15.00",
      "tax_name": "Standard rated 15.5"
    }
  ]
}

Counter impact

Credit Note

A return or reversal against a previously issued fiscal invoice. All amounts must be negative.

CopyPOST /fiscguy/receipts/

{
  "receipt_type": "creditnote",
  "currency": "USD",
  "total_amount": "-115.00",
  "payment_terms": "Cash",
  "credit_note_reason": "Customer returned goods — defective",
  "credit_note_reference": "R-00000142",
  "lines": [
    {
      "product": "Product Name",
      "quantity": "1",
      "unit_price": "-115.00",
      "line_total": "-115.00",
      "tax_amount": "-15.00",
      "tax_name": "Standard rated 15.5"
    }
  ]
}

Debit Note

An upward adjustment against a previously issued fiscal invoice — e.g. additional delivery charges.

CopyPOST /fiscguy/receipts/

{
  "receipt_type": "debitnote",
  "currency": "USD",
  "total_amount": "23.00",
  "payment_terms": "Card",
  "credit_note_reason": "Additional delivery charge",
  "credit_note_reference": "R-00000142",
  "lines": [...]
}

Payment methods

Tax types

Taxes are synced from FDMS on every open_day() and stored in the Taxes model. Pass tax_name exactly as it appears there.

Closing a Fiscal Day

At the end of each trading day the fiscal day must be closed by submitting a signed summary of all fiscal counters to ZIMRA FDMS.

Quick close

CopyPOST /fiscguy/close-day/

What happens during close

ClosingDayService.close_day() performs these steps in order:

1. Build counter strings — each counter is serialised into the ZIMRA closing string format
2. Assemble the closing string — deviceID + fiscalDayNo + fiscalDayDate + counters
3. Hash and sign — SHA-256 hash of the string, signed with the device RSA private key
4. Build payload — closing string, signature, fiscal day counters, receipt counter
5. Submit to FDMS — POST /CloseDay
6. Poll for status — waits 10 seconds then calls GET /getStatus
7. Update database — marks FiscalDay.is_open = False on success

Closing string spec

Fields concatenated in this exact order, all text uppercase, no separators:

Counter string rules

Example counter string

Copy23265842026-03-30SALEBYTAXZWG0.005000SALEBYTAXZWG15.50134950SALETAXBYTAXZWG15.5018110BALANCEBYMONEYTYPEZWGLCARD69975BALANCEBYMONEYTYPEZWGLCASH69975

Common close day errors

Fiscal day status values

Retrying a failed close

FDMS allows close retries when the fiscal day status is FiscalDayOpened or FiscalDayCloseFailed.

Copyfrom fiscguy.exceptions import CloseDayError

try:
    # POST /fiscguy/close-day/
    close_day()
except CloseDayError as e:
    print(f"Close failed: {e}")
    # investigate, fix, then retry
    close_day()

Fiscal Counters

Fiscal counters are running totals that accumulate throughout a fiscal day. At close of day they are submitted to ZIMRA as part of the closing payload and used to verify the hash signature.

Counter types

How counters are updated

Every time a receipt is submitted, counters update automatically. You never need to update them manually.

Fiscal invoice

CopySaleByTax         += salesAmountWithTax   (per tax group)
SaleTaxByTax      += taxAmount            (per tax group, non-exempt/non-zero)
BalanceByMoneyType += paymentAmount

Credit note (values are negative)

CopyCreditNoteByTax    += salesAmountWithTax  (negative, per tax group)
CreditNoteTaxByTax += taxAmount           (negative, non-exempt/non-zero)
BalanceByMoneyType += paymentAmount       (negative)

Race condition prevention

Counter updates use Django F() expressions for atomic DB-level increments, preventing lost updates under concurrent receipt submission.

Copy# FiscGuy uses atomic F() expressions — not in-memory increment
FiscalCounter.objects.filter(...).update(
    fiscal_counter_value=F("fiscal_counter_value") + amount
)

Inspecting counters

Copyfrom fiscguy.models import FiscalDay

fiscal_day = FiscalDay.objects.filter(is_open=True).first()
print(fiscal_day.counters.all().values(
    "fiscal_counter_type",
    "fiscal_counter_currency",
    "fiscal_counter_value",
))

Certificate Management

FiscGuy uses mutual TLS authentication with ZIMRA FDMS. The device must hold a valid certificate issued by ZIMRA to submit any signed request.

How certificates work

1. init_device generates an RSA key pair and a Certificate Signing Request (CSR)
2. The CSR is sent to ZIMRA FDMS RegisterDevice endpoint
3. ZIMRA returns a signed certificate
4. The certificate and private key are stored in the Certs model
5. Every request to FDMS uses the certificate for mutual TLS authentication

Certificate storage

Copyfrom fiscguy.models import Certs

cert = Certs.objects.first()
print(cert.certificate)      # PEM-encoded certificate
print(cert.certificate_key)  # PEM-encoded private key
print(cert.csr)              # Original CSR
print(cert.production)       # True = production, False = testing

Certificate renewal

When a certificate expires, all signed requests will fail with BadCertificateSignature.

Via REST endpoint

CopyPOST /fiscguy/issue-certificate/

Copy{ "message": "Certificate issued successfully" }

Via Python

Copyfrom fiscguy.services.certs_service import CertificateService
from fiscguy.models import Device

device = Device.objects.first()
CertificateService(device).issue_certificate()

Key generation

Security notes

At runtime, ZIMRAClient writes the certificate and key to a temporary PEM file. The temp file is cleaned up when the client is closed (ZIMRAClient.close()).

API Reference

All endpoints are prefixed with /fiscguy/ based on your URL configuration. Base URL: https://your-host/fiscguy/

Fiscal Day

Copy{ "success": true, "fiscal_day_no": 42, "fdms_response": { ... } }

Copy{ "success": true, "fiscal_day_no": 42, "message": "Fiscal day 42 already open" }

Copy{ "success": true, "fiscal_day_no": 42, "fdms_response": { ... } }

Copy{ "error": "FDMS returned an error: ..." }

Receipts

Copy{
  "next": "http://example.com/fiscguy/receipts/?cursor=cD0...",
  "previous": null,
  "results": [{ ...receipt object... }]
}

Copy{ "error": "FDMS returned an error: ..." }

Buyers

Copy[{
  "id": 1,
  "name": "Casy Holdings",
  "tin_number": "2000123456",
  "address": "123 Main St, Harare",
  "trade_name": "Casy Retail",
  "email": "accounts@casy.co.zw",
  "phonenumber": "+263771234567"
}]

Configuration & Taxes

Copy{
  "tax_payer_name": "ACME Ltd",
  "tin_number": "1234567890",
  "vat_number": "V123456789",
  "address": "10 Commerce Drive, Harare"
}

Copy{ "message": "Configuration Synced" }

Copy[
  { "code": "A", "name": "Standard rated 15.5", "tax_id": 1, "percent": "15.00" },
  { "code": "B", "name": "Zero Rated",          "tax_id": 2, "percent": "0.00"  },
  { "code": "C", "name": "Exempt",               "tax_id": 3, "percent": "0.00"  }
]

Device Management

Copy{ "lastFiscalDayNo": 41, "lastReceiptGlobalNo": 150, "fiscalDayStatus": "Closed" }

Copy{ "success": true }

Copy{ "message": "Certificate issued successfully" }

Copy{ "error": "Certificate renewal issuance failed." }

HTTP status codes

Error Reference

All FiscGuy exceptions inherit from FiscalisationError. Import them from fiscguy.exceptions.

Exception hierarchy

Common exceptions

ReceiptSubmissionError

Raised when a receipt cannot be processed or submitted.

• No open fiscal day — call open_day() first
• Invalid receipt data (missing required fields, wrong types)
• FDMS rejected the receipt (validation errors)
• Credit note references a non-existent original receipt

CloseDayError

FiscalDayError

A fiscal day is already open, FDMS rejected the open request, or the previous fiscal day was not closed.

ConfigurationError

init_device was not run, or FDMS was unreachable during configuration sync.

Logging

FiscGuy uses loguru for structured logging.

Copyfrom loguru import logger
logger.add("fiscguy.log", level="INFO", rotation="1 day")

Troubleshooting

Architecture

Internal engineering reference for contributors and maintainers. Version 0.1.6 · April 2026 · Maintainer: Casper Moyo

System overview

Layer architecture

FiscGuy follows a strict four-layer architecture. Each layer has a single responsibility and communicates only with the layer directly below it.

Receipt processing pipeline

A POST /fiscguy/receipts/ call flows through these steps:

1. Validation — ReceiptCreateSerializer.is_valid() checks types, amounts, TIN format, credit note references
2. Persist — serializer.save() creates Receipt + ReceiptLine rows inside @transaction.atomic
3. Ensure fiscal day open — auto-opens if none found
4. Get next global number — queries GET /getStatus from FDMS
5. Build receipt data — lines, tax groups, previous hash (chain), signature string
6. Hash & sign — SHA256 + RSA PKCS1v15 via ZIMRACrypto
7. QR code — MD5 of signature bytes → verification code → PNG saved
8. Update fiscal counters — atomic F() increments per tax group
9. Submit to FDMS — POST /SubmitReceipt; if rejected, the @transaction.atomic rolls back everything

Cryptography

Library: cryptography (replaces deprecated pyOpenSSL).

Receipt signature string (spec §13.2.1)

QR code generation

Copyverification_code = MD5(signature_bytes).hexdigest()[:16].upper()
# formatted as XXXX-XXXX-XXXX-XXXX
qr_url = f"{fdms_base}/{device_id}{date}{global_no}{code}"

Development guidelines

Adding a new service

Copyclass MyService:
    def __init__(self, device: Device):
        self.device = device
        self.client = ZIMRAClient(device)

    @transaction.atomic
    def do_thing(self) -> dict:
        try:
            result = self.client.some_endpoint()
        except requests.RequestException as exc:
            raise MyError("FDMS call failed") from exc
        MyModel.objects.create(device=self.device, ...)
        return result

Testing

Copypytest                                    # all tests
pytest --cov=fiscguy --cov-report=html   # with coverage
pytest -k "test_build_sale_by_tax"         # single test

Code style

Copyblack fiscguy && isort fiscguy && flake8 fiscguy && mypy fiscguy

• Line length: 100 (Black)
• Imports: isort with Black profile
• Private methods: prefix _
• Type hints on all public method signatures
• Docstrings on all public classes and methods