# Estudo de Conformidade do Módulo STA — Monetarie

**Data:** 26/04/2026
**Escopo:** `monetarie/sta/*` (Elixir/Phoenix), integrações `monetarie/core/*` e `monetarie/clst/*`
**Referência normativa:** [Manual de utilização dos Web Services do STA — BCB v1.5 (jul/2022)](https://www.bcb.gov.br/content/acessoinformacao/sisbacen_docs/Manual_STA_Web_Services.pdf), [Manual STA Web](https://www.bcb.gov.br/content/acessoinformacao/sisbacen_docs/Manual_STA_Web.pdf), [Entenda o STA](https://www.bcb.gov.br/Adm/STA/STA_Entenda_o_STA.asp), [Leiautes RSFN](https://www.bcb.gov.br/estabilidadefinanceira/leiautearquivosrsfn) e [Certificação Digital ICP‑Brasil](https://www.bcb.gov.br/estabilidadefinanceira/certificacaodigital).
**Autor do estudo:** Computer (assistente IA) sob direção de Luiz Marcelo
**Status:** Diagnóstico inicial — requer ação de engenharia

---

## 1. Sumário Executivo

O módulo `sta/` da Monetarie está **estruturalmente bem desenhado** (Phoenix + Vue + OTP, fila NATS, parsers plugáveis, telemetria, hot‑reload de configuração) e **endereça corretamente o caminho REST** introduzido pelo Manual STA Web Services v1.5. Porém, **existem cinco bugs bloqueantes** que impedem o módulo de operar com o BCB em homologação ou produção, e **diversos gaps funcionais** que comprometem aderência ao manual oficial e à entrada em conformidade regulatória do core bancário.

### Conclusão de alto nível

| Dimensão | Avaliação |
|---|---|
| Arquitetura geral (OTP, NATS, Phoenix, Vue, observabilidade) | ✅ Sólida |
| Endpoint base e ambientes (homol/prod) | ✅ Corretos |
| Autenticação HTTP Basic (RFC 7617, conforme manual v1.5) | 🟡 Parcial — implementa Basic, falta gestão de senha e ICP‑Brasil para parte das obrigações |
| Operações REST do STA (POST /arquivos, PUT /conteudo, GET /conteudo, /situacao, /disponiveis, /arquivos, /posicaoupload, /senhaws/senha) | 🔴 Incompleto e com bugs críticos |
| Suporte a transferência em partes (Content‑Range / Range / If‑Match / If‑Unmodified‑Since / ETag) | 🔴 Ausente |
| Rate limiting diferenciado (10 concorrentes, 120/min consultas, 10/min mudanças de situação) | 🔴 Único bucket — não diferencia |
| Mapeamento de estados (`codigoEstado` 1–75) ao status interno | 🔴 Ausente |
| Layouts de negócio (ACCS001‑012, ACIR, ACMP, ASCG, ASPB/ASTR, ABMA, ALFL, APTX, AGEN) | 🔴 Apenas stubs; CCS implementado como flat‑file quando o leiaute oficial é XML/XSD |
| Identificadores de documento (`IdentificadorDocumento`) usados pelo `core` (PCCS001, PSCR001 …) | 🟡 Convenção plausível mas não confirmada contra a tabela oficial de sistemas STA |
| Validação de cadeia ICP‑Brasil no pool Finch | 🔴 Não configurada |
| Bloco `<Destinatarios>` na requisição de protocolo | 🔴 Ausente |
| Código morto (módulo SOAP) | 🟡 Manter ou remover — decidir |

### 5 Bugs bloqueantes (P0)

1. **Path do upload usa protocolo `0` literal** — `client.ex:543` envia para `/arquivos/0/conteudo`, ignorando o protocolo recebido em `request_protocol`. Resultado: **toda gravação no BCB falhará com HTTP 404**.
2. **Hash SHA‑256 calculado sobre o NOME do arquivo, não sobre o CONTEÚDO** — `client.ex:512`. Resultado: **BCB rejeitará 100% das transferências por divergência de hash**.
3. **Tamanho do arquivo fixado em `0`** — `client.ex:518` envia `<Tamanho>0</Tamanho>`. Resultado: **protocolo será gerado para tamanho zero e qualquer envio com bytes será recusado**.
4. **Falta o bloco `<Destinatarios>` no XML de requisição de protocolo** — manual exige para fluxos com múltiplas dependências/IF destinatárias.
5. **Operação de upload é monolítica** — não há `PUT` parcial via `Content-Range`, nem leitura de `posicaoupload` para retomada após falha. Para arquivos grandes (SCR, CCS completo) o upload **não consegue se recuperar de quedas de conexão**.

### Bugs sérios (P1)

6. Parser de CCS é stub posicional (`parsers/ccs.ex`), mas os leiautes oficiais ACCS001‑ACCS012 são **XSD/XML** desde 2015 (ACCS010‑012 desde 2021).
7. Download não usa `Range`, `If-Match` (ETag) nem `If-Unmodified-Since` — perde a recuperação parcial e a verificação de integridade contra a versão original.
8. Mudança de situação (`PUT /arquivos/situacao`) só implementa `REC` — falta `A_REC` (cancelamento de recebimento) e mudança em lote (separador `;`).
9. Rate limiter usa um único bucket de 120/min e 10 concorrentes — manual exige **três limites distintos** (10 transferências simultâneas, 120 consultas/min, 10 alterações de situação/min).
10. Gestão de senha (`/senhaws/senha`, `GET /senhaws/senha/vencimento`) não implementada — senha BCB **expira a cada 90 dias** e o sistema fica fora do ar quando isso ocorre.
11. Códigos de estado retornados pelo BCB (1, 2, 5, 10, 15, 20, 25, 30, 35, 45, 55, 65, 70, 75) não são mapeados para o enum interno — workers tomam decisões com base em descrição textual.
12. `Authorization` não é preemptivo no caminho de cliente — manual recomenda enviar em **toda** requisição (caso contrário o BCB devolve `401` desnecessário e gasta um slot de rate limit).
13. Pool Finch não configura `transport_opts` com a cadeia ICP‑Brasil (raiz e intermediárias) — em produção isso quebra o handshake TLS contra `sta.bcb.gov.br`.
14. Consulta avançada `?tipoConsulta=AVANC` ausente — sem ela é impossível auditar histórico por janela temporal e por situação.

### Riscos de governança e regulatórios

- **CCS (Circular 3.978/2020 e Resolução BCB 119)**: Monetarie é IF participante direto e tem prazos diários para atualização cadastral. Falha no STA = multa.
- **SCR (Resolução CMN 5.037)**: envio mensal e diário do PSCR001 — também sob ônus de multa por atraso.
- **SISBAJUD (Lei 14.711/2023)**: tempo de resposta a ordens judiciais é regulado em 24h. Sem retomada de upload, qualquer falha de rede atrasa a entrega.

---

## 2. Mapeamento Técnico — Spec Oficial × Implementação Atual

### 2.1 Endpoints

| Endpoint oficial | Método | Implementado? | Localização | Observação |
|---|---|---|---|---|
| `/arquivos` (requisição de protocolo) | POST | 🟡 Parcial (3 bugs P0) | [`client.ex:510-523`](../../backend/lib/sta_connector/sta/client.ex) | Hash, Tamanho e Destinatarios incorretos |
| `/arquivos/{protocolo}/conteudo` (upload completo) | PUT | 🔴 Bug P0 | [`client.ex:540-544`](../../backend/lib/sta_connector/sta/client.ex) | Path hardcoded `/arquivos/0/conteudo` |
| `/arquivos/{protocolo}/conteudo` (upload parcial via `Content-Range`) | PUT | 🔴 Ausente | — | Necessário para arquivos > 100 MB ou retomada |
| `/arquivos/{protocolo}/posicaoupload` | GET | 🔴 Ausente | — | Necessário para retomar upload após queda |
| `/arquivos/{protocolo}/conteudo` (download completo) | GET | 🟡 Parcial | [`client.ex:525-527`, `:575-582`](../../backend/lib/sta_connector/sta/client.ex) | Sem `Range`, sem `If-Match`, sem `If-Unmodified-Since`; ETag não armazenado |
| `/arquivos/situacao` | PUT | 🟡 Parcial | [`client.ex:529-538`](../../backend/lib/sta_connector/sta/client.ex) | Apenas `REC`; falta `A_REC` e batching |
| `/arquivos/disponiveis` | GET | 🟡 Parcial | [`client.ex:503-508`](../../backend/lib/sta_connector/sta/client.ex) | Falta filtros `dependencia` e `identificadorDocumento` |
| `/arquivos?tipoConsulta=PROT` | GET | 🔴 Ausente | — | Necessário para auditar entrega |
| `/arquivos?tipoConsulta=AVANC` | GET | 🔴 Ausente | — | Auditoria por janela temporal |
| `/senhaws/senha` (troca) | PUT | 🔴 Ausente | — | Senha expira em 90 dias |
| `/senhaws/senha/vencimento` | GET | 🔴 Ausente | — | Para alertar antes do vencimento |

### 2.2 URL base por ambiente

| Ambiente | URL oficial STA | URL Senha | Implementado? |
|---|---|---|---|
| Homologação | `https://sta-h.bcb.gov.br/staws` | `https://www9.bcb.gov.br/senhaws` | ✅ STA / 🔴 Senha |
| Produção | `https://sta.bcb.gov.br/staws` | `https://www3.bcb.gov.br/senhaws` | ✅ STA / 🔴 Senha |

### 2.3 Autenticação e segurança

| Requisito | Status | Localização | Ação |
|---|---|---|---|
| HTTP Basic Auth (RFC 7617) preemptivo em **toda** requisição | 🟡 Implementado mas não obrigatório a cada chamada | [`client.ex:492-500`](../../backend/lib/sta_connector/sta/client.ex) | Auditar middleware Finch e garantir que sempre injeta header |
| Cabeçalho `Connection: keep-alive` | ✅ | [`client.ex:458`](../../backend/lib/sta_connector/sta/client.ex) | OK |
| Hash do conteúdo em SHA‑256 (lowercase hex, full content) | 🔴 Calculando sobre nome | [`client.ex:512`](../../backend/lib/sta_connector/sta/client.ex) | Reescrever — calcular sobre `content` antes do `request_protocol` |
| Validação de cadeia ICP‑Brasil no TLS (raiz + intermediárias) | 🔴 Não configurada | Pool Finch | Adicionar `transport_opts: [cacertfile: priv("icp-brasil/cadeia.pem"), verify: :verify_peer, depth: 5, customize_hostname_check: ...]` |
| Certificado A1/A3 do procurador BCB para assinatura de payloads ACCS/ASPB | 🔴 Não tratado | — | Necessário para arquivos XSD assinados (ACCS001, ACCS010, ASPB005) |
| Senha BCB rotacionada a cada ≤90 dias | 🔴 Sem cron, sem alerta | — | Implementar `Sta.PasswordManager` GenServer + cron diário |
| Credenciais BCB em segredo (Vault/secrets) | 🟡 Em config + env | [`client.ex:493-496`](../../backend/lib/sta_connector/sta/client.ex) | Mover para Vault/SecretsManager; nunca em `sta_config.json` |

### 2.4 Limites de uso (enforce do BCB)

Manual oficial (seção 5):

- **10** transferências (upload OU download) **simultâneas** por instituição.
- **120** consultas por minuto (qualquer GET de listagem ou consulta).
- **10** alterações de situação (`PUT /arquivos/situacao`) por minuto.
- **48 h** de validade do protocolo gerado em `POST /arquivos` (após esse prazo precisa requisitar novo).

Implementação atual:

- [`client.ex:48-50`](../../backend/lib/sta_connector/sta/client.ex): janela 60 s, max 120/min e max 10 simultâneos — **bucket único**, não diferencia consulta de mudança de situação.
- Não há tracking de validade do protocolo (48 h).

**Ação:** dividir em três `RateLimiter` GenServers (`:transfers`, `:queries`, `:status_changes`) e adicionar TTL no `OutboundFile` para invalidar protocolo.

### 2.5 Códigos de estado (`codigoEstado`) — manual seção 7

| Código | Descrição | Mapeado no código? |
|---|---|---|
| 1 | Protocolo gerado | 🔴 |
| 2 | Disponível para download | 🔴 |
| 5 | Transmissão iniciada | 🔴 |
| 10 | Transmissão finalizada (aguardando validação) | 🔴 |
| 15 | Validação em andamento | 🔴 |
| 20 | Recebido pelo Bacen | 🔴 |
| 25 | Entregue ao destinatário | 🔴 |
| 30 | Em processamento pelo destinatário | 🔴 |
| 35 | Aceito | 🔴 |
| 45 | Cancelado | 🔴 |
| 55 | Inconsistente | 🔴 |
| 65 | Rejeitado | 🔴 |
| 70 | Download iniciado | 🔴 |
| 75 | Download finalizado | 🔴 |

**Ação:** criar `StaConnector.Sta.StateCode` com `from_int/1`, `terminal?/1`, `success?/1`, `failure?/1` e mapear nos workers (`inbound/worker.ex`, `outbound/worker.ex`).

### 2.6 Códigos HTTP de erro (manual seção 8)

| Status | Significado oficial | Tratamento atual |
|---|---|---|
| 400 | Erro de validação no payload | ✅ via `Error.from_http_status/2` |
| 401 | Falha de autenticação (Basic) | ✅ tratado especificamente em `client.ex:470-471` |
| 403 | Sem permissão para o sistema/operação | 🟡 genérico |
| 404 | Protocolo inexistente / endpoint inválido | 🟡 genérico |
| 410 | Protocolo expirado (48 h) | 🔴 não diferencia — deveria gerar novo protocolo |
| 412 | Pré‑condição falhou (`If-Match` / `If-Unmodified-Since`) | 🔴 não tratado |
| 416 | `Range` inválido | 🔴 não tratado |
| 429 | Rate limit excedido (BCB também responde) | 🔴 não tratado — só limita do lado cliente |
| 501 | Operação não implementada | 🟡 genérico |

**Ação:** estender `StaConnector.Sta.Error.from_http_status/2` com casos específicos e estratégias de retry seletivas.

---

## 3. Mapeamento de Negócio — Sistemas / Leiautes

### 3.1 Leiautes RSFN oficiais (extração 26/04/2026)

Conforme [página oficial RSFN](https://www.bcb.gov.br/estabilidadefinanceira/leiautearquivosrsfn), 9 grupos / 44 arquivos:

#### Grupo CCS — Cadastro de Clientes do SFN
| ID | Descrição | Formato | Vigência | Link |
|---|---|---|---|---|
| ACCS001 | Atualização diária de clientes | XSD | 15/05/2019 | [ACCS001.xsd](https://www.bcb.gov.br/content/estabilidadefinanceira/leiautesRSFN/ACCS001.xsd) |
| ACCS002 | Resposta ao ACCS001 | XSD | 30/04/2015 | [ACCS002.xsd](https://www.bcb.gov.br/content/estabilidadefinanceira/leiautesRSFN/ACCS002.xsd) |
| ACCS003 | Validação dos relacionamentos | XSD | 15/05/2019 | [ACCS003.xsd](https://www.bcb.gov.br/content/estabilidadefinanceira/leiautesRSFN/ACCS003.xsd) |
| ACCS004 | Posição de cadastro | XSD | 15/05/2019 | [ACCS004.xsd](https://www.bcb.gov.br/content/estabilidadefinanceira/leiautesRSFN/ACCS004.xsd) |
| ACCS005 | Detalhamento de relacionamento | XSD | 30/04/2015 | [ACCS005.xsd](https://www.bcb.gov.br/content/estabilidadefinanceira/leiautesRSFN/ACCS005.xsd) |
| ACCS006 | Resposta ao ACCS005 | XSD | 30/04/2015 | [ACCS006.xsd](https://www.bcb.gov.br/content/estabilidadefinanceira/leiautesRSFN/ACCS006.xsd) |
| ACCS009 | Ocorrências do ACCS001 | DOC | 30/04/2015 | [ACCS009.doc](https://www.bcb.gov.br/content/estabilidadefinanceira/leiautesRSFN/Leiaute%20do%20Arquivo%20ACCS009.doc) |
| ACCS010 | Transferência de Relacionamentos — Solicitação | XSD | 03/09/2021 | [ACCS010.xsd](https://www.bcb.gov.br/content/estabilidadefinanceira/leiautesRSFN/ACCS010.xsd) |
| ACCS011 | Transferência — Validação do ACCS010 | XSD | 03/09/2021 | [ACCS011.xsd](https://www.bcb.gov.br/content/estabilidadefinanceira/leiautesRSFN/ACCS011.xsd) |
| ACCS012 | Transferência — Resultado do ACCS010 | XSD | 03/09/2021 | [ACCS012.xsd](https://www.bcb.gov.br/content/estabilidadefinanceira/leiautesRSFN/ACCS012.xsd) |

#### Grupo CIR — Circulação de Numerário
| ID | Descrição | Formato | Vigência |
|---|---|---|---|
| ACIR002 | Remunerações que originaram crédito consolidado | DOC | 10/09/2009 |
| ACIR003 | Estoque de Agências | DOC | 12/03/2026 |
| ACIR004 | Movimentação de Numerário | DOC | 12/03/2026 |
| ACIR005 | Numeração de Cédulas Novas em Estoque | DOC | 12/03/2026 |

#### Grupo CMP — Compe
| ACMP001 | Resultado do Processamento da Compe | DOC | 14/09/2018 |

#### Grupo GEN
| AGEN002 | Contato dos participantes do STR | TXT | 01/04/2022 |

#### Grupo LFL — Letras Financeiras de Liquidez
| ALFL001 | Ativos elegíveis | TXT | 12/03/2026 |
| ALFL002 | Operações de crédito admissíveis | TXT | 12/03/2026 |
| ALFL003 | Motivos para não admissibilidade | TXT | 12/03/2026 |

#### Grupo PTX
| APTX001 | Cotações finais da PTAX | TXT | 30/06/2011 |

#### Grupo SCG — Sistema de Controle de Garantias e Domicílio Bancário
- ASCG005, ASCG008, ASCG009, ASCG011, ASCG012, ASCG013, ASCG020, ASCG021, ASCG022, ASCG023, ASCG024, ASCG025 — 17 arquivos (DOCX/XSD/ZIP), versionamento por data‑corte 08/04/2019.

#### Grupo SEL — Selic
| ABMA | Leiautes dos arquivos ABMA | DOCX | 03/10/2022 |

#### Grupo STR — Sistema de Transferência de Reservas
| ASPB0004 | Preços de títulos públicos para redesconto | TXT | 01/07/2017 |
| ASPB005 | Contingência do STR | XSD | 27/03/2026 |
| ASPB006 | Resposta do Arquivo de Contingência do STR | XSD | 27/03/2026 |
| ASPB007 | Dicionário de Domínios | XSD | 27/12/2006 |
| ASPB020 | Relação de Erros | XSD | 06/03/2009 |
| ASTR003 | Relação de Participantes do STR | TXT | 18/11/2016 |

#### Grupos não disponíveis na página RSFN
**SPI, DICT, CAM, COS, SCR, SISBAJUD, E‑FINANCEIRA, DIMP, PGV, SIMBA** — usados na implementação Monetarie mas não publicados na página de leiautes RSFN. Esses sistemas têm **manuais próprios** (Manual de Negócios PIX/DICT, Manual SCR/MECIR, Manual SISBAJUD, Manual e‑Financeira da RFB), e seu trânsito pode ser via STA mas com documentação e identificadores em outras seções do BCB.

### 3.2 Identificadores de documento usados pela Monetarie

Mapeamento atual em [`core/backend/lib/monetarie/regulatory/sta_delivery.ex:55-62`](../../core/backend/lib/monetarie/regulatory/sta_delivery.ex):

| `report_type` (interno) | `IdentificadorDocumento` enviado | Status validação |
|---|---|---|
| `CCS` | `PCCS001` | 🟡 — leiaute oficial é `ACCS001`, prefixo `P` é convenção de "envio" mas precisa confirmação na tabela de sistemas STA |
| `SCR` | `PSCR001` | 🟡 — confirmar com Manual SCR |
| `SISBAJUD` | `PSBA001` | 🟡 — confirmar com Manual SISBAJUD |
| `E_FINANCEIRA` | `PEFI001` | 🟡 — não é STA do BCB; é entrega à RFB via SPED — **pode ser caminho errado** |
| `DIMP` | `PDIM001` | 🟡 — também é RFB, não BCB |
| `PGV` | `PPGV001` | 🟡 — confirmar |
| `SIMBA` | `PSMB001` | 🟡 — SIMBA é sistema do COAF, não BCB — **provavelmente errado** |

**Ação P1:** auditar com a área de Compliance Monetarie quais relatórios trafegam por STA‑BCB vs. SPED‑RFB vs. COAF SIMBA‑Web. Mover SIMBA, DIMP e e‑Financeira para conectores específicos (não STA).

### 3.3 Subjects NATS internos

Conforme [`sta/CLAUDE.md`](../../CLAUDE.md) e busca em `core/clst`:

| Subject | Direção | Produtor | Consumidor |
|---|---|---|---|
| `monetarie.sta.regulatory.upload` | upload | `core/regulatory/sta_delivery.ex` | `sta/outbound/worker.ex` (via consumer) |
| `monetarie.sta.file.received` | inbound | `sta/inbound/worker.ex` | `core/nats/consumers/sta_consumer.ex` |
| `monetarie.sta.file.uploaded` | outbound ack | `sta/outbound/worker.ex` | `core/nats/consumers/sta_consumer.ex` |
| `monetarie.sta.file.processed` | result | `sta/inbound/router.ex` | `core/...`, `clst/clearing/sta_handler.ex` |
| `monetarie.sta.file.error` | error | qualquer | `core` para auditoria |
| `monetarie.sta.protocol.processed` | finalização | `sta/outbound/worker.ex` | `core/regulatory/...` |
| `monetarie.sta.sisbacen.cam{NNNN}` | bilateral | adapter Câmbio | adapter Câmbio |
| `monetarie.sta.sisbajud.order` | inbound | `sta/inbound/router.ex` | `core` (SISBAJUD handler) |
| `monetarie.sta.sisbajud.response` | outbound | `core` | `sta/outbound/...` |
| `monetarie.sta.accs.generated` | gatilho | gerador CCS no `core` | `sta/outbound/...` |

**Recomendação:** consolidar a tabela de subjects em [`sta/docs/architecture/nats-subjects.md`](../architecture/) com schema (JSON Schema) por subject e versionar.

---

## 4. Análise de Arquivos do Módulo `sta/`

### 4.1 Resumo dos arquivos críticos

| Arquivo | LOC | Avaliação | Issues principais |
|---|---|---|---|
| [`backend/lib/sta_connector/sta/client.ex`](../../backend/lib/sta_connector/sta/client.ex) | 601 | 🔴 Refatorar | 5 bugs P0/P1 documentados na seção 2 |
| [`backend/lib/sta_connector/sta/operations.ex`](../../backend/lib/sta_connector/sta/operations.ex) | 548 | 🟡 OK estrutura, depende do client | Acopla com circuit breaker e rate limiter — bom; precisa expor `upload_partial`, `resume_upload` |
| [`backend/lib/sta_connector/sta/soap.ex`](../../backend/lib/sta_connector/sta/soap.ex) | — | 🔴 Código morto | REST é o caminho oficial desde v1.5; remover ou mover para `legacy/` com `@deprecated` |
| [`backend/lib/sta_connector/sta/types.ex`](../../backend/lib/sta_connector/sta/types.ex) | — | 🟡 Falta campo | Adicionar `etag`, `last_modified`, `state_code`, `expires_at` em `FileInfo` e `DownloadResult` |
| [`backend/lib/sta_connector/parsers/ccs.ex`](../../backend/lib/sta_connector/parsers/ccs.ex) | 206 | 🔴 Reescrever | Stub posicional; ACCS é XSD/XML |
| [`backend/lib/sta_connector/parsers/{cir,cmp,cam,spi,str,ldl,dict}.ex`](../../backend/lib/sta_connector/parsers/) | — | 🟡 Verificar formato | CIR/CMP são DOC, ASPB005/006/007/020 são XSD, ASTR003/AGEN002/APTX001 são TXT |
| [`backend/lib/sta_connector/inbound/poller.ex`](../../backend/lib/sta_connector/inbound/poller.ex) | 663 | 🟡 Bom mas frágil | Não trata expiração de protocolo (HTTP 410); não usa `tipoConsulta=AVANC` para reconciliação |
| [`backend/lib/sta_connector/inbound/worker.ex`](../../backend/lib/sta_connector/inbound/worker.ex) | — | 🟡 OK | Não mapeia `codigoEstado` para enum interno |
| [`backend/lib/sta_connector/outbound/uploader.ex`](../../backend/lib/sta_connector/outbound/uploader.ex) | 432 | 🔴 Refatorar | Sem retomada via `posicaoupload`, sem chunking |
| [`backend/lib/sta_connector/outbound/worker.ex`](../../backend/lib/sta_connector/outbound/worker.ex) | — | 🟡 OK | Acopla com client buggy |
| [`backend/config/sta_config.json`](../../backend/config/sta_config.json) | — | 🟡 OK | Adicionar `password_rotation_days`, `icp_brasil_chain_path` |

### 4.2 Diagrama de fluxo (atual vs. esperado)

```
[ Atual — outbound ]
core.regulatory.deliver/1
  └─> publish "monetarie.sta.regulatory.upload" (NATS)
       └─> sta.outbound.worker
            ├─> Client.request_protocol(system_id, file_name)   # 🔴 hash do nome, tamanho 0
            └─> Client.upload_file(system_id, file_name, content)  # 🔴 path /arquivos/0/conteudo
                                                                   # 🔴 sem Content-Range
                                                                   # 🔴 sem retomada via posicaoupload

[ Esperado ]
core.regulatory.deliver/1
  └─> publish "monetarie.sta.regulatory.upload" (NATS)
       └─> sta.outbound.worker
            ├─> hash = SHA-256(content)                           # ✅ sobre o CONTEÚDO
            ├─> size = byte_size(content)
            ├─> Client.request_protocol(%{
            │     identificador_documento: "PCCS001",
            │     hash: hash, tamanho: size,
            │     nome_arquivo: file_name,
            │     destinatarios: [%{tipo: "BACEN"}]               # ✅ bloco obrigatório
            │   })
            ├─> protocol = ...
            ├─> if size <= chunk_threshold:
            │     Client.upload_full(protocol, content)
            │   else:
            │     for chunk in chunks(content, 1MB):
            │       Client.upload_part(protocol, chunk, range)
            │       on_failure: pos = Client.posicao_upload(protocol)
            │                   resume_from(pos)
            ├─> Client.query_protocol(protocol, nivel: COMPL)     # ✅ confirmar estado 35 (Aceito)
            └─> publish "monetarie.sta.file.uploaded" + state_code
```

### 4.3 Resíduo Go

`cmd/`, `internal/` e `pkg/` ainda contêm o connector Go pré‑rewrite. Recomendação: mover para branch `legacy/go-connector` ou pasta `archive/go-2025/` e referenciar em [`docs/plans/2026-01-31-sta-connector-elixir-rewrite.md`](2026-01-31-sta-connector-elixir-rewrite.md). Manter no caminho ativo gera ruído em CI, scanners e revisões.

---

## 5. Checklist de Conformidade

### 5.1 Bloqueadores (P0 — corrigir antes de homologação BCB)

- [ ] **Bug 1:** corrigir path `PUT /arquivos/{protocolo}/conteudo` em `client.ex:540-544` — receber `protocol_number` como parâmetro
- [ ] **Bug 2:** calcular SHA‑256 sobre `content` em `request_protocol`, não sobre `file_name`
- [ ] **Bug 3:** enviar `<Tamanho>byte_size(content)</Tamanho>` real
- [ ] **Bug 4:** adicionar bloco `<Destinatarios>` no XML de `request_protocol`
- [ ] **Bug 5:** garantir cadeia ICP‑Brasil no Finch `transport_opts` para produção

### 5.2 Funcionalidades obrigatórias do manual (P1)

- [ ] Implementar `Client.upload_part/4` com header `Content-Range: bytes {ini}-{fim}/{total}`
- [ ] Implementar `Client.posicao_upload/1` (`GET /arquivos/{protocolo}/posicaoupload`)
- [ ] Implementar `Client.download_part/3` com header `Range: bytes={ini}-{fim}`, `If-Match`, `If-Unmodified-Since`
- [ ] Persistir `etag` e `last_modified` em `DownloadResult` e na tabela `processed_protocol`
- [ ] Adicionar `Client.change_status/2` aceitando `:rec | :a_rec` e lista de protocolos
- [ ] Adicionar `Client.query_protocol/2` (`tipoConsulta=PROT`, `nivelDetalhe=RES|BAS|COMPL`)
- [ ] Adicionar `Client.advanced_query/1` (`tipoConsulta=AVANC`)
- [ ] Adicionar `Client.password_*` (troca + consulta de vencimento) e cron de alerta quando vencimento ≤ 7 dias
- [ ] Dividir `RateLimiter` em três buckets (`:transfers`, `:queries`, `:status_changes`)
- [ ] Adicionar TTL de 48 h em `OutboundFile.protocol_expires_at`
- [ ] Mapear `codigoEstado` → `StaConnector.Sta.StateCode` (enum)
- [ ] Tratar HTTP 410 (protocolo expirado) gerando novo protocolo automaticamente
- [ ] Tratar HTTP 412 e 416 com mensagens específicas
- [ ] Tratar HTTP 429 com `Retry-After` (cliente respeita limite do servidor)

### 5.3 Parsers e leiautes (P1/P2)

- [ ] Reescrever `parsers/ccs.ex` para consumir XML/XSD ACCS001/002/003/004/005/006/009/010/011/012
- [ ] Validar parsers `cir.ex`, `cmp.ex` contra ACIR002‑005 e ACMP001 (formato DOC — possivelmente fixed‑width descrito em DOC)
- [ ] Criar parsers `aspb.ex` (ASPB005/006/007/020 XSD), `astr.ex` (ASTR003 TXT), `agen.ex` (AGEN002 TXT), `aptx.ex` (APTX001 TXT), `alfl.ex` (ALFL001‑003 TXT), `ascg.ex` (ASCG020‑025 DOCX/XSD)
- [ ] Adicionar suporte a XSD validation (Saxy + xmerl) com cache de schemas em `priv/leiautes-rsfn/`
- [ ] Baixar e versionar localmente todos os XSD/DOC/TXT da página RSFN para auditoria offline

### 5.4 Identificadores e roteamento (P1)

- [ ] Auditar `sta_system_for/1` em `core/regulatory/sta_delivery.ex` contra a tabela oficial de sistemas STA do BCB
- [ ] Mover `SIMBA`, `DIMP`, `E_FINANCEIRA` para conectores específicos (COAF / RFB SPED) — não trafegam por STA‑BCB
- [ ] Documentar em `sta/README.md` quais sistemas são suportados (lista oficial + comentário sobre exclusões)

### 5.5 Observabilidade e governança (P2)

- [ ] Métricas Prometheus separadas por `system_id` e `state_code`
- [ ] Dashboard Grafana: protocolos por estado, latência por sistema, taxa de retentativa, próxima expiração de senha
- [ ] Alerta para senha expirando ≤ 7 dias
- [ ] Alerta para upload em estado 65 (rejeitado) ou 55 (inconsistente)
- [ ] Audit log imutável (PG `audit_logs` table ou append‑only S3) de toda interação com BCB
- [ ] Rotacionar credenciais BCB via Vault/SecretsManager
- [ ] Remover credenciais de `sta_config.json` versionado

### 5.6 Limpeza técnica (P3)

- [ ] Mover/arquivar código Go (`cmd/`, `internal/`, `pkg/`) para `archive/go-2025/`
- [ ] Remover ou marcar `@deprecated` o módulo `Sta.Soap`
- [ ] Atualizar `sta/CLAUDE.md` para refletir que SOAP está deprecated
- [ ] Cobertura de teste mínima 85 % em `sta/sta/client.ex`, `sta/operations.ex`, `parsers/*`
- [ ] Testes de integração contra ambiente de homologação BCB com fixtures dos XSD ACCS

---

## 6. Plano de Implementação por Ondas

### Onda 1 — P0 hotfix (1 sprint, 3‑5 dias)

| # | Tarefa | Arquivo | Esforço |
|---|---|---|---|
| 1 | Corrigir hash, tamanho e path do upload | `client.ex` | 4 h |
| 2 | Adicionar `<Destinatarios>` no XML de protocolo | `client.ex` | 2 h |
| 3 | Configurar cadeia ICP‑Brasil no Finch | `application.ex`, `priv/icp-brasil/` | 4 h |
| 4 | Testes unitários cobrindo bugs corrigidos | `test/sta/client_test.exs` | 4 h |
| 5 | Smoke test contra `sta-h.bcb.gov.br` (homologação) | `test/integration/` | 1 dia |

### Onda 2 — Operações faltantes do manual (1‑2 sprints)

| # | Tarefa | Arquivo | Esforço |
|---|---|---|---|
| 6 | Upload em partes (`Content-Range`) | `client.ex`, `outbound/uploader.ex` | 1 dia |
| 7 | `posicaoupload` + retomada | `client.ex`, `outbound/worker.ex` | 1 dia |
| 8 | Download em partes (`Range` + ETag) | `client.ex`, `inbound/worker.ex` | 1 dia |
| 9 | `change_status` completo (REC + A_REC + batch) | `client.ex` | 4 h |
| 10 | `query_protocol` (PROT) e `advanced_query` (AVANC) | `client.ex` | 1 dia |
| 11 | Gestão de senha (`/senhaws/senha*`) + cron | `sta/password_manager.ex` (novo) | 1 dia |
| 12 | Rate limiter de 3 buckets | `sta/rate_limiter.ex` | 1 dia |
| 13 | TTL de 48 h no `OutboundFile.protocol_expires_at` | `outbound_file.ex` migration + worker | 4 h |
| 14 | Mapeamento `StateCode` enum + workers | `sta/state_code.ex` (novo) | 4 h |

### Onda 3 — Parsers e leiautes (2‑3 sprints, paralelo)

| # | Tarefa | Esforço |
|---|---|---|
| 15 | Baixar e versionar XSD/DOC/TXT em `priv/leiautes-rsfn/` | 4 h |
| 16 | Validador XSD genérico com Saxy/xmerl | 1 dia |
| 17 | Reescrever `parsers/ccs.ex` (ACCS001‑012 XSD) | 3 dias |
| 18 | Parsers ASPB, ASTR, AGEN, APTX, ALFL, ASCG | 3 dias |
| 19 | Auditar parsers CIR, CMP, CAM, SPI, STR, LDL, DICT | 2 dias |

### Onda 4 — Roteamento, observabilidade e limpeza (1‑2 sprints)

| # | Tarefa | Esforço |
|---|---|---|
| 20 | Auditar tabela `sta_system_for/1` no `core` | 4 h |
| 21 | Mover SIMBA / DIMP / E‑Financeira para conectores próprios | 2 dias |
| 22 | Métricas + dashboard + alertas | 2 dias |
| 23 | Audit log imutável | 1 dia |
| 24 | Mover credenciais BCB para Vault | 1 dia |
| 25 | Arquivar Go legado | 2 h |
| 26 | Remover/depreciar módulo SOAP | 2 h |
| 27 | Documentar arquitetura completa em `sta/docs/` (PT/EN) | 2 dias |

**Total estimado:** ~5‑7 sprints (10‑14 semanas) com 2 engenheiros sênior em Elixir + 1 SRE.

---

## 7. Itens em aberto / pendências de pesquisa

1. **Tabela oficial de sistemas STA (`IdentificadorDocumento`)** — não está nos manuais públicos consultados. É preciso solicitar ao BCB (canal Sisbacen) a relação atualizada de identificadores autorizados para a Monetarie.
2. **Manual SCR/MECIR atualizado** — confirmar identificadores e janelas de envio para o módulo SCR.
3. **Manual SISBAJUD** — confirmar se tráfega via STA ou tem canal próprio (provável que seja outro sistema, pelo Conselho Nacional de Justiça via PJe).
4. **e‑Financeira / DIMP** — sob administração da Receita Federal (SPED), não BCB. Provavelmente fora do escopo do `sta/`.
5. **SIMBA** — administrado pelo COAF; fora do STA‑BCB.
6. **Procurador BCB / certificado A1‑A3 para assinatura de XML** — alguns leiautes (ACCS, ASPB) são XML que **podem requerer assinatura digital ICP‑Brasil**. Confirmar com a área jurídica e adicionar `XmlSigner` ao stack.
7. **Validade do ACCS010** — leiaute de 2021 trata transferência de relacionamentos; confirmar se Monetarie precisa implementar ou apenas receber resposta (ACCS011/012).

---

## 8. Referências

### Normativas e manuais BCB

- [Manual STA Web Services v1.5 (jul/2022)](https://www.bcb.gov.br/content/acessoinformacao/sisbacen_docs/Manual_STA_Web_Services.pdf) — fonte primária deste estudo
- [Manual STA Web (interface usuário)](https://www.bcb.gov.br/content/acessoinformacao/sisbacen_docs/Manual_STA_Web.pdf)
- [Entenda o STA — portal BCB](https://www.bcb.gov.br/Adm/STA/STA_Entenda_o_STA.asp)
- [Leiaute dos Arquivos que Trafegam na RSFN](https://www.bcb.gov.br/estabilidadefinanceira/leiautearquivosrsfn) — listagem oficial de XSDs/DOCs/TXTs
- [Manual de Cadastro de Clientes do SFN — CCS](https://www.bcb.gov.br/content/acessoinformacao/Documents/ccs/ccs_manual.pdf)
- [Certificação Digital ICP‑Brasil — BCB](https://www.bcb.gov.br/estabilidadefinanceira/certificacaodigital)

### RFCs aplicáveis

- [RFC 7617 — HTTP Basic Authentication](https://datatracker.ietf.org/doc/html/rfc7617)
- [RFC 7233 — HTTP Range Requests](https://datatracker.ietf.org/doc/html/rfc7233) (`Range`, `Content-Range`, `If-Match`, `If-Unmodified-Since`)
- [RFC 7232 — HTTP Conditional Requests](https://datatracker.ietf.org/doc/html/rfc7232) (`ETag`)

### Internos do projeto

- [`sta/README.md`](../../README.md)
- [`sta/CLAUDE.md`](../../CLAUDE.md)
- [`sta/docs/plans/2026-01-31-sta-connector-elixir-rewrite.md`](2026-01-31-sta-connector-elixir-rewrite.md)
- [`sta/docs/plans/2026-01-31-sta-connector-design.md`](2026-01-31-sta-connector-design.md)
- [`sta/docs/plans/2026-02-01-test-files-and-real-integration.md`](2026-02-01-test-files-and-real-integration.md)

---

## 9. Próximos passos imediatos

1. **Hoje:** circular este documento entre tech lead, SRE e Compliance Monetarie.
2. **Esta semana:** abrir tickets P0 (Bugs 1‑5) e atribuir a 1 engenheiro sênior; iniciar branch `fix/sta-p0-conformance`.
3. **Próximas 2 semanas:** entregar Onda 1 com testes contra homologação `sta-h.bcb.gov.br`.
4. **Mês 1:** entregar Ondas 1 + 2 e iniciar paralelamente a Onda 3 (parsers).
5. **Antes de produção:** auditoria externa (preferencialmente PwC, Deloitte ou Vanta) com foco em conformidade BCB e ICP‑Brasil.

---

*Estudo gerado em 26/04/2026 com extração exaustiva da documentação oficial BCB. Para divergências entre este documento e o Manual oficial atualmente publicado pelo BCB, prevalece o Manual.*