# STA Official Web Services And System Map

Status: 2026-06-01

This note captures the local STA implementation map after validating the
official BCB STA Web Services path. It does not contain credentials and does
not contain any STA-H credential value.

## Confirmed Wire Path

The active client is `StaConnector.Sta.Client`. Its external BCB path is the
official STA Web Services REST surface under `/staws`, not the internal Phoenix
`/api/v1` routes used by local producers and the admin UI.

Required BCB sequence:

1. Request protocol with `POST /staws/arquivos`.
2. Send file content with `PUT /staws/arquivos/{protocolo}/conteudo`.
3. Reconcile upload position with `GET /staws/arquivos/{protocolo}/posicaoupload`.
4. Query or download by protocol with the official `/staws/arquivos` resources.

Hashing is SHA-256 over the file bytes. Upload/download resume uses
`Content-Range`, `Range`, and BCB upload position reconciliation.

## System Identifier Source Of Truth

The canonical source is `StaConnector.Sta.Systems`.

| Group | Values |
| --- | --- |
| STA query filters (`sistemas`) | `CCS`, `CIR`, `CMP`, `STR`, `SPI`, `CAM`, `LDL`, `DICT`, `JUD` |
| Core routing P-codes | `PCCS001`, `PSBA001`, `PSMB001`, `PGEN001`, `PSCR001`, `PDIM001`, `PPGV001`, `PEFI001` |
| CADOC P-codes | `PCAD2020`, `PCAD2030`, `PCAD2060`, `PCAD2061`, `PCAD3010`, `PCAD3020`, `PCAD3040`, `PCAD3042`, `PCAD3044`, `PCAD3050`, `PCAD4010`, `PCAD4016`, `PCAD4060`, `PCAD4111`, `PCAD5011`, `PCAD5300`, `PCAD5500`, `PCAD6209`, `PCAD9010`, `PCAD9011` |

Consumers must validate through `Systems.valid?/1` and persist the canonical
uppercase value returned by `Systems.normalize/1`.

Query consumers must validate through `Systems.valid_query_system?/1` or
`Systems.normalize_query_system/1`. STA-H rejected upload/document identifiers
such as `PSBA001` in the `sistemas` query parameter during the 2026-05-31
homologation smoke; SISBAJUD files are discovered with `JUD`.

## Outbound Upload Design

```mermaid
flowchart LR
    Core["Core producers"] -->|"NATS monetarie.sta.file.upload"| Consumer["StaConnector.Nats.Consumer"]
    Core -->|"NATS monetarie.sta.regulatory.upload"| Consumer
    Consumer -->|"normalize envelope data/root"| Systems["StaConnector.Sta.Systems"]
    Systems -->|"valid? + normalize"| Outbound["StaConnector.Outbound.submit_file"]
    Outbound --> Files[("outbound_files")]
    Outbound --> Jobs[("oban_jobs nats_publish")]
    Worker["Outbound worker"] --> Client["StaConnector.Sta.Client"]
    Client -->|"POST /staws/arquivos with SHA-256"| BCB["BCB STA-H/STA"]
    Client -->|"PUT /staws/arquivos/{protocolo}/conteudo"| BCB
    Client -->|"GET status/posicaoupload by protocolo"| BCB
```

```mermaid
sequenceDiagram
    participant Core
    participant NATS
    participant Consumer as STA NATS Consumer
    participant Systems as STA Systems
    participant Outbound as Outbound Context
    participant DB as Postgres
    participant Client as STA Client
    participant BCB as BCB STA Web Services

    Core->>NATS: publish monetarie.sta.file.upload
    NATS->>Consumer: deliver JSON payload
    Consumer->>Consumer: accept data envelope or root payload
    Consumer->>Systems: validate and normalize system_id
    Systems-->>Consumer: canonical system_id
    Consumer->>Outbound: submit_file(system_id, file_name, content_base64)
    Outbound->>DB: insert outbound_files pending
    Outbound->>DB: insert nats_publish outbox job
    Client->>DB: pick pending outbound file
    Client->>BCB: POST /staws/arquivos with SHA-256
    BCB-->>Client: protocol
    Client->>BCB: PUT content by protocol
    Client->>BCB: GET upload position/status
    Client->>DB: persist protocol/status
```

## Implemented On 2026-05-31

- Centralized STA system identifiers in `StaConnector.Sta.Systems`.
- Replaced duplicated validation lists in outbound, stats, route config, API V1
  files controller, files channel, metrics, and admin metrics/statistics.
- Added CADOC `PCAD*` acceptance for Core-originated regulatory reports.
- Implemented generic `monetarie.sta.file.upload` consumer path:
  `system_id`, `file_name`, and `content_base64` are validated before queueing.
