Managing Stores
Every Pedro's Chicken location must be registered in the middleware before its POS terminals can submit invoices. This guide covers registering, editing, activating and deactivating stores from the admin portal.
Why registration matters
There is no default or fallback Chrilan API key. When a POS submits an invoice, the middleware looks up the store by its
SellerName and uses that store's own API key to reach ZRA. An unregistered or inactive store gets an immediate HTTP 403 and the sale cannot be fiscalised.
The store list
Open /pckzra/stores after signing in. The list shows every registered store with its name, TPIN, active status and menu sync status. Use the search box for partial name matches (e.g. typing “Manda” finds “PCK Manda Hill”).
Registering a new store
- Go to Stores → Add (
/pckzra/stores/add). - Fill in the form (field reference below).
- Save. The system validates that the
SellerNameis unique before creating the record. - Have the store submit a test invoice (or use the test procedure) to confirm end-to-end flow.
Field reference
| Field | Required | Description |
|---|---|---|
| SellerName | Yes | The primary store identifier. Must match exactly the SellerInfo.SellerName the POS sends (e.g. PCK Manda Hill). Case and spacing matter. |
| TPIN | Yes | The store's Tax Payer Identification Number registered with ZRA. |
| Chrilan API key | Yes | The store-specific API key issued by Chrilan for that store's fiscal device. Sent as the x-api-key header on every Chrilan call. |
| Active | Yes | Only active stores can submit invoices. Deactivation is a soft switch — no data is deleted. |
| Oracle menu path | For menu sync | Format {OrgShortName}:{LocationRef}:{RevenueCenterRef}, e.g. PCK:PCK_3103:101. See Menu sync setup. |
| Menu sync enabled | No | When on, this store's menu is synced to Chrilan every 60 seconds. |
| Default department | No | Chrilan department code used for synced products. Defaults to 50203301. |
| Notification phone / group ID | No | WhatsApp targets for store-level alerts (per-store notification wiring). |
The #1 integration failure
A mismatch between the POS
SellerName and the registered seller_name is the most common cause of “Store not registered” (HTTP 403) errors. Confirm the exact string with the POS configuration team — including capitalisation and spaces — before saving.
Editing a store
Open the store from the list and choose Edit (/pckzra/stores/edit/{id}). All fields are updatable. Changes take effect immediately:
- Rotating a Chrilan API key affects the very next invoice.
- Changing the SellerName breaks lookups until the POS sends the new value — coordinate with the POS team.
Activating and deactivating
| Action | Effect |
|---|---|
| Deactivate | Soft delete. Invoices from this store are rejected with HTTP 403 (“Store is inactive”). All history, logs and fiscal invoices are preserved. Use this for store closures or incident response. |
| Activate | Re-enables invoice submission and menu sync (if configured). |
| Delete | Permanent removal via the REST API. Prefer deactivation unless you are certain — fiscal history must be retained for ZRA audit purposes. |
Verifying a store works
- Confirm the store shows Active in the list.
- From the POS, submit a small test sale.
- Open Reports, filter by the store, and confirm the transaction appears with success = true.
- Check the receipt prints with a ZRA receipt number and QR code.
Store statistics
The portal (and GET /api/stores/stats) reports total, active and inactive store counts — useful for a quick estate-wide health check.