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`](../../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`](../../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`](../../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`](../../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

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

```http
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)

```bash
# 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`).