- Removed STA-side SISBAJUD XML fabrication. The
  `monetarie.sta.sisbajud.response` consumer now requires an explicit `.zip`
  payload with base64 content and SISBAJUD document id `5302` or `5312`.
- Kept file content out of logs and rejected arbitrary `file_path` from NATS
  payloads.
- Added focused tests for system identifiers, outbound normalization, and NATS
  generic upload queueing.

## SISBAJUD Response Contract

The STA consumer must not invent SISBAJUD response content. Core must publish a
real response file on `monetarie.sta.sisbajud.response` using this contract:

```json
{
  "file_name": "SISBAJUD_RET_5312_YYYYMMDD.zip",
  "content_base64": "<base64 zip bytes>",
  "metadata": {
    "tipo_arquivo": "5312"
  }
}
```

Accepted document ids are `5302` for production response files and `5312` for
homolog response files. The ZIP must contain the fixed-width SISBAJUD TXT
validated against the current CNJ/BCB layout. Payloads that only carry
`response_content`, non-ZIP file names, invalid base64, or missing document id
are rejected locally and are not queued for upload.

Core-side update: `core/backend/lib/monetarie/use_cases/judicial/nats_handler.ex`
no longer publishes the legacy `response_content` contract to STA. The
STA-bound path is the formal file-processing route:
`FileProcessor` -> `ResponseBuilder` -> `ResponseArchive` -> `RegulatoryFile`
-> `StaDelivery`, with ZIP content stored as base64 and document metadata
`5302`/`5312`.

Core must set `SISBAJUD_ENVIRONMENT=homologation` in homolog deployments so
the response header and ZIP metadata both use `5312`. Production defaults to
`5302`.

## Live Homolog Smoke On 2026-05-31

AWS profile/region: `monetarie`, `sa-east-1`.

Current homolog deployment revalidated on 2026-06-01 after final deploy:

- Cluster: `monetarie-greenfield-homolog`
- ECS service: `sta-api`
- Task definition: `monetarie-sta-api-homolog:30`
- Image: `364807861246.dkr.ecr.sa-east-1.amazonaws.com/monetarie/sta-api:codex-20260601-b8fe6f518e-sta-admin-outbound`
- Digest:
  `sha256:7cc3943d4e2ab1111378d8ba1e070a661a58f969ff3efa1b8019cc904904511b`
- Runtime platform: `ARM64` / `LINUX`
- `STA_ENVIRONMENT=homologation`
- `SIMULATOR_ENABLED=false`
- `STA_WORKERS_ENABLED=true`
- `POLLER_ENABLED=false`
- ECS state: `ACTIVE`, `desired=1`, `running=1`, `pending=0`,
  primary rollout `COMPLETED`, `failed=0`.
- Target group `monetarie-gf-sta-api-homolog`: one target `healthy` on port
  `4000`.

Related services from the same deploy wave:

- `core-api`: `monetarie-core-api-homolog:96`, image
  `core-api:codex-20260601-d6d919f2c-sta-regulatory`,
  `SISBAJUD_ENVIRONMENT=homologation`, target groups healthy.
- `core-admin-ui`: `monetarie-core-admin-ui-homolog:7`, image
  `core-admin-ui:codex-20260601-d6d919f2c-sta-regulatory`, target group
  healthy.

Smoke evidence:

- Log stream: `sta-api/sta-api/1cf0f68ab4b74b84b4c2e33c5d46087e`
- `advanced_query` with no system filter returned 30 rows.
- `advanced_query` with `systems=["JUD"]` returned 21 SISBAJUD `AJUD*` rows.
- `list_available_files(["JUD"], since: "2026-05-13T00:00:00")` returned 21
  `AJUD*` files.
- `list_available_files(["PSBA001"])` and advanced `systems=["PSBA001"]` are
  now rejected locally because `PSBA001` is not a STA `sistemas` query filter.
- Download attempts for protocols `82672929` (`AJUD301`), `82672930`
  (`AJUD308`), and `82679073` (`AJUD305`) reached STA-H but returned HTTP 403
  from BCB: file unavailable or operator not authorized for download.

Interpretation: STA-H connectivity, credentials, TLS, query format, date format,
and SISBAJUD file discovery are working. The remaining blocker for content
download is BCB/Sisbacen authorization for the operator/type/dependency, not the
wire endpoint.

## Operational Notes

- Do not trigger real STA producers until BCB download authorization and the
  relevant upload type are explicitly confirmed.
- Keep STA-H credentials in runtime secrets only. Do not print values in logs or
  test artifacts.
- Upload should wait for an explicitly allowed test file/type and SISBAJUD
  response layout verification.