Headless Reconciliation Worker & Orchestration API

GUCE Foreign-Exchange Domestication & Customs Apurement Engine

An API-driven document extraction, linear-programming matching and regulatory dossier generation service supporting cross-border trade and customs control under BCEAO Regulation R09/CM/UEMOA.

Worker Status: Checking /readyz... Auth: X-API-Key Health: /readyz · /healthz

Five-Stage Processing Architecture

STAGE 01 / CAMPAIGNS

Campaign & Tenant Isolation

Initializes isolated apurement campaigns with PostgreSQL row-level security and an append-only cryptographic hash chain in audit.event_log.

STAGE 02 / INGESTION & OCR

Multi-Format Document Intake

Extracts structured fields from GUCE customs declarations, commercial invoices, packing lists, transport bills of lading and bank SWIFT/transfer proofs.

STAGE 03 / MILP MATCHING

Linear-Programming Allocation

Solves invoice-to-bank settlement allocation and currency/tolerance checks via Mixed-Integer Linear Programming (PuLP / HiGHS) and deterministic fuzzy matching.

STAGE 04 / HITL REVIEW

Human-in-the-Loop Verification

Routes low-confidence extractions or multi-currency variances to token-verified human review workflows orchestrated via n8n.

STAGE 05 / DELIVERABLES

Regulatory Dossier Generation

Generates multi-sheet Excel reconciliation workbooks and PDF apurement certificates via Gotenberg for regulatory submission.

Production API Endpoints

In production mode, interactive OpenAPI/Swagger browsers are disabled and all /api/v1/* endpoints require a valid X-API-Key header.

Method & Route	Authentication	Operational Function
`GET /healthz`	Public	Liveness probe confirming worker process responsiveness.
`GET /readyz`	Public	Readiness probe verifying PostgreSQL connectivity and schema readiness.
`POST /api/v1/campaigns`	`X-API-Key`	Create and configure a new customs/FX apurement campaign.
`POST /api/v1/ingest/*`	`X-API-Key`	Ingest and classify customs declarations, invoices and bank transfer proofs.
`POST /api/v1/reconcile/*`	`X-API-Key`	Execute deterministic + MILP reconciliation across ingested campaign documents.
`POST /api/v1/hitl/*`	`X-API-Key` / Signed Token	Record human-in-the-loop review decisions and overrides.
`POST /api/v1/deliverables/*`	`X-API-Key`	Generate audit-ready Excel workbooks and PDF regulatory dossiers.