smom-dbis-138/docs/hybx-omnl/OMNL_IPSAS_API.md

OMNL IPSAS / GL validation API (token-aggregation)

Endpoints are served under /api/v1 when the token-aggregation service is running. They tie on-chain OMNL compliance to IPSAS-aligned GL codes documented for OMNL Hybx (Fineract).

Discovery: GET /api/v1/omnl/catalog — machine-readable list of all OMNL routes, auth notes, and query parameters.

OpenAPI 3: GET /api/v1/omnl/openapi.json — static OpenAPI 3.0 document for Swagger UI, Postman import, and codegen.

Configuration files (smom-dbis-138)

File	Purpose
config/omnl-ipsas-gl-registry.json	Canonical GL codes (1000, 1050, 2000, 2100, 3000), IPSAS references, allowed pairs, monetary-layer hints
config/omnl-journal-matrix.json	IPSAS double-entry matrix (Phase C interoffice, M0–M4, Office 24 opening)
docs/04-configuration/mifos-omnl-central-bank/omnl-journal-matrix-phase-c-interoffice.json	Phase C HO/branch template
docs/04-configuration/mifos-omnl-central-bank/omnl-journal-matrix-hospitallers24-opening-1b.json	HOSPITALLERS-24 $1B opening two-leg reference

Override paths with OMNL_IPSAS_GL_REGISTRY and OMNL_JOURNAL_MATRIX_PATH if needed.

Fineract (live compare & health)

Set:

• OMNL_FINERACT_BASE_URL
• OMNL_FINERACT_TENANT (default omnl)
• OMNL_FINERACT_USER (default app.omnl) — or legacy OMNL_FINERACT_USERNAME
• OMNL_FINERACT_PASSWORD
• OMNL_FINERACT_GL_PAGE_LIMIT (pagination for large tenants)

Method	Path	Description
GET	/omnl/ipsas/fineract-health	Probe /glaccounts?limit=1 — returns ok, statusCode, configured
GET	/omnl/ipsas/fineract-compare	Full GL list vs registry (requires OMNL_API_KEY when that env is set)

IPSAS validation

Method	Path	Description
GET	/omnl/ipsas/registry	Full IPSAS GL registry JSON
GET	/omnl/ipsas/matrix	Journal matrix entries
GET	/omnl/ipsas/validate-pair?debitGlCode=&creditGlCode=	Validate one pair (registry + matrix)
POST	/omnl/ipsas/validate-pairs	Body: { "pairs": [{ "debitGlCode", "creditGlCode" }, ...] } — batch validation
GET	/omnl/ipsas/layer/:layer	m0_reserve | m1_liability | settlement | equity
GET	/omnl/ipsas/compliance-context/:lineId?aggregated=1	Compliance snapshot + IPSAS guidance (OMNL_API_KEY when set)

Cross-cutting OMNL APIs (same /api/v1 prefix)

Method	Path	Description
GET	/omnl/reconcile-anchor	SHA-256 of canonical IPSAS registry + journal matrix (same as omnl-reconcile-report.mjs)
GET	/omnl/integration-status	Booleans for configured env groups (no secrets)
GET	/omnl/cross-chain-lines	hybx-omnl-cross-chain-lines.json content + path
GET	/omnl/zk-verifier	Address from OMNL_ZK_VERIFIER
GET	/omnl/mirror-coordinator?chainId=138	On-chain mirrorChainSelector, mirrorReceiver, feeToken

Example

GET /api/v1/omnl/ipsas/validate-pair?debitGlCode=1050&creditGlCode=2000

POST /api/v1/omnl/ipsas/validate-pairs
Content-Type: application/json

{"pairs":[{"debitGlCode":"1050","creditGlCode":"2000"}]}

Expect ipsasCompliantPair: true when the pair is allowed in the registry or matrix. Same-GL pairs (e.g. 2000/2000) return doubleEntryValid: false, rejectReason: "same_gl_account".

Post-deploy validation (token-aggregation default port 3000)

# FAIL — same GL (invalid double entry)
curl -s "http://127.0.0.1:3000/api/v1/omnl/ipsas/validate-pair?debitGlCode=2000&creditGlCode=2000"

# PASS — Office 24 branch leg (live $1B pattern)
curl -s "http://127.0.0.1:3000/api/v1/omnl/ipsas/validate-pair?debitGlCode=1410&creditGlCode=2100"

# PASS — Phase C HO interoffice leg
curl -s "http://127.0.0.1:3000/api/v1/omnl/ipsas/validate-pair?debitGlCode=2100&creditGlCode=2410"

# PASS — M2→M3 token load
curl -s "http://127.0.0.1:3000/api/v1/omnl/ipsas/validate-pair?debitGlCode=2200&creditGlCode=2300"

# Reconcile anchor changes when registry/matrix updates
curl -s "http://127.0.0.1:3000/api/v1/omnl/reconcile-anchor"

Phase C rule: HO allocation uses 2100 → 2410 (not 2000 → 2410). Branch leg 1410 → 2100. GL 2100 is branch spendable M1 (matches Office 24 settlement profile glM1).