> ## 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.

# Opere o Lerian Consignado — Dataprev

> Orientação operacional para o Consignado: workers, idempotência, janelas do trilho, vazão, conciliação, credenciais e recuperação de falhas.

Opere o Lerian Consignado como um trilho isolado por tenant, não como um proxy sem estado. Comandos, leituras em segundo plano, o outbox e o estado de recuperação participam todos do contrato.

## Superfícies de comando e leitura

Use a API HTTP autenticada para comandos e consultas do cliente. A API separa comandos de leituras. Cada operação do cliente exige uma ação de autorização e roda no tenant de quem chama. Siga os requisitos de idempotência da operação. Novas tentativas após timeouts são normais e devem reutilizar a mesma identidade de negócio. Um comando de trilho parado em `outcome_unknown` (`503 OUTCOME_UNKNOWN`) é a exceção: nenhuma chave o reenvia, então leia `GET /v1/consignado/rail-commands`.

Uma operação montada não é prova de que um deployment específico conecta seu adapter Dataprev. Uma integração de trilho indisponível retorna `501 Not Implemented` para essa requisição, em vez de desaparecer da API. A operação de capacidades informa quais famílias de operação o seu deployment alcança. Registrar o código de instrumento da B3 de um contrato confirmado não chama o Dataprev, por isso não depende de nenhuma chave do trilho.

