Troubleshooting

Start from the symptom, confirm it in Reports (every failure keeps its full request and response), then apply the fix. Most issues resolve without server access.

Error catalog (POS-facing)

HTTP	Error	Cause	Fix
400	`SellerName is required`	Missing SellerInfo/SellerName in the payload	Include the SellerInfo block with SellerName
400	`FiscalFolioId is required`	Blank DocumentInfo.FiscalFolioId	Send a folio identifier
400	`PropertyTaxNumber is required`	Missing TPIN	Include a valid TPIN in DocumentInfo
400	`TrxInfo missing for TrxCode`	A Posting has no matching TrxInfo.Code	Link every TrxCode to a TrxInfo entry
400	Validation list	Malformed payload fields	Fix the listed fields; compare against the schema
401	Unauthorized	Missing/invalid JWT (when validation enabled)	Refresh the Oracle IDM token; check Bearer format
403	`Store not registered: X`	SellerName not in the database	Register the store; verify exact spelling/case
403	`Store is inactive: X`	Store deactivated	Reactivate in the portal
500	Chrilan API error	Chrilan rejected the call (error body contains code/message/type)	Read the Chrilan error in the transaction detail; commonly an invalid store API key or unknown PLU
500	Timeout	Chrilan unreachable for 30s	Check network/ZRA status; retries happen automatically (3 attempts)

Testing a store end to end

Confirm the store is Active with a valid Chrilan API key in the portal.
Check GET /pckzra/api/taxint/health returns UP.
Submit a small test sale from the POS.
In Reports, open the transaction: verify the Chrilan response contains rcptNo, sdcId and a QR code URL.
Verify the receipt prints with the fiscal identifiers.
If the product is new, confirm menu sync pushed it (look for the latest /product/createBulk call).

Common scenarios

“Every store is failing” (systemic)

Check /actuator/health for database DOWN.
Check failed transactions: if all show Chrilan 500s/timeouts, suspect a ZRA/Chrilan outage or network break — verify outbound connectivity to https://zra.abc.co.zm/smartinv.
Check whether a config change (JWT toggle, CORS, rate limiting) was just deployed.

“One store is failing”

403 → store registration/SellerName mismatch or deactivation.
Chrilan error mentioning key/auth → rotate/verify the store's Chrilan API key.
Chrilan error about product/PLU → the item isn't in the Chrilan catalog; check menu sync for that store.

“Menu changes aren't reaching Chrilan”

Confirm menuSyncEnabled on the store and a correct Oracle menu path (PCK:PCK_3103:101 format; the LocRef must be the exact Oracle location reference).
HTTP 403 from Oracle STS means a wrong LocRef or missing Simphony headers.
Check the sync summary logs: items are skipped when they lack a PLU or name.
Items without a sequence-1 price sync with price 0 — check Oracle price level configuration.

“Admins can't sign in to the portal”

No WhatsApp OTP → verify whapi.api.enabled=true, the Whapi token, and the user's registered phone number.
OTP rejected → it expires in 5 minutes and resend invalidates older codes; use the latest one.

“Credit note rejected”

The original invoice must exist in fiscal_invoices (the middleware looks it up automatically). If the original sale predates the middleware or was never fiscalised through it, the lookup fails.
Confirm AssociatedBillFiscalBillNo references the original fiscal bill number and at least one line has a Remark.

Log analysis

# Recent application errors
grep "ERROR" logs/taxint-chrilan-middleware.log | tail -20

# Follow one transaction through the logs
grep "<transaction-id>" logs/taxint-chrilan-middleware.log

# Failed conversions from the database
SELECT * FROM conversion_logs WHERE conversion_success = FALSE
ORDER BY created_at DESC LIMIT 10;

Escalation

When the transaction detail and this catalog don't resolve it, escalate with: the transaction ID, store name, timestamp, the full Chrilan error body (from Reports), and what changed recently (deployments, key rotations, menu changes).