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.
Requisition	`POST /v1/pending-requisition-queries`	Ask BACEN for the unanswered requisitions.
Requisition	`GET /v1/pending-requisition-queries/gaps`	List the unanswered requisitions.
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.
Transfer	`GET /v1/transfers-in`	List received transfers.
Transfer	`GET /v1/transfers-in/{id}`	Read one received transfer.
Transfer	`POST /v1/transfers-in/{id}/confirm`	Confirm a received transfer.
Audit	`GET /v1/audit/entries`	List audit entries.
Audit	`POST /v1/audit/verify-chain`	Verify the audit chain.
Streaming	`GET /v1/streaming/manifest`	Read the event manifest. With streaming off, the route is not mounted.

Operator endpoints sit outside /v1.

Endpoint	Purpose
`GET /health`	Liveness.
`GET /readyz`	Readiness of every dependency.
`GET /readyz/tenant/{id}`	Readiness of one institution.
`GET /version`	Build version.
`GET /metrics`	Readiness metrics, Prometheus text.
`/swagger/*`	The API specification, when `SWAGGER_ENABLED=true` outside production.

Authentication and tenancy

Every /v1 route takes an OAuth2 bearer token from Lerian Access Manager. With PLUGIN_AUTH_ENABLED=true and PLUGIN_AUTH_HOST, Lerian Access Manager authorizes each request. Only a development ENV_NAME outside saas accepts false. Each institution keeps its own database schema.

Idempotency

Lerian CCS accepts an optional X-Idempotency header on most mutating routes. A middleware caches the first response and replays it for a repeat of the same key. A repeat with a different body answers 422, and a repeat while the first request runs answers 409. Keys belong to one institution, and the default retention is 7 days.

Errors

A business error answers an RFC 9457 problem document, with the media type application/problem+json and 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-0074`	409	A reconciliation is already in progress.
`MYS-0008`	503	An upstream or the template is unavailable.

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. With RABBITMQ_ENABLED=true, Lerian CCS also publishes notifications on the exchange named by RABBITMQ_EXCHANGE.

Routing key	Meaning
`ccs.events.batch`	A batch finished generation and waits for review.
`ccs.events.batch.generation_failed`	Batch generation failed.
`ccs.events.reconciliation.divergence`	A run found a divergence.

Documents in those payloads are masked.

Integration conventions

Headers. While CORS_ALLOWED_HEADERS stays unset, a fixed default list applies, and it does not include X-Idempotency. A value you set replaces that list, so name every header your browser client sends.
Pagination. Each list route caps its own page size. A page size of 100 or less stays within every route’s cap.
Rate limits. The limiter covers /v1 only. Mutating requests and heavy reads such as audit queries carry tighter tiers.
File references. The regulatory XML stays in object storage. The API and the broker messages carry file references only.

How Lerian CCS works covers these flows.

​API surface

​Authentication and tenancy

​Idempotency

​Errors

​Events

​Integration conventions