# 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) | T-001…T-008 journal lines |

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.