{"id":44277069,"url":"https://github.com/digitaltouchcode/fisc","last_synced_at":"2026-04-03T16:01:43.768Z","repository":{"id":337297012,"uuid":"1153012649","full_name":"DigitalTouchCode/fisc","owner":"DigitalTouchCode","description":"Zimbabwe fiscalisation library ","archived":false,"fork":false,"pushed_at":"2026-03-27T19:48:40.000Z","size":395,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"release","last_synced_at":"2026-03-27T22:50:04.320Z","etag":null,"topics":["django","django-rest-framework","fiscalisation","software-engineering","zimra"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DigitalTouchCode.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-08T19:11:44.000Z","updated_at":"2026-03-27T21:29:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/DigitalTouchCode/fisc","commit_stats":null,"previous_names":["digitaltouchcode/fisc"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/DigitalTouchCode/fisc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DigitalTouchCode%2Ffisc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DigitalTouchCode%2Ffisc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DigitalTouchCode%2Ffisc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DigitalTouchCode%2Ffisc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DigitalTouchCode","download_url":"https://codeload.github.com/DigitalTouchCode/fisc/tar.gz/refs/heads/release","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DigitalTouchCode%2Ffisc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31362682,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T15:19:21.178Z","status":"ssl_error","status_checked_at":"2026-04-03T15:19:20.670Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["django","django-rest-framework","fiscalisation","software-engineering","zimra"],"created_at":"2026-02-10T21:00:21.332Z","updated_at":"2026-04-03T16:01:43.750Z","avatar_url":"https://github.com/DigitalTouchCode.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# FiscGuy\n\n[![Tests](https://github.com/digitaltouchcode/fisc/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/digitaltouchcode/fisc/actions/workflows/tests.yml?query=branch%3Dmain)\n[![PyPI version](https://img.shields.io/pypi/v/fiscguy.svg?v=1)](https://pypi.org/project/fiscguy/)\n[![Downloads](https://static.pepy.tech/badge/fiscguy)](https://pepy.tech/project/fiscguy)\n![Python](https://img.shields.io/badge/python-3.11%20|%203.12%20|%203.13-blue)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\n**The Modern Python Library for ZIMRA Fiscal Device Integration**\n\nFiscGuy gives Django applications a simple, Pythonic interface for every fiscal operation required by the Zimbabwe Revenue Authority — receipt submission, fiscal day management, certificate handling, and more. Built on Django REST Framework, it drops into any Django project in minutes.\n\n[Installation](#installation) • [Quick Start](#quick-start) • [API Reference](#api-reference) • [REST Endpoints](#rest-endpoints) • [📚 Full Documentation](https://digitaltouchcode.github.io/fisc/) • [Contributing](#contributing)\n\n---\n\n\u003c/div\u003e\n\n## Features\n\n- **Seven core API functions** — `open_day`, `close_day`, `submit_receipt`, `get_status`, `get_configuration`, `get_taxes`, `get_buyer`\n- **Full fiscal day lifecycle** — open, manage counters, close with ZIMRA-compliant hash and signature\n- **Receipt types** — Fiscal Invoice, Credit Note, Debit Note with correct counter tracking\n- **Offline resilience** — receipts queued locally when FDMS is unreachable, synced automatically on reconnect\n- **Certificate management** — CSR generation, device registration, certificate renewal via `init_device`\n- **Multi-currency** — USD and ZWG support with per-currency counter tracking\n- **Multiple payment methods** — Cash, Card, Mobile Wallet, Bank Transfer, Coupon, Credit, Other\n- **Buyer management** — optional buyer TIN and registration data on receipts\n- **Cursor pagination** — efficient receipt listing for large datasets\n- **Typed exceptions** — every error condition has its own exception class\n- **90%+ test coverage** — mocked ZIMRA and crypto, fast CI\n\n---\n\n## Requirements\n\n- Python 3.11, 3.12, or 3.13\n- Django 4.2+\n- Django REST Framework 3.14+\n\n---\n\n## Installation\n\n```bash\npip install fiscguy\n```\n\n### From source\n\n```bash\ngit clone https://github.com/digitaltouchcode/fisc.git\ncd fisc\npip install -e \".[dev]\"\n```\n\n---\n\n## Quick Start\n\n### 1. Add to Django settings\n\n```python\n# settings.py\nINSTALLED_APPS = [\n    # ...\n    \"fiscguy\",\n    \"rest_framework\",\n]\n```\n\n### 2. Run migrations\n\n```bash\npython manage.py migrate\n```\n\n### 3. Initialise your device\n\n```bash\npython manage.py init_device\n```\n\nThis interactive command collects your device credentials, generates a CSR, registers the device with ZIMRA, and fetches taxes and configuration automatically.\n\n### 4. Include URLs\n\n```python\n# urls.py\nfrom django.urls import path, include\n\nurlpatterns = [\n    path(\"fiscguy/\", include(\"fiscguy.urls\")),\n]\n```\n\n### 5. Submit your first receipt\n\n```python\nfrom fiscguy import open_day, submit_receipt, close_day\n\nopen_day()\n\nreceipt = submit_receipt({\n    \"receipt_type\": \"fiscalinvoice\",\n    \"currency\": \"USD\",\n    \"total_amount\": \"115.00\",\n    \"payment_terms\": \"Cash\",\n    \"lines\": [\n        {\n            \"product\": \"Consulting Service\",\n            \"quantity\": \"1\",\n            \"unit_price\": \"115.00\",\n            \"line_total\": \"115.00\",\n            \"tax_amount\": \"15.00\",\n            \"tax_name\": \"standard rated 15%\",\n        }\n    ],\n})\n\nclose_day()\n```s\n---\n\n## REST Endpoints\n\nWhen URLs are included, FiscGuy exposes the following endpoints:\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `POST` | `/fiscguy/open-day/` | Open a new fiscal day |\n| `POST` | `/fiscguy/close-day/` | Close the current fiscal day |\n| `GET` | `/fiscguy/get-status/` | Get device and fiscal day status |\n| `POST` | `/fiscguy/get-ping/` | Ping FDMS to report device is online |\n| `GET` | `/fiscguy/receipts/` | List receipts (cursor paginated) |\n| `POST` | `/fiscguy/receipts/` | Submit a new receipt |\n| `GET` | `/fiscguy/receipts/{id}/` | Retrieve a receipt by ID |\n| `GET` | `/fiscguy/configuration/` | Get taxpayer configuration |\n| `POST` | `/fiscguy/sync-config/` | Manually sync configuration from FDMS |\n| `GET` | `/fiscguy/taxes/` | List all tax types |\n| `POST` | `/fiscguy/issue-certificate/` | Renew device certificate |\n| `*` | `/fiscguy/buyer/` | Buyer CRUD (ModelViewSet) |\n\n### Pagination\n\nReceipt listing supports cursor-based pagination:\n\n```\nGET /fiscguy/receipts/?page_size=20\n```\n\nDefault page size: `10`. Maximum: `100`.\n\n---\n\n## Error Handling\n\nAll operations raise typed exceptions. Import them from `fiscguy.exceptions`:\n\n```python\nfrom fiscguy.exceptions import (\n    ReceiptSubmissionError,\n    CloseDayError,\n    FiscalDayError,\n    ConfigurationError,\n    CertificateError,\n    DevicePingError,\n    StatusError,\n)\n\ntry:\n    close_day()\nexcept CloseDayError as e:\n    print(f\"Close day failed: {e}\")\n```\n\n| Exception | Raised when |\n|-----------|-------------|\n| `ReceiptSubmissionError` | Receipt processing or FDMS submission fails |\n| `CloseDayError` | FDMS rejects the close day request |\n| `FiscalDayError` | Fiscal day cannot be opened or is already open |\n| `ConfigurationError` | Configuration is missing or sync fails |\n| `CertificateError` | Certificate issuance or renewal fails |\n| `DevicePingError` | Ping to FDMS fails |\n| `StatusError` | Status fetch from FDMS fails |\n| `DeviceRegistrationError` | Device registration with ZIMRA fails |\n| `CryptoError` | RSA signing or hashing fails |\n\n---\n\n## Models\n\nFiscGuy adds the following tables to your database:\n\n| Model | Description |\n|-------|-------------|\n| `Device` | Fiscal device registration details |\n| `Configuration` | Taxpayer configuration synced from FDMS |\n| `Certs` | Device certificate and private key |\n| `Taxes` | Tax types synced from FDMS on day open |\n| `FiscalDay` | Daily fiscal period with receipt counter |\n| `FiscalCounter` | Running totals per tax / payment method |\n| `Receipt` | Submitted receipts with hash, signature, QR code |\n| `ReceiptLine` | Individual line items on a receipt |\n| `Buyer` | Optional buyer registration data |\n\nAccess them directly:\n\n```python\nfrom fiscguy.models import Device, Receipt, FiscalDay, Taxes\n\ndevice = Device.objects.first()\nopen_days = FiscalDay.objects.filter(is_open=True)\nreceipts = Receipt.objects.select_related(\"buyer\").prefetch_related(\"lines\")\n```\n\n---\n\n## Management Commands\n\n### `init_device`\n\nInteractive device setup — run once per device:\n\n```bash\npython manage.py init_device\n```\n\nThe command will:\n1. Prompt for `org_name`, `activation_key`, `device_id`, `device_model_name`, `device_model_version`, `device_serial_number`\n2. Ask whether to use production or testing FDMS\n3. Generate an RSA key pair and CSR\n4. Register the device with ZIMRA to obtain a signed certificate\n5. Fetch and persist configuration and taxes\n\n---\n\n## Testing\n\n```bash\n# Run all tests\npytest\n\n# With coverage report\npytest --cov=fiscguy --cov-report=html\n\n# Run a specific test file\npytest fiscguy/tests/test_views.py\n\n# Run a specific test\npytest fiscguy/tests/test_closing_day_service.py::TestBuildSaleByTax\n```\n\nAll tests mock ZIMRA API calls and crypto operations — no network access required.\n\n---\n\n## 📚 Documentation\n\n**[📖 View Full Documentation](https://digitaltouchcode.github.io/fisc/)**\n\nOur comprehensive documentation covers everything you need to know:\n\n### 🚀 Quick Links\n- **[Installation Guide](https://digitaltouchcode.github.io/fisc/installation/)** - Detailed setup instructions\n- **[Receipt Types](https://digitaltouchcode.github.io/fisc/receipt-types/)** - Fiscal Invoice, Credit Note, Debit Note rules\n- **[Fiscal Counters](https://digitaltouchcode.github.io/fisc/fiscal-counters/)** - Counter tracking and calculations\n- **[Closing Day](https://digitaltouchcode.github.io/fisc/closing-day/)** - Hash string and signature specifications\n- **[Certificate Management](https://digitaltouchcode.github.io/fisc/certificate-management/)** - Certificate lifecycle and renewal\n- **[Error Reference](https://digitaltouchcode.github.io/fisc/error-reference/)** - All exceptions and troubleshooting\n\n### 🌐 GitHub Pages Setup\n\nThis documentation is automatically deployed to GitHub Pages when you push to the `main` branch.\n\n**No local scripts needed** - GitHub Actions handles everything automatically!\n\n### 📋 Documentation Contents\n\n| Document | Description |\n|----------|-------------|\n| [Installation](https://digitaltouchcode.github.io/fisc/installation/) | Detailed installation and setup guide |\n| [Receipt Types](https://digitaltouchcode.github.io/fisc/receipt-types/) | Fiscal Invoice, Credit Note, Debit Note rules |\n| [Fiscal Counters](https://digitaltouchcode.github.io/fisc/fiscal-counters/) | How counters work and how they are calculated |\n| [Closing Day](https://digitaltouchcode.github.io/fisc/closing-day/) | Closing day hash string and signature spec |\n| [Certificate Management](https://digitaltouchcode.github.io/fisc/certificate-management/) | Certificate lifecycle and renewal |\n| [Error Reference](https://digitaltouchcode.github.io/fisc/error-reference/) | All exceptions and what causes them |\n| [Changelog](https://digitaltouchcode.github.io/fisc/changelog/) | Version history |\n| [Contributing](https://digitaltouchcode.github.io/fisc/contributing/) | Contributing guidelines |\n\n---\n\n## Contributing\n\nContributions are welcome. Please read [`CONTRIBUTING.md`](CONTRIBUTING.md) first.\n\n```bash\n# Set up dev environment\ngit clone https://github.com/digitaltouchcode/fisc.git\ncd fisc\npip install -e \".[dev]\"\npre-commit install\n\n# Before submitting a PR\nblack fiscguy\nisort fiscguy\nflake8 fiscguy\npytest\n```\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n\u003cdiv align=\"center\"\u003e\nBuilt for Zimbabwe 🇿🇼 by \u003ca href=\"mailto:cassymyo@gmail.com\"\u003eCasper Moyo\u003c/a\u003e\n\u003c/div\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitaltouchcode%2Ffisc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdigitaltouchcode%2Ffisc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitaltouchcode%2Ffisc/lists"}