> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Operando o Lerian STA

> Operando o Lerian STA: credenciais de operador do BACEN, rotação de senha em três fases e conciliação de protocolo.

Três realidades do hub de arquivos do BACEN moldam o Lerian STA. As credenciais por instituição expiram, cada transferência de saída tem um tempo de vida limitado, e o BACEN não torna idempotente a etapa de criação de protocolo. O Lerian STA concilia na granularidade do número de protocolo do BACEN.

## Pollers

***

Quando `SCHEDULER_ENABLED` é `true`, o scheduler roda o poller de status de saída. O poller se autoenfileira com um backoff indexado por estado.

O Lerian STA mantém todas as credenciais de uma instituição em um único orçamento de 10 transferências de arquivo simultâneas e 10 comandos por minuto, que a rotação de senha compartilha. Ele reserva 20 consultas por minuto para a descoberta de entrada por padrão.

## Credenciais

***

Cada credencial é uma **senha de operador** do BACEN. O Lerian STA a identifica por código da instituição e ID do operador. O Lerian STA a armazena criptografada com criptografia envelope. Os operadores podem criar, atualizar, testar a conectividade de, rotacionar e revogar uma credencial. Uma atualização altera apenas o ID do operador ou a descrição.

### Qual credencial uma transferência usa

Uma requisição de criação de transferência seleciona sua credencial do BACEN de uma de três formas. O Lerian STA aplica a primeira que a requisição carrega:

1. `credentialId`: o Lerian STA usa essa credencial.
2. `institutionCode` sem `credentialId`: o Lerian STA usa a única credencial não revogada dessa instituição.
3. Nenhum dos dois campos: o Lerian STA usa a única credencial não revogada que tem.

A resposta `201` carrega o `credentialId` que o Lerian STA usou. Para deixar um campo sem valor, omita-o ou envie `null`. Uma string vazia retorna `400` com `STA-0014`.

| Código | Status | Quando |
| - | - | - |
| `STA-0105` | 422 | A requisição não tem nenhum dos dois campos, e o Lerian STA não tem credencial não revogada. |
| `STA-0106` | 422 | A requisição não tem `credentialId`, e mais de uma credencial não revogada é candidata. |
| `STA-0107` | 422 | Nenhuma credencial não revogada corresponde a `institutionCode`. |
| `STA-0005` | 404 | `credentialId` não identifica nenhuma credencial. |
| `STA-0007` | 409 | A credencial selecionada não está ativa, por exemplo durante uma rotação de senha. |

Um `409` durante uma rotação de senha não é permanente. Repita a mesma requisição após um backoff.

## Rotação de senha

***

A rotação é um protocolo de três fases que mantém a senha antiga e a nova até o BACEN confirmar uma delas:

1. **Preparar** a nova senha localmente.
2. **Alterá-la** no BACEN.
3. **Promovê-la** localmente.

Uma **varredura de recuperação** resolve rotações deixadas em andamento. Ela roda uma vez no boot do worker quando `CREDENTIALS_RECOVERY_ON_BOOT` é `true`, e em cada varredura de credenciais quando `SCHEDULER_ENABLED` é `true`. Se o BACEN não aceita nem a senha antiga nem a nova, o Lerian STA trava a credencial em um estado de erro para uma redefinição manual de credencial.

## Monitoramento de expiração de senha

***

O BACEN exige trocas periódicas de senha. O Lerian STA rastreia a expiração informada pelo BACEN de cada credencial por meio de um read-through cache. Ele projeta uma **faixa de saúde** com os dias restantes. As faixas são healthy acima de 15 dias, warning de 6 a 15, critical de 1 a 5 e expired em 0 ou menos. O operador pode então rotacionar a senha antes que o BACEN o bloqueie.

## Retenção e TTL de protocolo

***

* **TTL de protocolo de saída.** Cada transferência de saída tem um tempo de vida em tempo real, contado a partir do momento em que o BACEN atribui seu protocolo. O padrão é 44 horas (`TRANSFER_TTL_HOURS`).
* **Transferências canceladas e inconsistentes.** Quando `SCHEDULER_ENABLED` é `true`, o Lerian STA as exclui quando a última mudança de estado tem mais de 7 dias (`SCHEDULER_QUARANTINE_RETENTION_DAYS`).
* **Retenção de entrada.** Uma política de ciclo de vida no bucket controla por quanto tempo os arquivos de entrada permanecem.

## Conciliação e contingência

***

O Lerian STA concilia na granularidade de uma transferência por número de protocolo do BACEN. Na descoberta, o número de protocolo é a chave de idempotência: um protocolo já registrado não cria uma segunda transferência.

O BACEN não oferece criação de protocolo idempotente. Uma segunda criação pode duplicar o arquivo no BACEN. Quando uma transferência tem uma marca persistente de tentativa de criação, mas não tem número de protocolo, o Lerian STA a coloca em **Criação de protocolo não confirmada**. Um operador deve conciliar essa tentativa. O Lerian STA não repete a criação marcada.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.