Skip to main content
Lerian STA moves files in two directions. Each exchange is one transfer, a single file that moves between the institution and BACEN. A protocol number tracks the transfer through BACEN’s protocol lifecycle. Each end verifies the SHA-256.

​
Outbound submission

The institution, or an upstream Lerian product, stores the file in the Lerian STA bucket and creates a transfer whose file reference is outbound/<file name>. When TRANSFER_SCHEDULER_ENABLED is true, a worker computes the file’s SHA-256 and size and obtains a protocol number from BACEN that declares them. It uploads the file’s bytes. BACEN validates the bytes against the declared SHA-256. Within the configured deduplication window, a completed request with the same tenant and key replays its cached result and returns X-Idempotency-Replayed: true, when that result is available in the idempotency store. Without the header, Lerian STA derives the key from the source product, the selected credential, the document type, the file reference, and the file name. If your service creates transfers in reaction to an event, send a key derived from that event’s identifier. Retries of one trigger then carry the same key. The transfer advances through BACEN’s lifecycle: At the ceiling, Lerian STA cancels the transfer. Each transfer also carries a wall-clock TTL (44 hours by default), counted from when BACEN assigns its protocol. When the TTL runs out, Lerian STA cancels the transfer, or marks it Evaluation unconfirmed if BACEN still owed a verdict.

​
Inbound discovery and download

When TRANSFER_INBOUND_ENABLED is true, Lerian STA polls BACEN for available files, per active tenant. Each inbound source configuration sets its polling interval, from 15 to 1,800 seconds. For each file, Lerian STA matches the file’s BACEN system code against the tenant’s inbound source configurations. A file that matches none takes the source product unrouted. Lerian STA then downloads the bytes. It verifies the bytes against BACEN’s reported SHA-256. It stores the file durably in object storage. When the verified file is a single-entry ZIP archive, Lerian STA extracts the entry and delivers it instead of the archive. The claim-check then describes the extracted file: object_key, file_name, size_bytes, and sha256 refer to the entry. Lerian STA computes that sha256 over the extracted bytes. TRANSFER_INBOUND_EXTRACT_MAX_EXPANSION_RATIO and TRANSFER_INBOUND_EXTRACT_MAX_EXTRACTED_BYTES bound the extracted size. When Lerian STA does not extract an entry, it delivers the file as received. The claim-check then carries the hash and size that BACEN reported. When the hash does not match, Lerian STA makes up to 3 attempts by default, then ends the transfer as inconsistent. When a download fails, it makes up to 5 attempts by default, then cancels the transfer. When BACEN refuses to authorize the download, the transfer ends as not authorized at once. In each case, Lerian STA does not deliver the file to its source product.

​
Operator actions

An operator can act only where the transfer’s state and configuration permit it:
  • Cancel when the state machine permits a transition to Canceled, which excludes Integrity check and Delivered. The cancel is local. Lerian STA sends nothing to BACEN.
  • Retry an outbound transfer when it is non-terminal, has fewer than 5 upload attempts, and its TTL has not expired. This threshold stays at 5 whatever the configured ceiling. Each retry counts as one attempt.
  • Mark urgent, when TRANSFER_INBOUND_ENABLED is true, an inbound transfer in AvailableForDownload whose source product has urgency enabled on every enabled configuration. It fails closed otherwise.