Integrating with Lerian CCS

Lerian CCS exposes one REST API under /v1. Every business route needs a bearer token.

API surface

Area	Operation	Purpose
Configuration	`GET /v1/configurations`	Read the current configuration.
Configuration	`POST /v1/configurations`	Create a configuration.
Configuration	`GET /v1/configurations/{id}`	Read one configuration.
Configuration	`PATCH /v1/configurations/{id}`	Update one configuration.
Configuration	`POST /v1/configs/{configId}/conglomerate-members`	Add a member.
Configuration	`GET /v1/configs/{configId}/conglomerate-members`	List members.
Configuration	`DELETE /v1/configs/{configId}/conglomerate-members/{memberId}`	Remove a member.
Batch	`POST /v1/batches`	Generate the batch for a movement date.
Batch	`GET /v1/batches`	List batches.
Batch	`GET /v1/batches/{id}`	Read one batch.
Batch	`POST /v1/batches/{id}/approve`	Approve and start the render.
Batch	`POST /v1/batches/{id}/submit`	Alias of approve.
Batch	`POST /v1/batches/{id}/reject`	Reject a batch under review.
Batch	`GET /v1/batches/{id}/items`	List line items.
Batch	`GET /v1/batches/{id}/items/{itemId}/errors`	List item errors.
Batch	`POST /v1/batches/resend`	Resend from a terminal batch.
Batch	`POST /v1/batches/{id}/reprocess-last-event`	Admin. Re-fire the last event.
Batch	`POST /v1/batches/{id}/drain-parked-response`	Admin. Apply a parked ACCS003.
Batch	`POST /v1/batches/reconcile-partial-applies`	Admin. Repair a contradicted verdict.
Batch	`POST /v1/batches/recompute-mirror`	Admin. Recompute the mirror.
Batch	`POST /v1/batches/backfill-sta-transfer-id`	Admin. Restore a lost identity.
Detail request	`GET /v1/detail-requests`	List detail requests.
Detail request	`GET /v1/detail-requests/{id}`	Read one detail request.
Detail request	`POST /v1/detail-requests/{id}/cancel`	Cancel a detail request.
Injunction	`POST /v1/injunctions`	Record a block or unblock.
Injunction	`GET /v1/injunctions`	List injunctions.
Injunction	`GET /v1/injunctions/{id}`	Read one injunction.
Injunction	`POST /v1/injunctions/{id}/revoke`	Revoke an injunction.
Reconciliation	`POST /v1/reconciliations`	Start a run against an ACCS004.
Reconciliation	`GET /v1/reconciliations`	List runs.
Reconciliation	`GET /v1/reconciliations/{id}`	Read one run.
Reconciliation	`GET /v1/reconciliations/{id}/divergences`	List divergences.
Transfer	`POST /v1/transfers`	Create a transfer.
Transfer	`GET /v1/transfers`	List transfers.
Transfer	`GET /v1/transfers/{id}`	Read one transfer with its legs.
Audit	`GET /v1/audit/entries`	List audit entries.
Audit	`POST /v1/audit/verify-chain`	Verify the audit chain.

Operator endpoints sit outside /v1.

Endpoint	Purpose
`GET /health`	Liveness. It answers 503 while the self-probe fails.
`GET /readyz`	Readiness of every dependency.
`GET /readyz/tenant/{id}`	Readiness of one institution.
`GET /version`	Build version.
`GET /metrics`	Readiness metrics, Prometheus text.
`GET /streaming`	The event manifest.
`/system/{namespace}`	Runtime configuration.
`/swagger/*`	The API specification, when `SWAGGER_ENABLED=true`.

Authentication and tenancy

Every /v1 route takes an OAuth2 bearer token from Lerian Access Manager. Set PLUGIN_AUTH_ENABLED=true and PLUGIN_AUTH_HOST to turn the gate on. Production requires both. Each institution keeps its own database schema. The service reads the institution identity from the validated token, never from a request body, a header, or a path parameter.

Idempotency

Lerian CCS accepts an Idempotency-Key header. The header is mandatory on POST /v1/batches and optional on the cancel route. A middleware caches the first response and replays it for a repeat of the same key. Keys belong to one institution, and the default retention is 7 days.

Errors

Every error body is an RFC 9457 problem document with the media type application/problem+json. Each body carries a product code. The code values are frozen contract, so a client matches on the code, not the message text.

Code	Status	When
`CCS-0001`	409	A configuration already exists.
`CCS-0004`	404	The configuration does not exist.
`CCS-0010`	409	A non-terminal batch holds that movement date.
`CCS-0012`	400	The movement date is outside the window.
`CCS-0020`	404	The batch does not exist.
`CCS-0024`	422	The batch refuses that transition.
`CCS-0050`	400	The transfer names the institution itself.
`CCS-0061`	409	An injunction already covers that document.
`CCS-0064`	404	The detail request does not exist.
`CCS-0066`	409	The cancellable window closed.
`CCS-0074`	409	A reconciliation is already in progress.
`MYS-0008`	503	An upstream or the template is unavailable.

A route whose collaborators failed to wire answers 501.

Events

Lerian CCS publishes one business event on its own topic, with a matching dead-letter topic. The topic and the event type follow the Streaming Hub naming rule, with this service’s CloudEvents source as the namespace.

Event	Meaning
Batch submitted	The ACCS001 batch went to Lerian STA.

It carries the critical delivery posture. The service writes it to the transactional outbox in the same transaction as the state change. Streaming is off by default. While it is off, the service wires a no-operation emitter and publishes nothing. Lerian Streaming Hub is the delivery layer. Lerian CCS also publishes notifications on the exchange named by RABBITMQ_EXCHANGE.

Routing key	Meaning
`ccs.events.batch`	A batch changed state.
`ccs.events.batch.generation_failed`	Batch generation failed.
`ccs.events.detail_request.received`	A detail request arrived.
`ccs.events.detail_request.cancelled`	A detail request moved to cancelled.
`ccs.events.reconciliation.divergence`	A run found a divergence.
`ccs.outbox.dlq`	An outbox message exhausted its attempts.

Documents in those payloads are masked.

Integration conventions

Headers. CORS_ALLOWED_HEADERS carries no default. While it stays unset, a preflight response echoes the headers the browser asked for. A value you set replaces that behavior with a fixed list, so name every header your browser client sends.
Pagination. Each list route caps its own page size. A limit of 100 or less stays within every route’s cap.
Rate limits. The limiter covers /v1 only. Export and dispatch routes carry tighter tiers.
File references. The regulatory XML stays in object storage. Only file references travel over the wire.

How Lerian CCS works covers these flows.

​API surface

​Authentication and tenancy

​Idempotency

​Errors

​Events

​Integration conventions