Integrated Systems

The middleware integrates with four external systems and one internal database. Each integration has its own authentication mechanism, data format and failure modes.

1. Oracle Simphony (Micros POS) — inbound

The point-of-sale system at all Pedro's Chicken locations. When a cashier completes a sale, the terminal sends the invoice here for fiscal processing.

Property	Value
Direction	Inbound (POS → Middleware)
Protocol / format	HTTPS REST, JSON (Taxint format)
Authentication	Bearer JWT (Oracle Restaurant IDM)
Endpoint	`POST /pckzra/api/taxint/pos/upload`

The POS sends a StandardInvoicePayloadDto: DocumentInfo (folio ID, TPIN), SellerInfo (SellerName, contact), FolioInfo (currency, rate, cashier, postings, VAT codes), optional BuyerInfo, and PaymentInfo. It receives an UploadResponseDto with the fiscal folio number and fiscal outputs (QR code, SDC ID, MRC, signature, tax data).

2. Chrilan Smart API (ZRA) — outbound

The fiscal compliance gateway to ZRA. It registers invoices, assigns receipt numbers, generates QR codes and returns digitally signed fiscal data.

Property	Value
Direction	Outbound
Base URL	`https://zra.abc.co.zm/smartinv`
Authentication	API key per store (header `x-api-key`)
Timeout	30 seconds; retry 3 attempts with 1s backoff

Endpoint	Method	Purpose
`/invoice/create`	POST	Submit invoice for fiscal registration
`/product/createBulk`	POST	Create/update products in the catalog
`/product/validate`	GET	Check whether a product PLU exists
`/codes/currency/all`	GET	List supported currencies

Chrilan errors return JSON with code, message and type; the middleware wraps them in a ChrilanApiException carrying the HTTP status, error details and full response body.

3. Oracle STS API — outbound

Simphony Transaction Services: the source of menu items and tax definitions for synchronization.

Property	Value
Base URL	`https://msaf-sts.oraclemicros.com/api/v1`
Authentication	OAuth 2.0 authorization code + PKCE (id_token cached until 60s before expiry)
OIDC authority	`https://ors-idm.msaf.oraclerestaurants.com`
Organization	`PCK`
Timeout	30 seconds

Endpoint	Method	Purpose
`/menus/{menuPath}`	GET	Fetch menu items, paginated (`offset`/`limit`, loop while `hasMore`)
`/taxes`	GET	Fetch tax classes and rates for vatCat mapping

Menu path format: {OrgShortName}:{LocationRef}:{RevenueCenterRef}, e.g. PCK:PCK_3103:101. Both query parameters and Simphony-* headers are required on calls — omitting either yields HTTP 403.

4. Whapi (WhatsApp API) — outbound

WhatsApp Business gateway used to deliver OTP codes to administrators, and available for store-level alert notifications.

Property	Value
Base URL	`https://gate.whapi.cloud`
Authentication	Bearer token
Endpoint used	`POST /messages/text`
Toggle	`whapi.api.enabled`

5. MariaDB — internal

Property	Value
Host / database	`192.168.0.50:3306 / pckmiddle`
Driver	MariaDB JDBC (`org.mariadb.jdbc.Driver`)
Pool	HikariCP, max 20 connections, min 5 idle
Migrations	Flyway (V001–V008), auto-run on startup

Table	Purpose
`api_transactions`	Full request/response logging
`conversion_logs`	Data transformation audit trail
`fiscal_invoices`	Issued invoice records for refund lookups
`store_registrations`	Per-store configuration and API keys
`users`	Portal user accounts (BCrypt passwords, OTP fields)
`system_config`	Key-value configuration store

Schema detail: Database Schema.

Failure modes quick reference

System	Typical failure	Symptom
Oracle IDM	JWKS unreachable	POS calls rejected (401) when validation enabled
Chrilan	Timeout / 5xx / invalid key	POS receives HTTP 500; transaction logged with Chrilan error body
Oracle STS	Wrong LocRef, expired credentials	Menu sync HTTP 403; products go stale
Whapi	Token invalid / disabled	OTP not delivered; portal sign-in blocked
MariaDB	Connection loss	Application health check fails; requests error