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

# Como funciona o Lerian Consignado — Dataprev

> O fluxo completo do Consignado no Dataprev: configuração de tenant, margem do trabalhador, leilões, registro, gestão da carteira, portabilidade, garantias e conciliação.

O Lerian Consignado combina comandos HTTP síncronos com fatos assíncronos e leituras agendadas do Dataprev. A API HTTP admite trabalho e responde a consultas. O outbox publica fatos de negócio. Workers em segundo plano descobrem ou recuperam o estado que o Dataprev expõe como feeds, e não como callbacks.

## Configure um tenant

Antes que um tenant possa chamar o trilho, registre:

* um certificado de cliente ICP-Brasil A1 e a chave privada
* credenciais de cliente OAuth2
* o código de solicitante Dataprev de três dígitos do tenant
* opcionalmente, a URL base do portal do trabalhador oferecida como contato de formalização nas propostas de lance

O status da credencial retorna presença, fingerprint do certificado e metadados de expiração. Ele nunca retorna o certificado, a chave privada ou o segredo OAuth. Em um [deploy gerenciado](https://docs.lerian.studio/pt/rails/consignado/consignado-environment-variables.md), uma operação do trilho para um tenant sem o certificado, as credenciais OAuth ou o código de solicitante responde `DATAPREV_CREDENTIAL_REQUIRED`. Uma credencial revogada responde `DATAPREV_CREDENTIAL_REVOKED`. Apenas um [envio completo](https://docs.lerian.studio/pt/reference/rails/consignado/put-dataprev-credentials.md) do certificado e do cliente OAuth juntos encerra a revogação. Envie um novo certificado e um segredo de cliente OAuth recém-gerado no Dataprev. O id do cliente OAuth pode continuar o mesmo. `certPem` e `keyPem` aceitam no máximo 65.536 caracteres cada. Quando o Dataprev recusa as credenciais de cliente OAuth do tenant, uma leitura responde `DATAPREV_CREDENTIAL_REJECTED`, e uma escrita pode ficar parada. Corrija as credenciais na custódia e veja [Credenciais e artefatos](https://docs.lerian.studio/pt/rails/consignado/consignado-operations.md#credentials-and-artifacts) antes de enviar uma escrita de novo.

O gateway avisa você antes que o certificado Dataprev do tenant expire. Ele publica `consignado.certificate.expiring` no máximo duas vezes para cada certificado: `30_days` quando restam 30 dias ou menos, e `7_days` quando restam 7 dias ou menos. Um certificado expirado, uma custódia revogada e uma custódia sem certificado não geram aviso. Um certificado renovado avisa de novo. Apenas as subscriptions do próprio tenant o recebem.

Quando parceiros originam empréstimos em nome do tenant, registre cada um como originador. Um originador desativado não pode enviar lances, e o gateway mantém o registro dele. [Reative](https://docs.lerian.studio/pt/reference/rails/consignado/reactivate-consignado-originador.md) o originador para que ele volte a agir sob a mesma referência.

Quando o tenant cede créditos a fundos, registre cada fundo. Um fundo que o gateway conhece pelos fatos de fundo do Lender não precisa de registro aqui. Até o gateway conhecer o fundo, uma averbação que o nomeia responde `FUNDO_NOT_REGISTERED`. Um fundo desativado não aceita novo crédito até você [reativá-lo](https://docs.lerian.studio/pt/reference/rails/consignado/reactivate-consignado-fundo.md).

Uma averbação nomeia um fundo do Lender pelo id do Lender, assim como uma cessão do Lender. O CNPJ do fundo só importa para um fato de cessão do Lender sem id de fundo. O gateway então cede o contrato ao fundo registrado com esse CNPJ.

Um fundo ou um originador também pode chamar o gateway com uma credencial de parceiro do Access Manager restrita ao seu id de registro. Ele usa as rotas sob `/v1/consignado/fundos/{fundo_id}/` ou `/v1/consignado/originadores/{originador_id}/`, com esse id de registro no caminho. A chamada então roda como rodaria a credencial própria do fundo ou do originador. Um id de caminho que não está no registro de fundos ou de originadores do tenant responde `403`.

A credencial de parceiro de um originador também pode chamar as rotas sob `/v1/consignado/originador/`, que não nomeiam nenhum id de registro. `GET /v1/consignado/originador` retorna o originador em nome de quem a credencial age. Quando o escopo da credencial tem mais de um originador, essas rotas respondem `403` `AUT-1022`. O parceiro então usa as rotas `/v1/consignado/originadores/{originador_id}/` ou restringe seu escopo no Access Manager. Essas rotas exigem o Access Manager 3.14.0 ou posterior. Em uma versão anterior, elas respondem `503`.

## 2. Leia dados e margem do trabalhador

O endpoint de margem autentica o tenant, obtém o contexto de autorização do trabalhador no Dataprev e retorna a resposta do trilho sem transformá-la em uma decisão de underwriting. Quando o Dataprev os retorna, a resposta também traz os registros do trabalhador, do vínculo empregatício e do empregador. A API também expõe novos vínculos empregatícios, relatórios de rescisão, registros de FGTS autorizados e leituras de saldo de FGTS.

A resposta de margem também pode trazer `alerts`. Cada entrada é um evento eSocial que o Dataprev coletou para o vínculo empregatício: `typeCode` 1 é uma ausência, e `typeCode` 2 é uma rescisão, incluindo o aviso prévio. Não trate esse conjunto de tipos como fechado. Cada entrada traz suas datas de referência e o código de motivo eSocial como o Dataprev o enviou, então complete com zero à esquerda, até dois dígitos, um código que começa com 0. `eventId` está presente quando o Dataprev o envia. O Dataprev coleta os alertas diariamente, então eles não são em tempo real. Um originador vê os alertas apenas nesta leitura. O tenant também recebe cada um como `consignado.afastamento.reported`.

O termo de autorização modelo do Dataprev não lista os dados cadastrais da resposta de margem: o nome da mãe do trabalhador, a nacionalidade, o CBO, o nome do empregador, o início de atividade do empregador e o CNAE. O seu próprio instrumento de consentimento deve cobrir esses campos. O gateway não impõe isso.

O gateway guarda a categoria eSocial e a data de admissão da leitura de margem mais recente de cada vínculo empregatício. Ele as apaga 30 dias após a última leitura. Quando o `dados_cadastrais` da averbação não declara esses campos, `consignado.contract.registered` os traz dessa leitura de margem.

## Descubra leilões e envie propostas

Um loop de descoberta agendado lista as solicitações de empréstimo abertas e publica cada nova solicitação. Uma via rápida opcional repete essa listagem a cada segundo. Ela roda apenas em um deploy single-tenant. Em um deploy multi-tenant, a descoberta roda para todo tenant que tem custódia Dataprev. O cliente pode então enviar um lance pela API HTTP autenticada. O gateway retém o payload durável do lance necessário para comprovar o que o cliente enviou e, depois, publica o testemunho da proposta aceita.

Um lance pode nomear um originador. O gateway recusa um lance para um originador desconhecido ou desativado. Um originador que se autentica com a própria credencial envia lances sob a própria referência.

Quando a chamada ao Dataprev falha antes de o Dataprev recebê-la, o lance fica sem desfecho e responde `503` `DATAPREV_UNAVAILABLE`. Apenas um código que o Dataprev publicou recusa uma primeira tentativa. Reenvie sob a mesma chave `X-Idempotency`: ela responde `409` enquanto a primeira tentativa roda e depois envia as mesmas propostas. Após o prazo da tentativa anterior, reenvios de um lance com resultado desconhecido sob a mesma chave esperam intervalos progressivos: 30 segundos, que dobram até 30 minutos; durante essa espera, respondem `503` `OUTCOME_UNKNOWN` sem nova chamada ao Dataprev. Quando o desfecho de um lance nunca se resolve, a aceitação pelo Dataprev de uma averbação para um dos números de proposta dele o resolve como `accepted`. Um reenvio sob a mesma chave então repete `200` com uma lista `propostas` vazia. Enquanto o resultado for desconhecido, nunca reenvie o lance sob uma nova chave. Corrija uma recusa local sob uma nova chave. No livro de lances, `fundo_ref` é o fundo a que o crédito foi cedido, e fica nulo até que uma cessão seja registrada.

Toda proposta deve chegar ao trabalhador por pelo menos um contato. O gateway adiciona um portal de formalização como contato quando encontra um: primeiro no lance, depois no originador nomeado, depois no tenant. Quando nenhum dos três tem portal, cada proposta deve levar um contato do cliente. Caso contrário, o gateway recusa o lance antes de chamar o Dataprev.

Os leilões de portabilidade usam uma operação de resposta separada e uma janela de requisição limitada no Dataprev.

## 4. Registre e financie o contrato

O fluxo de registro:

1. envia a averbação ao Dataprev
2. envia a documentação do contrato ao Dataprev
3. expõe o status de registro e os documentos do trilho
4. registra a confirmação de desembolso do cliente
5. publica fatos imutáveis de registro contábil e de pagamento pelo outbox

A [averbação](https://docs.lerian.studio/pt/reference/rails/consignado/averbar-consignado-contract.md) executa apenas o Manual 003 do Dataprev e não leva nenhum documento nem instante de assinatura. Ela exige `nome_trabalhador`, o nome completo do trabalhador. Você cria o número do contrato: de 2 a 15 letras ou dígitos, sem espaços, acentos ou símbolos. A mesma regra vale para o novo contrato de um refinanciamento, de uma renegociação ou de uma portabilidade de entrada. A averbação responde 422 `MATRICULA_DIFFERS_FROM_PROPOSAL` antes de chamar o Dataprev quando `numero_proposta` nomeia uma proposta que registrou uma `matricula` e a averbação traz outra. Ela responde 422 antes de chamar o Dataprev quando `tem_garantias` e os valores de garantia do FGTS não concordam: `true` sem nenhum valor, ou `false` com um valor.

Com o bloco de contabilização, o gateway verifica a contabilização antes de chamar o Dataprev e responde 422 quando o Lender não consegue contabilizá-la, e `liberated_amount` deve ser igual a `principal_amount` menos `iof_amount` e `origination_fee_amount`. Quando o tenant tem versões do Lender, o gateway também recusa uma `loan_product_version` que ele não recebeu do Lender e uma versão que não admite pessoa física. O detalhe do problema nomeia a regra, e a [lista de erros](https://docs.lerian.studio/pt/reference/rails/consignado/consignado-error-list.md) traz cada código. Quando o Dataprev aceita a averbação, a operação responde `attachment_pending` e o gateway publica `consignado.averbacao.accepted`. O Dataprev então detém o mandato de desconto em folha, e o contrato aguarda a documentação.

[Envie a documentação](https://docs.lerian.studio/pt/reference/rails/consignado/attach-consignado-ccb.md) em uma segunda requisição, sob a própria chave `X-Idempotency`. Ela executa apenas o Manual 004. Ela leva a CCB assinada, a evidência de assinatura e `data_hora_assinatura`, o instante em que o trabalhador assinou a CCB. O trabalhador pode assinar dias depois da averbação.

Quando a averbação trouxe o bloco de contabilização, a documentação leva também o pacote de evidências e `signature_evidence_ref`. Sem o bloco, os dois são recusados. Com o bloco, um instante de assinatura posterior a `formalization_deadline` responde `FORMALIZATION_DEADLINE_EXCEEDED`. Um instante mais de 5 minutos à frente do relógio do gateway responde `DECLARED_DATES_OUT_OF_ORDER`.

A documentação também completa o novo contrato de uma renegociação que o Dataprev aceitou por meio deste gateway. Envie apenas a CCB assinada do contrato substituído. A resposta é `confirmed`, e o gateway não publica nenhum fato. Esse contrato recebe a mesma janela de 7 dias de uma averbação, contada a partir do instante em que o Dataprev aceitou a renegociação. Ele aparece em `GET /v1/consignado/averbacao-operations` com os mesmos campos, com `booking_profile` `rail_only`. A leitura de averbação dele responde 404.

Sem uma averbação aceita ou uma renegociação desse tipo, a documentação responde `AVERBACAO_NOT_ACCEPTED` e nada chega ao Dataprev. A recusa é definitiva apenas quando a averbação lê `rejected`, porque a recuperação de averbações (`DATAPREV_AVERBACAO_RECOVERY_ENABLED`, desligada por padrão) ainda pode aceitar uma averbação que lê `averbacao_unknown`. Sem ela, contate a Lerian com o número do contrato.

Quando o Dataprev recusa uma averbação, o número do contrato fica livre de novo. Envie a averbação corrigida sob um novo `contract_id` e uma nova chave `X-Idempotency`. O `contract_id` recusado continua consumido e responde `AVERBACAO_CLAIM_CONFLICT`. Uma averbação em andamento, aceita ou `averbacao_unknown` ainda detém o número.

Um contrato aceita uma única documentação aceita. A mesma documentação sob uma nova chave repete a primeira resposta. Uma documentação diferente responde `AVERBACAO_DOCUMENTATION_CONFLICT` enquanto a primeira está aceita ou a caminho do Dataprev. Ela também responde esse código para um contrato lido de volta no registro cuja proposta de leilão já está resolvida. Quando o Dataprev aceita a documentação, a operação responde `confirmed` e o gateway publica `consignado.averbacao.confirmed`. A confirmação entrega ao Lender, para contabilização e desembolso, o contrato enviado com o bloco de contabilização.

Quando o Dataprev recusa a documentação, a requisição responde 422 com os códigos do Dataprev em `upstream`, e o contrato volta a aguardar a documentação. Envie a documentação corrigida sob uma nova chave ou exclua o contrato. Quando a chamada termina sem veredito, a requisição responde 503 ou 504, e o contrato também volta a aguardar. Envie a mesma documentação de novo.

O Manual 004 dá à instituição financeira 7 dias após a averbação para enviar a documentação. O gateway não impõe esse prazo. A leitura da averbação mostra `documentation_due_at`, 7 dias corridos após a averbação, e `documentation_overdue` enquanto a documentação está atrasada. Dois loops opcionais ajudam você a acompanhá-lo, e os dois vêm desabilitados por padrão. O sinal de prazo publica `consignado.averbacao.documentation_deadline`. O acompanhamento da documentação lê no Dataprev cada contrato que aguarda, uma vez por dia, e mostra o que encontra em `dataprev_follow_up`. Ele também lê, uma vez por semana, um contrato que o término de vínculo encerrou enquanto a dívida permanece. Uma leitura que encontra o contrato de volta no registro, depois de uma migração do Dataprev, desfaz o encerramento, e a documentação volta a ser aceita.

Um lender ou ledger downstream decide o que esses fatos significam para seus próprios livros. O gateway não lança diretamente no ledger.

Após a confirmação, [informe o código de instrumento B3](https://docs.lerian.studio/pt/reference/rails/consignado/inform-the-b3-instrument-code-of-an-averbado-contract.md) que a B3 retornou ao aceitar o registro da CCB. Apenas a credencial do próprio tenant pode informá-lo ou lê-lo, não uma credencial de fundo ou de originador. O gateway grava o código uma única vez e publica `consignado.registro_b3.registered`. Reenviar o mesmo código e a mesma data responde o registro original. Um código ou uma data diferente responde `REGISTRO_B3_JA_INFORMADO`, e a API não oferece correção. O gateway não se comunica com a B3 e não confere o código com a CCB.

Importe um contrato que já está registrado no trilho fora deste gateway. A importação lê o contrato no Dataprev e não movimenta dinheiro. Apenas um contrato ativo ou suspenso pode ser importado. Uma contabilização é aceita apenas para um contrato que o Dataprev lê como averbação de banco (`origemAverbacao` 0), tombamento compulsório (7) ou sem `origemAverbacao`. Para qualquer outra origem, a importação com contabilização responde 422 e não grava nada. Importe esse contrato sem a contabilização. Sem os dados de contabilização, um contrato que já tem uma obrigação de saldo devedor aqui responde `CONTRACT_ALREADY_REGISTERED`.

Uma importação também pode levar os dados de contabilização, em dois objetos enviados juntos. O objeto `booking` é o corpo da averbação com o bloco de contabilização completo e um `numero_proposta` vazio. Ele também leva a documentação: a CCB assinada, o pacote de evidências, `signature_evidence_ref` e a evidência de assinatura.

O objeto `registration` traz o que o Dataprev devolveu na averbação original. Ele leva `averbado_at`, o `response_code` da averbação e o `hash_operacao` do Manual 004 da documentação. O `averbado_at` deve ficar a até um minuto do instante de inclusão na leitura do Dataprev. Enviar apenas um dos dois é recusado.

O gateway confere a contabilização e o `averbado_at` com a leitura do Dataprev, guarda os documentos sob sua custódia e publica `consignado.contract.registered`. O Lender então contabiliza o contrato como contabiliza um registrado por averbação aqui. A importação não envia averbação nem CCB ao Dataprev.

Com os dados de contabilização, uma obrigação que o contrato já tem não é um conflito. O gateway a mantém intacta, e `saldo_devedor_dispatch_scheduled` responde `false`. Nesse modo, `CONTRACT_ALREADY_REGISTERED` significa que o contrato foi registrado por este gateway ou foi importado antes com outros dados de contabilização. A importação roda as mesmas verificações de versão de produto do Lender que a averbação.

Registre uma correção contra o contrato registrado quando algo que o cliente já afirmou se revela incorreto. Exemplos são o arquivo CCB errado e uma confirmação de desembolso com a evidência errada. Uma correção não cruza nenhuma fronteira governamental: os próprios campos de retificação do trilho foram desativados, então o cliente permanece como a única autoridade. O gateway assume a custódia dos bytes corrigidos, publica o fato que os nomeia e os serve de volta mediante autenticação. As correções formam uma cadeia: cada uma substitui o evento anterior a ela. Apenas a credencial do próprio tenant registra uma correção. Um fundo lê as correções de um contrato cedido a ele e de um novo contrato que herda esse fundo.

## Administre o contrato

A API cobre o ciclo de vida do trilho após o registro: suspensão, reativação, alterações de termos, antecipação e reversão de parcela, e exclusão. Ela também cobre refinanciamento e reversão, renegociação, registro de portabilidade e operações de contrato legado. O desfecho de uma renegociação publica `consignado.renegociacao.efetivada` ou `consignado.renegociacao.recusada`.

A portabilidade funciona nos dois sentidos. Como instituição proponente, registre a portabilidade de entrada. Como instituição de origem, exclua o contrato do qual o trabalhador migrou. O gateway aceita isso apenas para um contrato que ele mantém para você: registrado por meio dele, ou importado. Ele recusa qualquer outro caso antes de chamar o trilho.

A averbação de portabilidade de entrada exige que a exclusão na origem rode primeiro. O Dataprev a recusa com a regra `PT` quando a exclusão não rodou, e com a regra `PW` quando a portabilidade já está encerrada. Qualquer uma das recusas libera o número do contrato. O gateway verifica a janela de 20 dias corridos apenas quando você envia `dataExclusaoOrigem`. Sem ele, o Dataprev avalia a ordem e a janela.

O gateway reivindica o número do contrato antes de chamar o Dataprev. Um número que o tenant já detém responde `409` `CONTRACT_ALREADY_REGISTERED`. Um reenvio sob uma nova chave nunca envia duas vezes. Enquanto a primeira chamada ainda pode estar rodando, um reenvio responde `409` `CLT-0007`. Depois disso, responde `503` `OUTCOME_UNKNOWN` até o gateway ler o contrato no Dataprev. Com a recuperação de averbações ligada, essa leitura registra uma aceitação ou libera o número. Nesta rota, reenviar sob qualquer chave durante essa espera é seguro.

Quando o Dataprev aceita a compra, o contrato aguarda a documentação: a leitura de averbação dele mostra `attachment_pending`, e a obrigação de saldo devedor dele começa. O gateway não publica `consignado.averbacao.accepted` para uma compra. [Envie a documentação](https://docs.lerian.studio/pt/reference/rails/consignado/attach-consignado-ccb.md) como para uma averbação.

A averbação de portabilidade aceita um objeto `booking` opcional. O gateway nunca o envia ao Dataprev. Envie todos os membros dele ou omita o objeto: `iof_amount`, `expected_disbursement_date`, `loan_product_version`, `formalization_deadline`, `margin_snapshot` e `origins[]`. Essa contabilização exige Lender 4.0.0 ou posterior; atualize o Lender antes do gateway 4.2.0. Cada entrada de `origins[]` nomeia um contrato de origem que a compra quita:

* `origin_institution`, o código COMPE de 3 dígitos do banco de origem, com zeros à esquerda
* `external_operation_ref`, de 2 a 15 letras ou dígitos
* `transferred_principal`, a parte positiva de `valorPago` que quita esse contrato

As entradas devem somar `valorPago` e nomear cada contrato uma única vez. O valor liberado contabilizado é `valorEmprestimo` menos `iof_amount`. O gateway responde 422 com os códigos de contabilização antes de chamar o Dataprev quando `iof_amount` não é menor que `valorEmprestimo`, quando `valorPago` é zero ou maior que o valor liberado, quando as origens não somam ou quando o Lender recusaria a contabilização.

Depois que o Dataprev aceita a documentação, o gateway publica `consignado.contract.registered` com `portability_in`. Ele espera até que o registro de status de portabilidade do Dataprev mostre exatamente os contratos de origem contabilizados como excluídos, por no máximo 20 dias corridos a partir da documentação confirmada. Um contrato excluído que a contabilização não nomeia, ou o fim dos 20 dias, deixa o contrato parado para a operação da Lerian, sem fato. Sem `booking`, o contrato fica apenas no trilho e o Lender não recebe nenhum fato.

Reverter um refinanciamento funciona da mesma forma. Você apenas pode reverter um refinanciamento por este gateway se o gateway o registrou. A janela de 7 dias úteis é avaliada em relação ao próprio registro do gateway sobre quando esse refinanciamento foi efetivado.

O pedido de refinanciamento aceita um objeto `booking` opcional que o Lender usa para contabilizar o novo contrato. O gateway nunca o envia ao Dataprev. Envie `expected_disbursement_date`, `loan_product_version`, `formalization_deadline` e `margin_snapshot`, com um `origination_fee_amount` opcional, ou omita o objeto. Com ele, `competenciaInicioDesconto` é obrigatória. `valorEmprestimo` menos `valorIOF` e a tarifa deve ser igual a `valorPago` mais `valorTroco`, ou o pedido responde 422 `DECLARED_TERMS_INCONSISTENT`. Os códigos de contabilização se aplicam, exceto `FORMALIZATION_DEADLINE_EXCEEDED`, porque o refinanciamento não tem etapa de documentação. Sem o bloco, o novo contrato existe apenas no trilho e o Lender não contabiliza nada.

O gateway publica o desfecho de um refinanciamento que ele enviou. `consignado.refinanciamento.efetivado` nomeia os contratos quitados e os novos termos, e traz `novo_contrato` quando você enviou a contabilização. `consignado.refinanciamento.revertido` informa uma reversão que excluiu o novo contrato, incluindo uma feita no portal do Dataprev que a leitura de acompanhamento de 14 dias vê. `consignado.refinanciamento.recusado` informa uma recusa e nomeia os contratos que continuam ativos. Um refinanciamento feito fora do gateway não publica nenhum desses fatos.

Com a contabilização, o gateway publica `novo_contrato` apenas em termos que o Dataprev confirmou. Quando o Dataprev responde com uma `competenciaInicioDesconto` diferente da contabilizada, o pedido responde `503` `OUTCOME_UNKNOWN`. Tente de novo apenas sob a mesma chave `X-Idempotency`. O comando então fica parado em `outcome_unknown`. A recuperação publica o fato apenas quando a leitura dela do novo contrato mostra os termos contabilizados. Se o Dataprev aceitou o refinanciamento com termos diferentes, contate a operação Lerian.

O gateway informa o saldo devedor ao Dataprev para cada contrato que mantém no registro. São os contratos que ele registra por averbação, refinanciamento, renegociação ou portabilidade de entrada, e os contratos que importa. Para um contrato que ele registra, a obrigação começa quando o Dataprev aceita essa operação. Para uma averbação, isso acontece antes da documentação.

O saldo informado é o valor presente das parcelas não pagas ainda por vencer, na data de Brasília do informe. O gateway desconta cada parcela pela taxa mensal do contrato e considera o pagamento na data de vencimento. Ele envia um informe quando a dívida muda, quando uma parcela vence sem pagamento e no último dia útil de um mês sem informe.

Quando o Dataprev aceita uma alteração de termos, o saldo informado segue os novos termos. As parcelas vencidas antes da competência inicial da alteração continuam devidas pelo valor que tinham. A partir dessa competência, valem a nova quantidade e o novo valor, e o gateway enfileira um novo informe na hora. As duas leituras de saldo devedor passam a trazer `valores_parcela`, que mapeia cada competência inicial (`yyyyMM`) para o valor da parcela a partir desse mês. O campo fica ausente até que uma alteração de termos seja aceita. `numero_parcelas` conta as parcelas a partir de `competencia_inicio_desconto` sob os termos alterados.

Os informes param quando o contrato sai do registro. Um contrato sai do registro quando:

* o Dataprev confirma a exclusão dele ou aceita a exclusão por portabilidade do lado de origem
* um refinanciamento ou uma renegociação aceita o substitui, e nenhuma reversão desfaz isso
* uma reversão desfaz o refinanciamento que o criou. Com o acompanhamento da documentação ligado, isso inclui uma reversão no portal do Dataprev nos 14 dias após o refinanciamento.
* uma leitura do contrato no Dataprev, pelo acompanhamento da documentação ou pela leitura de ausência na folha, o mostra excluído ou encerrado (situação 2, 3 ou 16)
* uma exclusão se encerra como rejeitada porque a leitura de status do Dataprev achou o contrato já fora. Um refinanciamento ou uma renegociação que o gateway registrou para o contrato prevalece sobre essa leitura.

Um contrato que o término de vínculo encerrou (situação 15) não sai do registro. A dívida permanece, então o gateway continua informando o saldo até a quitação ou a renegociação. A documentação dele continua recusada, e os sinais de prazo da documentação param.

Um contrato que um refinanciamento aceito ou uma exclusão por portabilidade do lado de origem quita recebe um informe final de 0,00 antes de os informes pararem. O mesmo vale para um contrato que uma leitura do Dataprev mostra como saído por portabilidade ou refinanciamento.

A exclusão é uma operação recuperável. O comando autenticado inicial registra a intenção, e um loop de recuperação agendado leva o trabalho admitido a um estado terminal no trilho. Repetir o mesmo comando idempotente não cria uma segunda exclusão. Você também pode excluir um contrato sem averbação neste gateway enquanto o gateway informa o saldo devedor dele. Exemplos são um contrato importado e o novo contrato de um refinanciamento. A recuperação de comandos do trilho converge um comando cujo desfecho ninguém estabeleceu junto ao registro do trilho, em vez de perdê-lo. Ela cobre refinanciamento, reversão, renegociação, exclusão por portabilidade do lado de origem, antecipação de parcela e a remoção dela, e alterações de termos. Para uma antecipação ou uma alteração de termos, uma leitura que começa uma hora ou mais após o prazo da chamada e ainda não mostra mudança fecha o comando como rejeitado, com `GW-M005-NAO-EXECUTADO`. Reenvie-o sob uma nova chave de idempotência. Suspensão, reativação e operações legadas não têm leitura que decida.

O seu back office pode fechar um refinanciamento, uma renegociação, uma alteração de termos ou uma renegociação legada em `outcome_unknown`. Consulte [Ações de back office](https://docs.lerian.studio/pt/rails/consignado/consignado-operations.md) para fazer o fechamento.

Uma exclusão também pode cancelar uma averbação que aguarda a documentação. A partir do pedido de exclusão, a documentação desse contrato responde `AVERBACAO_EXCLUDED`, a menos que o Dataprev rejeite a exclusão. A documentação de um contrato que saiu do registro também responde `AVERBACAO_EXCLUDED`. A documentação que o gateway recebeu mas nunca enviou ao Dataprev não bloqueia a exclusão. A exclusão a descarta, e `last_documentation_close` mostra `excluded`. Enquanto uma chamada de documentação ao Dataprev está em andamento, a exclusão responde `EXCLUSION_DOCUMENTATION_UNDERWAY`. Isso inclui o novo contrato de uma renegociação. Envie a exclusão de novo quando `GET /v1/consignado/averbacao-operations` listar o contrato como `confirmed` ou `attachment_pending`, ou quando o prazo da chamada tiver passado.

Uma exclusão de um contrato que uma renegociação substituiu vai ao Dataprev sob o número que o substituiu, por sucessivas renegociações até a última. Ela nunca segue o contrato substituído de um refinanciamento. O `numeroContrato` da resposta é o número que o Dataprev foi solicitado a excluir, e `GET .../exclusion` também encontra a exclusão sob o número que você informou. Os fatos de exclusão respondem sob o número que você informou e nomeiam o número excluído em `numero_contrato_excluido` quando ele difere.

Uma exclusão e uma renegociação se bloqueiam. Enquanto uma renegociação não tem resposta do Dataprev, a exclusão responde `409` `EXCLUSION_RENEGOTIATION_UNDERWAY`. Envie-a de novo quando `GET /v1/consignado/rail-commands` mostrar a renegociação aceita ou rejeitada. Uma renegociação responde `409` `RENEGOTIATION_EXCLUSION_UNDERWAY` enquanto existe uma exclusão do contrato encerrado que o Dataprev não rejeitou.

O gateway recusa uma exclusão antes de chamar o Dataprev, com `404` `CLT-0005`, quando mantém o contrato mas o contrato já saiu do registro: um refinanciamento o substituiu sem reversão, uma exclusão por portabilidade do lado de origem dele foi aceita, ou uma leitura do Dataprev o viu excluído ou encerrado. Um contrato encerrado por término de vínculo (situação 15) ainda pode ser excluído.

Quando uma leitura do Dataprev encontra um contrato que o gateway mantém já fora do registro, sem nenhuma exclusão pelo gateway por trás, o gateway publica `consignado.exclusao.confirmed` uma vez, com `evidence_source` `m005_external_exit` e um `reason_code` que começa com `contract_left_registry`. Isso cobre um contrato excluído no portal ou por outra origem, encerrado ou renegociado fora do gateway. O acompanhamento da documentação (`DATAPREV_DOCUMENTATION_FOLLOWUP_ENABLED`, desabilitado por padrão) e a leitura de ausência na folha abaixo fazem essas leituras. O gateway não publica nada para um contrato na situação 15, para uma reversão de refinanciamento, que `consignado.refinanciamento.revertido` informa, nem para uma saída que o próprio gateway fez. Uma saída por refinanciamento só publica se uma segunda leitura 14 dias depois ainda achar o contrato fora. Uma saída por renegociação espera enquanto um refinanciamento ou uma renegociação desse contrato pelo gateway não tem resposta.

Quando o Dataprev move um contrato para o novo vínculo empregatício do trabalhador por conta própria (Manual 018), o gateway publica `consignado.migracao.efetivada`, uma vez para cada contrato e novo vínculo. Ele cobre todo contrato sob o código de solicitante do tenant, inclusive contratos não registrados pelo gateway. Vem desligado por padrão: defina `DATAPREV_MIGRACAO_ENABLED=true`, que exige `DATAPREV_ENABLED=true`. Uma subscription que lista `event_types` explícitos não o recebe: crie uma subscription que liste `consignado_migracao.efetivada`.

## 6. Concilie a folha de pagamento e o repasse

O worker de conciliação lê duas fontes independentes do Dataprev:

* **registros de escrituração**, indexados pela competência da folha de pagamento e pelo contexto do contrato
* **registros de repasse da CEF**, que representam a movimentação de liquidação

O gateway emite um fato de conciliação por registro de repasse, exceto um retido, e um por empregador, contrato e mês de escrituração, e acompanha os repasses esperados. Um repasse pode ficar atrasado, resolver-se depois ou tornar-se não observável quando o gateway não consegue estabelecer uma visão atual do trilho. Os consumidores não devem tratar o silêncio como liquidação.

Um repasse ausente gera `consignado.repasse.overdue` apenas depois que o dia do prazo e mais um dia útil da ANBIMA se encerraram. O prazo é o fechamento, no horário de Brasília, do dia que cai dois dias úteis da ANBIMA depois do vencimento da guia do FGTS. A guia vence no dia 20 do mês seguinte à competência. Um repasse que chega dentro do dia extra produz `consignado.repasse.resolved` sem `overdue` antes dele.

No mês em que um trabalhador é desligado, o Dataprev registra dois descontos para um contrato: a parcela da folha e o desconto sobre as verbas rescisórias. O gateway espera dois repasses e alarma cada um. Um repasse fecha apenas a expectativa da própria origem. Os fatos da expectativa de verbas rescisórias trazem `verbas_rescisorias: true`. Cada item do quadro de repasses esperados traz `verbas_rescisorias`. O gateway publica um fato de conciliação para os dois registros de escrituração desse empregador, contrato e mês, a partir do registro que lê primeiro, então `valor_parcela` e `tipo_evento_esocial` dele podem pertencer a qualquer um dos registros.

Cada leitura cobre todos os empregadores do tenant. Em um deploy multi-tenant, o worker concilia todo tenant ativo que tem uma credencial Dataprev. O gateway casa um repasse com o repasse esperado pelo contrato e pela competência da folha de pagamento, não pelo empregador. Um registro de repasse que não nomeia o empregador ou a competência, e que nenhum repasse esperado consegue suprir, fica retido. O gateway não publica fato para ele até que um repasse esperado nomeie os dois. Um registro de verbas rescisórias que não nomeia a competência fecha a expectativa de verbas rescisórias do contrato e é publicado sob esse mês. Um registro com encargos de atraso e sem competência continua retido.

O seu back office pode listar e liberar repasses retidos. Consulte [Ações de back office](https://docs.lerian.studio/pt/rails/consignado/consignado-operations.md).

Com `DATAPREV_RECONCILIATION_ENABLED=true`, uma execução que lê as duas fontes sem falha também lê no Dataprev, pela consulta de contratos (Manual 005), os contratos vivos que a folha da última competência encerrada deixou de fora. Ela lê no máximo 50 contratos por tenant em uma execução. Essas leituras rodam mesmo com o acompanhamento da documentação desligado e gastam o orçamento ritmado do tenant no Dataprev. Uma leitura que encontra o contrato excluído ou encerrado para os informes de saldo devedor dele e publica o fato de exclusão descrito na seção 5.

## 7. Opere portfólios e garantias

Famílias adicionais de API cobrem calendários operacionais, rescisões de vínculo empregatício, execução de garantia de FGTS, fundos, originadores, créditos cedidos, vazão por tenant e subscriptions de entrega de eventos.

O Lender cede um contrato a um fundo. Quando o Lender publica que um fundo aceitou um contrato, o gateway registra a cessão e publica `consignado.cessao.registered`. O contrato é um que este gateway confirmou por averbação ou importou com a contabilização. Ele também pode ser o novo contrato de um refinanciamento ou de uma renegociação que este gateway registrou como aceito. A leitura de créditos cedidos do fundo passa então a listar o contrato, também quando ele não veio de um leilão.

O gateway não registra cessão para um contrato que saiu do registro: uma exclusão confirmada, uma exclusão por portabilidade aceita, um original que um refinanciamento ou uma renegociação aceita substituiu sem reversão, ou um contrato que uma leitura do Dataprev viu excluído ou encerrado (situação 2, 3 ou 16). Um contrato que o término de vínculo encerrou (situação 15) ainda pode ser cedido.

> [!NOTE]
>
> Use a página da operação na referência da API para conhecer os cabeçalhos obrigatórios exatos, as regras de idempotência, os intervalos de validação e os esquemas de resposta.


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