> ## 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 SISBAJUD > Operando a Lerian SISBAJUD Mensageria: instituições, ordens que precisam de atenção, janelas de resposta, rotação de chaves, proteção de dados, papéis e a superfície HTTP. Esta página descreve como operar a **Mensageria**. [Operando o Lerian SISBAJUD executor](https://docs.lerian.studio/pt/rails/sisbajud/sisbajud-executor-operations.md) descreve o executor. ## Instituições *** `POST /v1/institutions` registra uma instituição na Mensageria. O corpo tem estes campos: | Campo | Significado | | - | - | | `institutionId` | O UUID da instituição. | | `institutionCode` | A raiz do CNPJ da instituição, com 8 dígitos. A Mensageria a compara com a raiz do CNPJ no header de cada arquivo e a escreve nos arquivos de resposta. | | `retryPolicyConfig` | Opcional. A política de retentativa, em JSON. | | `enabled` | Se a instituição está ativa. | A requisição cria o keyset de tokenização e o keyset de auditoria da instituição. Uma segunda requisição com o mesmo `institutionId` retorna `409`. `PATCH /v1/institutions/{institutionId}` altera `institutionCode`, `retryPolicyConfig` ou `enabled`. ### Registre a instituição nos dois componentes Registre cada instituição na Mensageria e no executor: 1. Envie `POST /v1/institutions` à Mensageria com o `institutionId` da instituição e `"enabled": true`. 2. Envie `POST /v1/institutions` ao executor com o mesmo `institutionId` e `"enabled": true`. O corpo do executor também traz a configuração do seu conector do Midaz e aceita os campos opcionais `branchFormat` e `accountFormat`. [Operando o Lerian SISBAJUD executor](https://docs.lerian.studio/pt/rails/sisbajud/sisbajud-executor-operations.md) descreve essa requisição. O executor se registra como dono da instituição, a partir da sua própria identidade M2M (`EXECUTOR_M2M_SUBJECT`). Nenhum campo de requisição define o dono, e um `PATCH` não o altera. O executor escreve no ledger somente para as instituições das quais é dono. ### Um cliente por instalação Cada instalação da Mensageria atende um cliente. Uma instalação pode ter muitas instituições. ## Ordens que precisam de atenção *** | Operação | O que retorna | | - | - | | `GET /v1/institutions/{institutionId}/awaiting-decision-orders` | As ordens que a geração de arquivos de resposta retém para uma decisão humana e que nenhum arquivo de resposta respondeu. | | `GET /v1/institutions/{institutionId}/failed-orders` | As ordens em `FAILED` e as ordens das quais o executor desistiu. Cada ordem mostra seu prazo de SLA. | | `GET /v1/institutions/{institutionId}/sla-status` | As ordens ativas por faixa de risco de SLA, com o detalhe de cada ordem. | | `GET /v1/institutions/{institutionId}/stats` | O número de ordens, por status e por tipo de ordem. Um período opcional limita a contagem. | `GET /v1/institutions/{institutionId}/orders` e `GET /v1/institutions/{institutionId}/files` listam as ordens e os arquivos. As operações de detalhe retornam uma ordem ou um arquivo. ## Janelas de resposta *** O SISBAJUD define o prazo da resposta de bloqueio pelo horário de envio de cada remessa. Uma remessa enviada até as 13:00 BRT vence às 19:00 BRT do mesmo dia. Uma remessa enviada depois das 13:00 BRT vence às 12:00 BRT do próximo dia útil. A Mensageria gera arquivos de resposta em intervalos, não em horários fixos. Defina `RETURN_FILE_GENERATION_SCAN_INTERVAL` e `INFORMATION_RETURN_FILE_GENERATION_SCAN_INTERVAL` para que cada ciclo termine dentro da janela do BACEN. Os dois valores são em segundos, e os dois têm padrão de uma hora. ### Correções de arquivos de resposta * `POST /v1/institutions/{institutionId}/return-file/generate` executa uma geração de arquivo de resposta agora. * `POST /v1/institutions/{institutionId}/return-file/{id}/reconsolidate` libera as ordens de um arquivo de resposta `FAILED`, para que uma geração posterior possa respondê-las. O arquivo continua `FAILED`. * `POST /v1/institutions/{institutionId}/return-file/{id}/resolve-transmission` aplica uma correção a um envio que nenhum caminho automático consegue concluir: `probe_now`, `attach_transfer`, `force_fail` ou `cancel_now`. O `reason` vai para a trilha de auditoria como foi escrito, então não coloque dados pessoais nem valores nele. `force_fail` só segue quando a última tentativa de envio tem pelo menos 5 minutos e o Lerian STA não tem uma transferência do arquivo que ainda possa chegar ao BACEN. Caso contrário, ele retorna `422`. Cada correção retorna `503` quando a Mensageria não consegue acessar o Lerian STA. ## Rotação de chaves *** A rotação de chaves é executada por instituição: * **Chave de criptografia de chaves (KEK).** `POST /v1/institutions/{institutionId}/security/kek:rotate` rotaciona a KEK da instituição. A resposta mostra a versão anterior e a nova versão da KEK. A rotação publica um evento `kek.rotated`. Com `KEK_REWRAP_BACKFILL_ENABLED` ativado, um job em segundo plano reenvolve as chaves de dados com a nova versão da KEK. Ele vem desativado por padrão. Com o AWS KMS no modo `provided`, a Mensageria não rotaciona a sua chave, e a operação retorna `422`. * **Keyset de tokenização.** `POST /v1/institutions/{institutionId}/security/keyset:rotate` adiciona uma nova chave primária ao keyset de tokenização da instituição. Uma instituição sem keyset ativo retorna `422`. Uma rotação de KEK pode retornar estes erros: * `SBJ-0007` / **409**: outra rotação da mesma chave para a mesma instituição está em andamento. Envie-a novamente depois que essa rotação terminar. * `SBJ-0012` / **409**: nada foi rotacionado, e a mesma requisição falha de novo. * `SBJ-0005` / **404**: a instituição não tem chave. * `SBJ-0008` / **503**: o gerenciador de chaves falhou antes da rotação. Envie-a novamente mais tarde. * `SBJ-0013` / **500**: o resultado da rotação não é conhecido. Não envie a rotação novamente. A Mensageria reconcilia o seu registro de chaves quando reinicia. * `SBJ-0014` / **500**: a chave foi rotacionada, mas uma etapa posterior falhou. Não envie a rotação novamente. Fale com o suporte da Lerian. ## Proteção de dados *** * **Criptografia por envelope.** A Mensageria criptografa campos sensíveis com AES-256-GCM sob uma chave de dados (DEK). Uma KEK envolve a chave de dados, no HashiCorp Vault Transit ou no AWS KMS. Os dados autenticados adicionais vinculam cada texto cifrado à sua instituição, tabela, registro e campo. * **Tokenização pesquisável.** Um blind index guarda um token do CPF/CNPJ e do número do processo. O token vem de uma chave HMAC-SHA256 da instituição. Ele permite busca por correspondência exata. * **Leituras mascaradas.** O detalhe da ordem e o detalhe do arquivo mascaram campos sensíveis, a menos que o chamador tenha `admin:read_pii`. A Mensageria registra na trilha de auditoria uma leitura de ordem em texto claro. * **Trilha de auditoria.** `GET /v1/institutions/{institutionId}/audit/verify` verifica um intervalo do log de auditoria por índice de folha, sem descriptografar nenhum payload. Ele informa adulterações e entradas excluídas. * **LGPD.** `POST /v1/institutions/{institutionId}/lgpd/requests` abre uma requisição de acesso ou portabilidade. `.../resolve` registra a decisão. `GET /v1/institutions/{institutionId}/lgpd/subject-data` exporta os registros de um titular de dados. ## Papéis *** A Mensageria declara quatro papéis de negócio: `operator`, `investigator`, `compliance-officer` e `admin`. Cada permissão vai para estes papéis: | Permissão | Papéis | | - | - | | `admin:read` | `operator`, `investigator`, `compliance-officer`, `admin` | | `admin:read_pii` | `investigator`, `compliance-officer`, `admin` | | `lgpd:request_read`, `lgpd:request_write` | `compliance-officer`, `admin` | | `non_compliance:justify` | `compliance-officer`, `admin` | | `institution_config:write` | `admin` | | `kek:rotate`, `keyset:rotate` | `admin` | | `systemplane:read`, `systemplane:write` | `admin` | | `return_file:generate`, `return_file:reconsolidate`, `return_file:resolve_transmission` | `admin` | | `sta_dlq:acknowledge` | `admin` | Um papel vale para todas as instituições da instalação. A Mensageria não tem concessão por instituição. ## Superfície HTTP *** As ordens chegam somente como arquivos, então nenhuma operação aceita uma ordem. A API principal escuta em `SERVER_ADDRESS`. O padrão é `:4031`. Ela atende estes grupos de operações: * Instituições: criar, ler e atualizar. * Ordens e arquivos: listas, detalhes, ordens que precisam de atenção, status de SLA e estatísticas. * Verificação de auditoria. * Requisições LGPD. * Justificativas de não conformidade. * Correções de arquivos de resposta. * Rotação de chaves. * Confirmação de dead letter do Lerian STA. Ela também atende `/health`, `/readyz`, `/version` e as rotas de administração do Systemplane em `/system`. A API de execução tem seu próprio listener. `PLUGIN_AUTH_ENABLED` precisa ser `true` ou `false`. A Mensageria aceita `false` somente quando `ENV_NAME` é `development`, `develop`, `dev`, `local` ou `test`, e `DEPLOYMENT_MODE` não é `saas`. Com `false`, as operações protegidas ainda exigem um bearer token. A Mensageria pula somente a verificação do Access Manager. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.