O stream de comandos do Lender carrega apenas o comando de exclusão. Ele não substitui a superfície HTTP completa. Veja [Eventos do Consignado](https://docs.lerian.studio/pt/reference/events/consignado.md).

## Workers agendados

O gateway executa o trabalho em segundo plano como loops agendados. Eles compartilham execução inicial retardada, escalonamento estável por réplica, isolamento de panic e encerramento gracioso. Todos os loops, exceto a via rápida de leilões, também fazem execuções sem sobreposição com jitter positivo.

| Worker | Finalidade | Cadência padrão |
| - | - | - |
| Poller de conciliação | Lê dados de escrituração e de repasse de todos os empregadores e avalia a liquidação esperada. | 1 hora |
| Poller de descoberta de leilões | Lista solicitações de empréstimo abertas e publica cada nova solicitação. Em um deploy multi-tenant, roda para todo tenant com credenciais do Dataprev em custódia. | 1 hora |
| Via rápida de leilões | Lista as solicitações de empréstimo abertas nos últimos 60 segundos e publica cada nova solicitação. Desabilitada por padrão. Apenas em deploys single-tenant. | 1 segundo |
| Poller de descoberta de portabilidade | Lista solicitações de portabilidade de entrada abertas e retransmite cada uma com seu próprio prazo de expiração. Em um deploy multi-tenant, roda para todo tenant com credenciais do Dataprev em custódia. | 1 hora |
| Poller de relatório de vínculo empregatício | Lê dados de rescisão de vínculo empregatício por tenant. Uma réplica por vez lê o feed de um tenant. | 1 hora |
| Recuperação de exclusão | Leva exclusões admitidas a um estado terminal. | 30 segundos |
| Recuperação de averbação | Converge averbações cujo desfecho nunca foi estabelecido junto ao registro do trilho. | 1 minuto |
| Recuperação de comandos do trilho | Converge comandos de refinanciamento, reversão, renegociação, exclusão por portabilidade, antecipação e alteração de termos cujo desfecho nunca foi estabelecido. | 1 minuto |
| Recondução de lances | Reenvia um lance cuja resposta do trilho se perdeu, com o número de proposta original, até a proposta ou a solicitação de empréstimo expirar. | 15 segundos |
| Limpeza de credenciais | Expira credenciais de tenant obsoletas sob um lease. | 30 segundos |
| Limpeza de payload de lances | Remove payloads de lances expirados e leilões resolvidos. Exclui o vínculo empregatício que uma consulta de margem armazenou, 30 dias após a última consulta. | 1 minuto |
| Testemunho de proposta | Confirma os termos da proposta aceita em relação ao lance durável do cliente. | 5 segundos |
| Relógio de saldo devedor | Avalia obrigações de parcela em atraso e de saldo de fim de mês, uma vez por dia por tenant e em cada execução do último dia útil do mês. | 1 hora |
| Reenvio de saldo devedor | Envia os informes de saldo devedor que uma virada de competência reteve. | 1 minuto |
| Prazo da documentação | Publica o sinal de prazo para averbações que aguardam a documentação e para o novo contrato de uma renegociação aceita por meio do gateway, contado a partir da aceitação. Desabilitado por padrão. | 1 minuto |
| Acompanhamento da documentação | Lê no Dataprev cada averbação que aguarda a documentação, uma vez por dia por contrato. Também lê o novo contrato de cada refinanciamento aceito por meio deste gateway durante 14 dias após o desfecho. Isso encontra uma reversão feita no portal do Dataprev. Uma vez por semana, também relê cada contrato encerrado por término de vínculo enquanto a dívida permanece. Desabilitado por padrão. | 5 minutos |
| Vencimento do certificado | Avisa antes de o certificado do Dataprev em custódia do tenant vencer. | 1 hora |
| Migração de contratos | Lê os contratos que o Dataprev moveu para o novo vínculo empregatício do trabalhador. Desabilitada por padrão. | 24 horas |

A via rápida de leilões, a limpeza de payload de lances e o testemunho de proposta leem sua cadência pelo Systemplane e entram em vigor no próximo intervalo. Os outros loops tomam sua cadência da configuração de ambiente e precisam de uma reinicialização para mudar.

A recuperação de averbação e a recuperação de comandos do trilho existem porque um comando de trilho pode deixar seu desfecho sem estabelecer: o processo morreu no meio da chamada, ou o trilho nunca respondeu. Elas convergem esse estado junto ao próprio registro do trilho, em vez de perdê-lo.

Para uma antecipação ou uma alteração de termos, a recuperação lê o contrato no Dataprev: uma mudança encontrada fecha o comando como aceito, e uma leitura que ainda não mostra mudança uma hora após o prazo da chamada o fecha como rejeitado. A recuperação espaça as releituras de um comando que não consegue fechar: 1 minuto, depois cada espera dobra, até uma vez por hora.

A recondução de lances reenvia um lance cuja resposta do trilho se perdeu, com o número de proposta original. Cada reenvio usa o orçamento de trilho do tenant. A recuperação de averbação, a recuperação de comandos de trilho e a recondução de lances vêm desabilitadas por padrão. Habilite os dois loops de recuperação em qualquer deploy que envie averbações ou comandos de trilho.

Quando o Dataprev recusa a documentação, a requisição responde `422` com os códigos do Dataprev em `upstream`, e o contrato volta para `attachment_pending`. Envie a documentação corrigida sob uma nova chave `X-Idempotency` ou exclua o contrato. Quando a chamada termina sem veredito, como um timeout, um `5xx` do Dataprev ou um recibo inutilizável, a requisição responde `503` ou `504`. O contrato também volta para `attachment_pending`: envie a mesma documentação de novo, sob a mesma chave ou uma nova. A leitura da averbação mostra em `last_documentation_close` a tentativa mais recente que o Dataprev não aceitou.

Um anexo de CCB interrompido no meio da chamada permanece em `attachment_invoking` até o `attachment_invocation_deadline_at` dele. Depois desse instante, a próxima documentação ou exclusão do contrato assume a chamada. Uma exclusão responde `409 EXCLUSION_DOCUMENTATION_UNDERWAY` apenas enquanto uma chamada de documentação está em andamento (`attachment_invoking` antes do `attachment_invocation_deadline_at`), para uma averbação ou um contrato renegociado. Envie a exclusão de novo quando `GET /v1/consignado/averbacao-operations` listar o contrato como `confirmed` ou `attachment_pending`, ou quando o prazo tiver passado. A exclusão descarta a documentação que o gateway nunca enviou (`last_documentation_close` com o código `excluded`).

Uma vez por mês, o Dataprev fecha para a virada de competência e recusa requisições. Quatro loops pausam para esse tenant quando um deles encontra essa recusa. São eles a descoberta de leilões, a via rápida de leilões, a descoberta de portabilidade e a recondução de lances. A pausa dura 5 minutos, depois 15, depois 30 a cada nova recusa. A recuperação de averbação, a recuperação de comandos do trilho, a conciliação e o poller de relatório de vínculo empregatício não aguardam essa pausa. Cada execução delas para de chamar o Dataprev na recusa e tenta de novo na próxima execução.

As requisições do cliente continuam chegando ao Dataprev e recebem a recusa dele. O relatório de jobs agendados mostra `paused_until` para um loop pausado. Na Lerian Cloud, o gateway publica `consignado.rail.paused` uma vez por virada e `consignado.rail.resumed` quando uma execução iniciada depois de a pausa abrir é respondida sem a recusa. O fato pode chegar um intervalo de sondagem depois de o Dataprev reabrir.

## Janelas do trilho

Os padrões e as restrições do trilho incluem:

* uma janela de validade de 24 horas para o leilão de empréstimo, que o Dataprev fornece e o gateway não configura
* um lookback de 72 horas para a solicitação de portabilidade
* 20 dias corridos desde a exclusão de origem para registrar uma portabilidade de entrada, quando a requisição informa a data da exclusão
* 7 dias úteis para reverter um refinanciamento
* 7 dias após uma averbação, ou após uma renegociação aceita por meio do gateway, para enviar sua documentação pelo anexo de CCB. Encontre os contratos que ainda aguardam com `GET /v1/consignado/averbacao-operations?status=attachment_pending` e leia `documentation_due_at` e `documentation_overdue` em cada um. Uma averbação cuja exclusão você pediu também continua em `attachment_pending`. A documentação dela recebe `409 AVERBACAO_EXCLUDED`, a menos que o Dataprev tenha rejeitado a exclusão. Antes de enviá-la, consulte `GET /v1/consignado/contracts/{numero_contrato}/exclusion` com a credencial do próprio tenant. Uma credencial de fundo ou de originador não pode consultá-lo.
* uma janela de 48 horas para a descoberta de leilões, com uma tolerância de clock skew de cinco minutos

Trate essas janelas como restrições do trilho, não como timeouts internos. Configure apenas as definições expostas pelo gateway quando o contrato do Dataprev para o ambiente de destino exigir um valor diferente. O gateway não permite alterar valores fixos que o Dataprev fornece, incluindo a janela de validade do leilão de empréstimo.

## Vazão e ritmo

O tráfego do Dataprev tem seu ritmo controlado por tenant. A API de vazão define a taxa do tenant, de 0 a 25 requisições por segundo, e nenhuma configuração eleva esse teto. Um tenant sem taxa armazenada opera a 3 requisições por segundo. Um valor armazenado de `0` pausa o tráfego do trilho para esse tenant.

## Segurança da conciliação

As leituras de escrituração e de repasse são independentes. Uma fonte com falha não deve suprimir a outra. Repasses esperados podem emitir três estados:

* `consignado.repasse.overdue`: a movimentação esperada está atrasada
* `consignado.repasse.resolved`: a movimentação esperada chegou depois do prazo. Ela pode chegar sem um `overdue` antes
* `consignado.repasse.unobserved`: o gateway não consegue, no momento, comprovar presença ou ausência

A conciliação lê todos os empregadores de cada tenant que atende. Um repasse fecha sua expectativa por contrato, competência e origem (parcela da folha ou desconto de verbas rescisórias), nunca por empregador. Um registro de repasse cujo empregador ou competência nenhuma expectativa consegue fornecer fica retido: o gateway não o publica. A lista de expectativas de repasse conta as expectativas abertas por empregador e mostra os registros retidos no bloco `held`. Leia primeiro o estado de atualização: uma lista vazia não prova nada, a menos que o estado seja `fresh`.

Um repasse ausente conta como atrasado apenas depois que o dia útil ANBIMA seguinte ao dia do prazo se encerrou. Quando uma execução lê as duas pontas, escrituração e repasse, sem falhas, ela também lê, pela consulta de contratos do Dataprev, os contratos ativos que a última folha encerrada deixou de fora. Essas leituras gastam o orçamento do Dataprev do tenant mesmo com o acompanhamento da documentação desabilitado. Uma leitura que encontra o contrato excluído, encerrado ou renegociado fora do gateway publica `consignado.exclusao.confirmed` com `evidence_source` `m005_external_exit`.

## Ações do back office

Seu back office tem duas ações no caminho do dinheiro. As duas exigem um papel do Access Manager que tenha a permissão correspondente. Os papéis `admin` e `operator` têm as duas.

| Ação | Permissão | Use quando |
| - | - | - |
| `POST /v1/consignado/rail-commands/{id}/close` | `consignado-rail` `rail-command-close:execute` | O gateway deixou parado um refinanciamento, uma renegociação, uma alteração de termos ou uma renegociação de legado em `outcome_unknown` e a recuperação não consegue decidi-lo. |
| `POST /v1/consignado/reconciliation/held-repasses/{id}/release` | `consignado-operations` `held-repasses-release:execute` | Você sabe o mês em que um registro de repasse retido é pago. |

O fechamento informa o que o portal do Dataprev mostra: `outcome` `accepted` ou `refused`, e `portal_evidence` de 1 a 500 caracteres, sem CPF nem nome do trabalhador. Um fechamento bem-sucedido responde `204`.

Um fechamento `refused` não lê nada no Dataprev. Um fechamento `accepted` de refinanciamento, renegociação ou renegociação de legado lê o novo contrato uma vez e responde `409 RAIL_COMMAND_CLOSE_CONTRADICTED` se a leitura o contradiz. Uma alteração de termos `accepted` não lê nada: o gateway move a obrigação do saldo devedor para os termos informados, sem verificação no Dataprev.

Uma suspensão, uma reativação ou uma inclusão ou exclusão de legado parada permanece em `outcome_unknown`: confirme o efeito no portal do Dataprev.

A liberação recebe `{"competencia":"yyyyMM"}`, publica o registro sob esse mês e responde `204`. Um mês que não serve responde `409`, e o registro continua retido.

## Credenciais e artefatos

Rotacione o certificado do tenant, o segredo OAuth, o código de solicitante e a URL do portal pela API de credenciais. Uma troca do código de solicitante chega a todas as réplicas na próxima chamada ao Dataprev. As variáveis de arquivo de certificado local são um fallback de desenvolvimento, não um substituto para a custódia do tenant em deployments gerenciados.

Quando o Dataprev recusa as credenciais de cliente OAuth do tenant, as operações que chegam ao Dataprev respondem `409 DATAPREV_CREDENTIAL_REJECTED`. A averbação e o anexo de CCB respondem esse código antes de reservar qualquer coisa. A exclusão não: ela responde com a operação parada em `outcome_unknown`. Um comando de trilho também responde esse código e fecha como `rejected`. Uma execução de garantia de FGTS responde e fecha como `refused`. Um lance continua aberto sob a sua chave: envie-o de novo sob a mesma chave.

Corrija as credenciais, e as leituras voltam a funcionar. Envie de novo uma averbação ou um anexo de CCB recusado sob a mesma chave. Envie de novo um comando de trilho ou uma execução de garantia de FGTS recusada sob uma nova chave `X-Idempotency`: a chave antiga repete a recusa. Para um tenant revogado, as operações do trilho e os envios parciais de credenciais respondem `409 DATAPREV_CREDENTIAL_REVOKED`. Um [envio completo](https://docs.lerian.studio/pt/reference/rails/consignado/put-dataprev-credentials.md) de um novo certificado e de um segredo de cliente OAuth gerado de novo no Dataprev encerra a revogação.

Registrar uma URL base de portal do trabalhador é opcional, para o tenant e para cada originador. Veja [Descubra leilões e envie propostas](https://docs.lerian.studio/pt/rails/consignado/how-consignado-works.md#3-discover-auctions-and-submit-proposals) para a ordem em que o gateway seleciona um portal.

Artefatos de CCB e do trilho usam o armazenamento de objetos configurado. Mantenha o bucket privado e entregue o conteúdo apenas pela operação autenticada de artefatos.

A averbação não carrega nenhum documento, e um corpo de 1 MiB ou mais recebe `413`. O anexo de CCB aceita uma CCB assinada e, depois de uma averbação com o bloco de contabilização, um pacote de biometria. O texto em base64 de cada um tem até 8 MiB, e um corpo inteiro de 18 MiB ou mais recebe `413`. Uma importação de contrato que carrega esses documentos segue os mesmos limites. Uma correção de contrato aceita um recurso corrigido cujo texto em base64 tem até 8 MiB.

## Comportamento em falha

O trilho falha de forma fechada quando falta identidade de tenant, com identificadores de comando malformados e com endpoints do Dataprev fora da política de deploy: HTTPS em um deploy gerenciado, HTTP loopback apenas nos demais. Um deploy gerenciado também falha de forma fechada quando faltam credenciais e com adapters sem suporte. Fatos de negócio são gravados pelo outbox e entregues pelo menos uma vez. Consumidores devem deduplicar pela origem e pelo ID do CloudEvent.

Uma queda do broker não tira o gateway da rotação: o outbox mantém os fatos duráveis, e o `/readyz` apenas reporta a verificação `streaming`. Alerte sobre essa verificação ou sobre o backlog do outbox.

Depois que o banco de dados de um tenant roda o schema da 4.2.0, não volte a imagem para a 4.0.0 ou anterior. Avance a versão.


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