Getting Started

Welcome to the Pedro's Chicken (PCK) ZRA middleware documentation. This guide explains what the system is, who uses it, and how to find your way around.

What is this system?

The Taxint–Chrilan Middleware is a translation and compliance bridge. It lets every Pedro's Chicken point-of-sale terminal running Oracle Simphony issue fiscally compliant invoices through the Zambia Revenue Authority (ZRA) Smart Invoice system, which is operated by Chrilan Technologies.

The two systems speak completely different languages:

Oracle Simphony (Micros POS) sends invoices in a proprietary format called Taxint.
ZRA fiscal compliance happens through the Chrilan Smart API, which uses an entirely different data format.

Without this middleware, every POS terminal in every store would need custom code to talk to ZRA. Instead, the middleware sits in the middle and:

Receives invoice data from the POS in Taxint format
Translates it into Chrilan Smart API format
Submits the invoice to Chrilan/ZRA for fiscal registration
Translates the ZRA response (receipt number, QR code, SDC ID, tax data) back into Taxint format
Returns the fiscal response to the POS so it can print a compliant receipt

Why it exists: the regulatory requirement

The Zambia Revenue Authority mandates that all point-of-sale transactions be reported to its electronic fiscal device system. Every invoice must receive:

A receipt number (rcptNo) from ZRA
A Smart Device Controller ID (sdcId)
A QR code for customer verification
A digital signature (rcptSign)
Tax breakdown data (taxData)

Compliance note Without these fiscal identifiers printed on the receipt, a business is non-compliant and subject to penalties. The middleware exists to make this automatic and invisible to cashiers.

Who uses it?

Role	How they interact
Cashiers	Never touch the middleware directly. They ring up sales on the POS as usual; fiscal registration happens automatically in the background.
Store administrators	Use the web admin portal to register stores, manage API keys, configure menu sync, and review reports.
Operations / support	Monitor health endpoints, review failed transactions, and follow the troubleshooting guide.
POS integrators (Micros)	Connect POS terminals to the upload endpoint using the integration guide.
Developers	Maintain and extend the middleware using the architecture and mapping references.

What the system does, at a glance

Capability	Description
Invoice fiscalisation	Translates every POS sale into a ZRA-registered invoice with receipt number, QR code and digital signature
Credit notes / refunds	Looks up the original invoice in the local database and links the refund to it, as ZRA requires
Menu synchronization	Syncs Oracle Simphony menu items (with prices and VAT categories) to the Chrilan product catalog every 60 seconds
Multi-store management	Each store has its own TPIN, Chrilan API key and menu sync settings, managed from one portal
Complete audit trail	Every request, response and conversion is logged to the database with timing and transaction IDs
Reporting	Transaction statistics, failure reports and conversion history, filterable by store and date

The 30-second mental model

Customer pays at the till
        │
        ▼
Oracle Simphony POS ──(Taxint JSON)──▶ MIDDLEWARE ──(Chrilan JSON)──▶ Chrilan Smart API ──▶ ZRA
        │                                │                                   │
        │                                ▼                                   │
        │                          MariaDB (logs,                            │
        │                          invoices, stores)                         │
        │                                                                    ▼
        ◀──────────(receipt no, QR code, signature)────────────── ZRA registers the invoice

POS prints the compliant receipt

Where is it running?

Property	Value
Production URL	`https://server.zra.co.zm/pckzra`
Admin portal	`https://server.zra.co.zm/pckzra/login`
POS upload endpoint	`POST https://server.zra.co.zm/pckzra/api/taxint/pos/upload`
Interactive API docs (Swagger)	`https://server.zra.co.zm/pckzra/swagger-ui.html`
Database	MariaDB at `192.168.0.50:3306/pckmiddle`

Next steps

Sign in to the admin portal — email, password and WhatsApp OTP
Register your first store — the step that makes invoices work
Platform overview — understand the moving parts