Reconciliation API¶
Reconciliation is a microservice mesh. Most integrators call ingestion (start work) and exception resolve (operator decisions). Engine/loader/workers are often chained internally via HTTP and Pub/Sub.
Primary entry points¶
| Concern | Service | Path | Status |
|---|---|---|---|
| Start money pipeline | bk-ingestion :8001 |
POST /v1/ingestion/background |
IMPLEMENTED |
| Start asset pipeline | bk-ingestion |
POST /v1/ingestion/asset |
IMPLEMENTED |
| Resolve exceptions | exception-service :8005 |
POST /v1/exceptions/resolve |
IMPLEMENTED |
| Detect banking exceptions | exception-service |
POST /v1/exceptions/banking/detect |
IMPLEMENTED |
| Detect commercial exceptions | exception-service |
POST /v1/exceptions/commercial/detect |
IMPLEMENTED |
Evidence: microservices/ingestion/.../routes/ingestion.py (/background, /asset + root_path=/v1); microservices/exception-service/src/routes/*.py.
Engine / loader / reversals (often internal)¶
From service README + routers (root_path=/v1):
| Service | Paths |
|---|---|
bk-recon-engine :8002 |
POST /v1/reconcile/banking, /commercial, /asset, /complete-batch, /reprocess-cross-month/background, /target-field-suggestion |
bk-loader :8003 |
POST /v1/loader/matches, /publish-matches, /task, PATCH /v1/loader/update/{session_id}, plus code-only helpers (/software-records, /pipeline-status, /cancel/{session_id}/) |
bk-reversals :8004 |
Code: POST /v1/reversals/pipeline/background, /gl-reversals/background, /reprocess-cross-month/background |
README vs code (reversals)¶
Service README documents POST /v1/reversals/background. Routers currently expose /reversals/pipeline/background and /reversals/gl-reversals/background. Treat routers / OpenAPI on the running process as authoritative until README is aligned.
Workers¶
| Service | Path | Status |
|---|---|---|
bk-name-worker |
POST /extract-names |
IMPLEMENTED |
bk-recon-worker |
POST /process-window |
IMPLEMENTED |
bk-recon-work-dlq-replay |
POST /replay |
IMPLEMENTED |
| all workers | GET /health, POST /wake |
IMPLEMENTED |
Exception resolve contract¶
Bulk action scoped by partner_id, tenant_id, domain, cluster_type (optional cluster_ids / status band). Full semantics: exception resolution, banking exception resolution.
Prod may also pull resolution requests from Pub/Sub (exception-resolution-requests-{env} per route comments) — HTTP remains a manual/fallback path.
Asset events¶
Downstream consumers: asset event contract.
Local¶
cd banking-reconciliation-ai-backend
make run-all # or make run-core
# APP_ENVIRONMENT=local → sequential matching, no Pub/Sub workers required
See Local development.