REST API Reference
All endpoints live under the context path /pckzra. Interactive documentation with try-it-out is available at /pckzra/swagger-ui.html (OpenAPI JSON at /pckzra/v3/api-docs).
Taxint API — /api/taxint
Used by POS terminals. Bearer JWT authentication.
| Method | Path | Description |
|---|---|---|
| POST | /api/taxint/pos/upload | Submit an invoice, credit note or debit note for fiscal registration. See the integration guide. |
| GET | /api/taxint/health | Health check: service status, version, timestamp. |
Health check response:
{
"status": "UP",
"timestamp": "2026-08-01T14:52:39",
"version": "1.0.0",
"service": "Taxint-Chrilan Middleware"
}Stores API — /api/stores
Store registration management (also available via the web portal).
| Method | Path | Description |
|---|---|---|
| GET | /api/stores | List all stores |
| POST | /api/stores | Register a new store (SellerName uniqueness enforced) |
| GET | /api/stores/{id} | Get a store by ID |
| PUT | /api/stores/{id} | Update store fields |
| DELETE | /api/stores/{id} | Permanently delete a store (prefer deactivate) |
| GET | /api/stores/active | List active stores only |
| GET | /api/stores/by-name/{sellerName} | Look up a store by exact SellerName |
| GET | /api/stores/search | Partial name search |
| POST | /api/stores/{id}/activate | Activate a store |
| POST | /api/stores/{id}/deactivate | Deactivate (soft delete) a store |
| GET | /api/stores/stats | Counts: total / active / inactive |
Store object fields
| Field | Description |
|---|---|
sellerName | Primary identifier — must match the POS SellerInfo.SellerName exactly |
tpin | Store Tax Payer Identification Number |
chrilanApiKey | Per-store Chrilan API key |
active | Only active stores can submit invoices |
oracleMenuPath | {OrgShortName}:{LocationRef}:{RevenueCenterRef} |
menuSyncEnabled | Include this store in the 60-second sync cycle |
defaultDepartment | Chrilan department code (default 50203301) |
notificationPhone / notificationGroupId | WhatsApp alert targets |
Reports API — /api/reports
Statistics and audit-trail queries. This is the only statistics surface (there is no /api/taxint/statistics).
| Method | Path | Description |
|---|---|---|
| GET | /api/reports/statistics | Total/successful/failed counts + success rate; filter by store and date range |
| GET | /api/reports/transactions | Paginated transaction history |
| GET | /api/reports/transactions/{transactionId} | Full request/response detail for one transaction |
| GET | /api/reports/transactions/failed | Failed transactions (default: last 7 days) |
| GET | /api/reports/conversions | Paginated conversion log history |
| GET | /api/reports/conversions/{id} | Single conversion detail |
| GET | /api/reports/conversions/failed | Failed conversions |
| GET | /api/reports/volume-by-store | Transaction counts per store |
| GET | /api/reports/active-stores | Simple store list for report filter UIs |
Web portal routes
Server-rendered (Thymeleaf) pages; session-based after OTP sign-in.
| Route | Purpose |
|---|---|
GET/POST /login | Email + password; triggers WhatsApp OTP |
GET/POST /verify-otp | OTP entry; creates the session |
POST /resend-otp | Issue a fresh OTP (invalidates the previous one) |
GET /dashboard | Landing page after sign-in |
GET /stores, /stores/add, /stores/edit/{id} | Store management UI |
POST /stores/save, /stores/delete/{id} | Store form actions |
GET /reports | Reports UI |
GET /logout | Invalidate the session |
Actuator endpoints
| Path | Purpose |
|---|---|
/pckzra/actuator/health | Detailed Spring Boot health (details always shown) |
/pckzra/actuator/info | Application info |
/pckzra/actuator/metrics | Application metrics |
/pckzra/actuator/prometheus | Prometheus-format metrics export |
/pckzra/actuator/loggers | Runtime log-level inspection/adjustment |
Error response shape
All API errors use a structured body with a message, a details list, and (for Chrilan failures) a Smart Invoice error block:
{
"error": "Validation failed",
"details": ["PropertyTaxNumber is required"]
}| Status | Meaning |
|---|---|
| 400 | Validation / conversion failure |
| 401 | Missing or invalid Bearer token |
| 403 | Store not registered or inactive |
| 404 / 405 / 415 | Unknown route / wrong method / wrong content type |
| 500 | Chrilan API failure, timeout or internal error |
Testing with curl
# Health
curl https://server.zra.co.zm/pckzra/api/taxint/health
# Upload (abridged payload)
curl -X POST https://server.zra.co.zm/pckzra/api/taxint/pos/upload \
-H "Authorization: Bearer $JWT_TOKEN" \
-H "Content-Type: application/json" \
-d @sample-invoice.json
# Statistics
curl "https://server.zra.co.zm/pckzra/api/reports/statistics?startDate=2026-07-01&endDate=2026-07-31"