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

# Eventos do Consignado

> Contrato de CloudEvents emitido pelo Lerian Consignado: headers de roteamento, gatilhos, assuntos, campos de payload e semântica de entrega.

O Lerian Consignado publica seus fatos de negócio como CloudEvents 1.0. Os fatos emitidos entram no outbox transacional antes da publicação.

> [!NOTE]
>
> Os contratos de payload abaixo descrevem o objeto `data` do CloudEvent. Uma propriedade marcada com `?` pode estar ausente. `null` é válido apenas onde um contrato de payload o escreve explicitamente.

## Contrato do stream de aplicação

| Elemento do wire | Valor |
| - | - |
| Tópico do fato | `lerian.streaming.consignado-gw` |
| `ce-source` | `consignado-gw` |
| `ce-type` | `studio.lerian.consignado-gw.<resource>.<event>` |
| `ce-id` | UUIDv7 |
| Chave de despacho | `<resource>.<event>` a partir de `ce-resourcetype` e `ce-eventtype` |
| `ce-schemaversion` | `1.0.0`, e `1.1.0` em `consignado.exclusao.rejected` |
| Chave de partição | Identificador do tenant |
| Entrega | Pelo menos uma vez, por meio do outbox transacional |

O tópico identifica a aplicação produtora, não um evento único. Faça o roteamento por `ce-source`, `ce-resourcetype` e `ce-eventtype`. Use `ce-type` como o composto qualificado por source desses três. Nunca infira um evento a partir do nome do tópico.

## Catálogo de eventos emitidos

| Chave de definição | `ce-type` | Recurso / evento | `ce-subject` | Gatilho de emissão |
| - | - | - | - | - |
| `consignado.solicitacao.received` | `studio.lerian.consignado-gw.consignado_solicitacao.received` | `consignado_solicitacao` / `received` | `id_solicitacao` | O gateway descobre uma solicitação de empréstimo aberta no Dataprev. |
| `consignado.portability_proposal.received` | `studio.lerian.consignado-gw.consignado_portability_proposal.received` | `consignado_portability_proposal` / `received` | `id_solicitacao` | O gateway descobre uma oferta de portabilidade M011 ativa e a registra com seu envelope de outbox. |
| `consignado.margin.fetched` | `studio.lerian.consignado-gw.consignado_margin.fetched` | `consignado_margin` / `fetched` | `request_ref` | O gateway lê a margem do trabalhador no Dataprev. |
| `consignado.proposal.accepted` | `studio.lerian.consignado-gw.consignado_proposal.accepted` | `consignado_proposal` / `accepted` | `proposal_ref` | O gateway constata a proposta aceita do trilho em relação à oferta durável do cliente, depois de `consignado.averbacao.confirmed`. |
| `consignado.averbacao.accepted` | `studio.lerian.consignado-gw.consignado_averbacao.accepted` | `consignado_averbacao` / `accepted` | `contract_id` | O Dataprev aceita a averbação (Manual 003), e o contrato aguarda sua documentação. |
| `consignado.averbacao.documentation_deadline` | `studio.lerian.consignado-gw.consignado_averbacao.documentation_deadline` | `consignado_averbacao` / `documentation_deadline` | `contract_id` | A documentação de uma averbação aceita vence em 48 horas, ou está vencida. |
| `consignado.averbacao.confirmed` | `studio.lerian.consignado-gw.consignado_averbacao.confirmed` | `consignado_averbacao` / `confirmed` | `contract_id` | O Dataprev aceita a documentação de uma averbação aceita (Manual 004). |
| `consignado.averbacao.rejected` | `studio.lerian.consignado-gw.consignado_averbacao.rejected` | `consignado_averbacao` / `rejected` | `contract_id` | O Dataprev rejeita a averbação. |
| `consignado.contract.registered` | `studio.lerian.consignado-gw.consignado_contract.registered` | `consignado_contract` / `registered` | `numero_contrato` | O registro do contrato atinge seu limite imutável. |
| `consignado.disbursement.confirmed` | `studio.lerian.consignado-gw.consignado_disbursement.confirmed` | `consignado_disbursement` / `confirmed` | `numero_contrato` | O cliente confirma que o trabalhador recebeu os recursos. |
| `consignado.contract_correction.available` | `studio.lerian.consignado-gw.consignado_contract_correction.available` | `consignado_contract_correction` / `available` | `numero_contrato` | Um cliente substitui a CCB assinada e expõe o recurso corrigido para recuperação autenticada. |
| `consignado.disbursement_correction.available` | `studio.lerian.consignado-gw.consignado_disbursement_correction.available` | `consignado_disbursement_correction` / `available` | `numero_contrato` | Um cliente substitui uma confirmação de pagamento e expõe o recurso corrigido para recuperação autenticada. |
| `consignado.portabilidade.efetivada` | `studio.lerian.consignado-gw.consignado_portabilidade.efetivada` | `consignado_portabilidade` / `efetivada` | `numero_contrato` | O Dataprev aceita a exclusão de portabilidade do lado de origem deste gateway e o contrato deixa a instituição. |
| `consignado.portabilidade.rejeitada` | `studio.lerian.consignado-gw.consignado_portabilidade.rejeitada` | `consignado_portabilidade` / `rejeitada` | `numero_contrato` | O Dataprev rejeita a exclusão de portabilidade do lado de origem deste gateway, ou uma leitura posterior do Dataprev mostra que ela não rodou. |
| `consignado.renegociacao.efetivada` | `studio.lerian.consignado-gw.consignado_renegociacao.efetivada` | `consignado_renegociacao` / `efetivada` | `numero_contrato` | O Dataprev aceita uma renegociação por término de vínculo, e um novo contrato substitui o contrato encerrado. |
| `consignado.renegociacao.recusada` | `studio.lerian.consignado-gw.consignado_renegociacao.recusada` | `consignado_renegociacao` / `recusada` | `numero_contrato_encerrado` | Uma renegociação por término de vínculo é recusada, e o contrato encerrado continua encerrado. |
| `consignado.exclusao.confirmed` | `studio.lerian.consignado-gw.consignado_exclusao.confirmed` | `consignado_exclusao` / `confirmed` | `numero_contrato` | A exclusão do contrato atinge um estado terminal de sucesso. |
| `consignado.exclusao.rejected` | `studio.lerian.consignado-gw.consignado_exclusao.rejected` | `consignado_exclusao` / `rejected` | `numero_contrato` | A exclusão do contrato atinge um estado terminal de rejeição. |
| `consignado.reconciliation.received` | `studio.lerian.consignado-gw.consignado_reconciliation.received` | `consignado_reconciliation` / `received` | `object_ref` | O gateway normaliza um registro de escrituração, repasse ou CSV do portal. |
| `consignado.employment_status.reported` | `studio.lerian.consignado-gw.consignado_employment_status.reported` | `consignado_employment_status` / `reported` | `record_id` | O gateway lê um registro de suspensão ou desligamento do vínculo empregatício. |
| `consignado.afastamento.reported` | `studio.lerian.consignado-gw.consignado_afastamento.reported` | `consignado_afastamento` / `reported` | `SHA-256(payload)` | Um alerta de afastamento ou desligamento do trabalhador é reportado. |
| `consignado.throughput.changed` | `studio.lerian.consignado-gw.consignado_throughput.changed` | `consignado_throughput` / `changed` | `tenant_id` | O throughput efetivo de um tenant no Dataprev muda. |
| `consignado.cessao.registered` | `studio.lerian.consignado-gw.consignado_cessao.registered` | `consignado_cessao` / `registered` | `numero_contrato` ou `idempotency_key` | Um crédito ou contrato passa para um fundo, pela operação de cessão ou por um fato de cessão do Lender. |
| `consignado.registro_b3.registered` | `studio.lerian.consignado-gw.consignado_registro_b3.registered` | `consignado_registro_b3` / `registered` | `numero_contrato` | O cliente informa o código do instrumento na B3 de um contrato com averbação confirmada. |
| `consignado.repasse.overdue` | `studio.lerian.consignado-gw.consignado_repasse.overdue` | `consignado_repasse` / `overdue` | `object_ref` | Um repasse esperado ultrapassa seu prazo ou não tem prazo calculável. |
| `consignado.repasse.resolved` | `studio.lerian.consignado-gw.consignado_repasse.resolved` | `consignado_repasse` / `resolved` | `object_ref` | Uma movimentação resolve um repasse em atraso. |
| `consignado.repasse.unobserved` | `studio.lerian.consignado-gw.consignado_repasse.unobserved` | `consignado_repasse` / `unobserved` | `object_ref` | O gateway não consegue estabelecer uma observação atual do trilho para as expectativas. |
| `consignado.calendar.published` | `studio.lerian.consignado-gw.consignado_calendar.published` | `consignado_calendar` / `published` | `competencia_consulta` | Uma janela operacional do calendário de descontos é publicada. |
| `consignado.rail.paused` | `studio.lerian.consignado-gw.consignado_rail.paused` | `consignado_rail` / `paused` | `tenant/<tenant_id>` | Um job agendado do gateway recebe a recusa da virada de competência do Dataprev, e o gateway abre uma pausa para o tenant. |
| `consignado.rail.resumed` | `studio.lerian.consignado-gw.consignado_rail.resumed` | `consignado_rail` / `resumed` | `tenant/<tenant_id>` | A pausa do tenant termina. |

## Notação do payload

O wire usa JSON com nomes de propriedade em `snake_case`, exceto `consignado.registro_b3.registered`, que usa `camelCase`. Estes aliases descrevem os formatos usados pelos esquemas:

```typescript theme={null}
type Decimal = string
type RFC3339 = string
type DateOnly = string
type YearMonth = string
type UUID = string
type RailCodePair = {
  codigo: number
  descricao: string
}
```

`originador_ref` é o originador cujo lance produziu o contrato. `fundo_ref` é o fundo que recebeu o contrato em uma cessão. O novo contrato de um refinanciamento ou de uma renegociação que o gateway registrou como aceito herda uma parte dos contratos que ele substituiu. Ele herda uma parte apenas quando todos esses contratos nomeiam a mesma, e apenas quando ele não tem essa parte. Um fundo do cadastro de fundos do Lender aparece com seu id de fundo no Lender. Em `consignado.contract.registered`, `fund_ref` é o fundo ao qual a averbação atribui o contrato. Nos fatos de averbação, `remetente_fundo_ref` é o fundo cuja credencial enviou a averbação ou sua documentação. Ele fica ausente quando nenhuma credencial de fundo enviou nenhuma das duas, mesmo quando a averbação nomeia um fundo.

## Contratos de payload

> [accordion] consignado.solicitacao.received
>
> O gateway descobre uma solicitação de empréstimo aberta no Dataprev.
>
> **Assunto:** `id_solicitacao`
>
> ```typescript theme={null}
> type ConsignadoSolicitacaoReceivedV1 = {
> id_solicitacao: string
> codigo_solicitante: string
> cpf: string
> matricula: string
> nome_trabalhador: string
> data_nascimento: DateOnly | ""
> inscricao_empregador: RailCodePair | null
> numero_inscricao_empregador: string
> data_admissao: DateOnly | ""
> valor_liberado: Decimal
> nro_parcelas: number
> margem_disponivel: Decimal
> elegivel_emprestimo?: boolean
> data_hora_validade_solicitacao: RFC3339
> pessoa_exposta_politicamente?: RailCodePair
> garantias: {
>   tem_garantias: boolean
>   valor_saldo_disponivel_garantia_fgts?: Decimal
>   valor_multa_rescisoria_garantia_fgts?: Decimal
>   perc_verba_rescisoria_garantia?: Decimal
> }
> discovered_at: RFC3339
> }
> ```

> [accordion] consignado.portability\_proposal.received
>
> O gateway descobre uma oferta de portabilidade M011 ativa e a registra com seu envelope de outbox.
>
> **Assunto:** `id_solicitacao`
>
> ```typescript theme={null}
> type ConsignadoPortabilityProposalReceivedV1 = {
> id_solicitacao: string
> cpf: string
> matricula: string
> nome_trabalhador: string
> numero_inscricao_empregador: string
> margem_disponivel: Decimal
> elegivel_emprestimo?: boolean
> data_hora_validade_solicitacao: RFC3339
> }
> ```

> [accordion] consignado.margin.fetched
>
> O gateway lê a margem do trabalhador no Dataprev.
>
> **Assunto:** `request_ref`
>
> ```typescript theme={null}
> type ConsignadoMarginFetchedV1 = {
> request_ref: string
> cpf: string
> matricula: string
> available_margin: Decimal
> remuneracao_disponivel: Decimal
> valor_total_vencimentos?: Decimal
> elegivel?: boolean
> motivo_inelegibilidade?: RailCodePair
> tipo_bloqueio?: RailCodePair
> qtd_emprestimos_ativos_suspensos?: number
> data_desligamento?: DateOnly
> codigo_motivo_desligamento?: string
> percentual_verba_rescisoria_disponivel?: Decimal
> as_of: RFC3339
> }
> ```

> [accordion] consignado.proposal.accepted
>
> O gateway constata a proposta aceita do trilho em relação à oferta durável do cliente. O gateway publica este fato depois de `consignado.averbacao.confirmed`, quando o Dataprev aceita a documentação (Manual 004). `consignado.averbacao.accepted` não o dispara, então ele pode chegar dias depois da averbação.
>
> **Assunto:** `proposal_ref`
>
> ```typescript theme={null}
> type ConsignadoProposalAcceptedV1 = {
> proposal_ref: string
> id_solicitacao: string
> numero_proposta: string
> numero_contrato: string
> cpf: string
> matricula: string
> numero_inscricao_empregador: string
> principal_amount: Decimal
> liberated_amount: Decimal
> installment_amount: Decimal
> installment_count: number
> monthly_rate: Decimal
> annual_rate: Decimal
> cet_monthly: Decimal
> cet_annual: Decimal
> iof_amount: Decimal
> situacao_emprestimo?: number
> situacao_descricao?: string
> garantia?: {
>   tem_garantias: boolean
>   valor_saldo_disponivel_garantia_fgts?: Decimal
>   valor_multa_rescisoria_garantia_fgts?: Decimal
>   perc_verba_rescisoria_garantia?: Decimal
> }
> accepted_at: RFC3339
> inscricao_empregador?: RailCodePair
> if_concessora?: RailCodePair
> origem_averbacao?: RailCodePair
> origem_exclusao?: RailCodePair
> motivo_exclusao?: RailCodePair
> situacao_bloqueio_garantia?: RailCodePair
> nome_trabalhador?: string
> nome_empregador?: string
> cnpj_operador?: string
> cnpj_empregador_completo?: boolean
> valor_troco?: Decimal
> competencia_inicio_desconto?: YearMonth
> competencia_fim_desconto?: YearMonth
> qtd_escrituracoes?: string
> qtd_pagamentos?: string
> portabilidade_codigo_origem?: string
> portabilidade_codigo_proponente?: string
> portabilidade_numero_unico_averbacao?: string
> portabilidade_numero_unico_exclusao?: string
> portabilidade_situacao?: RailCodePair
> portabilidade_valor_pago?: Decimal
> data_inicio_contrato?: RFC3339
> data_fim_contrato?: RFC3339
> data_primeiro_desconto?: RFC3339
> atualizado_em?: RFC3339
> excluido_em?: RFC3339
> info_contrato_enviada_em?: RFC3339
> originador_ref?: string
> fundo_ref?: string
> }
> ```

> [accordion] consignado.averbacao.accepted
>
> O Dataprev aceita a averbação (Manual 003). O mandato de desconto em folha existe no trilho, e o contrato aguarda sua documentação. Envie a documentação por `POST /v1/consignado/contracts/{numero_contrato}/ccb-attachment`. Este fato não contabiliza, não desembolsa e não fatura. Contabilize um contrato apenas a partir de `consignado.contract.registered`.
>
> Uma exclusão ainda pode cancelar a averbação antes do envio da documentação. Quando o Dataprev confirma a exclusão, `consignado.exclusao.confirmed` vem em seguida, e nem `consignado.averbacao.confirmed` nem `consignado.contract.registered` são publicados.
>
> Uma subscription restrita a um originador recebe este fato apenas quando `originador_ref` nomeia esse originador. Uma subscription restrita a um fundo o recebe apenas quando `remetente_fundo_ref` nomeia esse fundo. `consignado.averbacao.documentation_deadline`, `consignado.averbacao.confirmed` e `consignado.averbacao.rejected` seguem a mesma regra.
>
> A credencial de fundo ou de originador que enviou a averbação ou sua documentação a lê com `GET .../averbacao`. Para qualquer outro contrato, uma credencial de fundo ou de originador recebe `404`. A credencial do próprio tenant lê todos os contratos.
>
> `averbado_at` é o instante em que o gateway registrou a aceitação do Manual 003. Quando o gateway comprova um resultado desconhecido lendo o contrato de volta no Dataprev, `dataprev_success_code` é `GW-M005-AVERBADO` e `averbado_at` é o instante dessa leitura.
>
> **Assunto:** `contract_id`
>
> ```typescript theme={null}
> type ConsignadoAverbacaoAcceptedV1 = {
> contract_id: string
> numero_contrato: string
> dataprev_success_code: string
> averbado_at: RFC3339
> originador_ref?: string
> remetente_fundo_ref?: string
> }
> ```

> [accordion] consignado.averbacao.documentation\_deadline
>
> A documentação de uma averbação aceita vence em 48 horas (`approaching`), ou está vencida (`expired`). O Manual 004 dá à instituição 7 dias após a averbação para enviar a documentação. O gateway conta 7 dias corridos a partir de `averbado_at`. Este fato é apenas um sinal. O gateway não exclui nem altera o contrato quando o prazo passa.
>
> O gateway publica este fato apenas para uma averbação que aguarda sua documentação. Ela está em `attachment_pending`, nenhuma tentativa de documentação está aberta, nenhuma exclusão está pendente ou confirmada para ela, e ela não [saiu do registro](https://docs.lerian.studio/pt/rails/consignado/how-consignado-works.md#5-service-the-contract). Cada contrato recebe `approaching` uma vez, 48 horas antes de `documentation_due_at`, e `expired` uma vez, em `documentation_due_at`. Um contrato que o gateway encontra pela primeira vez depois do seu instante de vencimento recebe apenas `expired`. O `ce-id` é estável para cada contrato e etapa. `ce-time` é o instante em que o gateway gravou o fato.
>
> `averbado_at` repete o valor de `consignado.averbacao.accepted`, e `documentation_due_at` é `averbado_at` mais 7 dias. `averbado_at_origin` é `dataprev_response` quando o gateway registrou `averbado_at` ao receber a aceitação do Dataprev. É `recovery_read` quando uma leitura posterior no Dataprev comprovou a aceitação. Nos dois casos, o prazo do Dataprev pode ser anterior a `documentation_due_at`. A diferença pode ser maior com `recovery_read`.
>
> O sinal de prazo vem desabilitado por padrão. Um deploy publica este fato apenas enquanto o sinal está habilitado.
>
> **Assunto:** `contract_id`
>
> ```typescript theme={null}
> type ConsignadoAverbacaoDocumentationDeadlineV1 = {
> contract_id: string
> numero_contrato: string
> stage: "approaching" | "expired"
> averbado_at: RFC3339
> averbado_at_origin: "dataprev_response" | "recovery_read"
> documentation_due_at: RFC3339
> originador_ref?: string
> remetente_fundo_ref?: string
> }
> ```

> [accordion] consignado.averbacao.confirmed
>
> O Dataprev aceita a documentação de uma averbação aceita (Manual 004), e a averbação está completa. O Manual 004 dá à instituição 7 dias após a averbação para enviar a documentação. O gateway não controla esse prazo. `consignado.averbacao.documentation_deadline` sinaliza esse prazo.
>
> `averbado_at` e `dataprev_success_code` mantêm os valores do Manual 003 do fato de aceitação. Leia o instante da averbação em `averbado_at`, não no horário de publicação.
>
> **Assunto:** `contract_id`
>
> ```typescript theme={null}
> type ConsignadoAverbacaoConfirmedV1 = {
> contract_id: string
> numero_contrato: string
> dataprev_success_code: string
> averbado_at: RFC3339
> originador_ref?: string
> remetente_fundo_ref?: string
> }
> ```

> [accordion] consignado.averbacao.rejected
>
> O Dataprev rejeita a averbação (Manual 003). Quando o gateway comprova um resultado desconhecido lendo o contrato de volta no Dataprev e o Dataprev não tem esse empréstimo, `error_code` é o código `HY` do Manual 005. Uma falha no envio da documentação (Manual 004) não publica nenhum fato.
>
> **Assunto:** `contract_id`
>
> ```typescript theme={null}
> type ConsignadoAverbacaoRejectedV1 = {
> contract_id: string
> numero_contrato: string
> error_code: string
> error_message: string
> originador_ref?: string
> remetente_fundo_ref?: string
> }
> ```

> [accordion] consignado.contract.registered
>
> A contabilização do contrato atinge seu limite imutável. Para uma averbação feita pelo gateway com o bloco de contabilização, este fato vem depois de `consignado.averbacao.confirmed`. Uma averbação sem o bloco de contabilização nunca o emite. Uma importação de contrato com `booking` o emite sem nenhum fato de averbação. Contabilize um contrato apenas a partir deste fato.
>
> O campo `dados_cadastrais_digest_sha256` é o digest SHA-256 do cadastro que o gateway armazenou para o contrato. O gateway armazena um cadastro para todo contrato, com pelo menos `nome_trabalhador`. O campo só fica ausente em um contrato que o gateway salvou antes de armazenar um cadastro para todo contrato.
>
> O campo `signature.signed_at` é o `data_hora_assinatura` da documentação. Os outros campos de `signature` e os dois `artifacts` também vêm da documentação, exceto `signature.binding_method`, que é sempre `portal_attested`. Os campos `identity.esocial_category` e `identity.admission_date` descrevem o vínculo empregatício. Cada um vem do cadastro da averbação ou, na falta dele, da leitura de margem mais recente no Dataprev para o mesmo trabalhador e empregador. Cada um fica ausente quando desconhecido.
>
> Os campos `declared_terms.origination_fee_amount` e `preparation` repetem as declarações do cliente na requisição de averbação. O gateway verifica o formato deles e que `origination_fee_amount` seja menor que `principal_amount`, e nunca os consulta. Um `origination_fee_amount` ausente significa zero.
>
> Todo valor e toda taxa deste fato têm exatamente duas casas decimais, por exemplo `1201.20` e `100.00`.
>
> **Assunto:** `numero_contrato`
>
> ```typescript theme={null}
> type ConsignadoContractRegisteredV1 = {
> contract_id: string
> numero_contrato: string
> numero_proposta?: string
> identity: {
>   cpf: string
>   matricula: string
>   codigo_inscricao_empregador: string
>   numero_inscricao_empregador: string
>   esocial_category?: string
>   admission_date?: DateOnly
> }
> declared_terms: {
>   principal_amount: Decimal
>   liberated_amount: Decimal
>   installment_amount: Decimal
>   installment_count: number
>   monthly_interest_rate: Decimal
>   annual_interest_rate: Decimal
>   cet_monthly: Decimal
>   cet_annual: Decimal
>   iof_amount: Decimal
>   first_deduction_competencia: YearMonth
>   contract_start_date: DateOnly
>   contract_end_date: DateOnly
>   first_deduction_date: DateOnly
>   expected_disbursement_date: DateOnly
>   loan_product_version: string
>   formalization_deadline: RFC3339
>   guarantee: {
>     tem_garantias: boolean
>     valor_saldo_disponivel_garantia_fgts?: Decimal
>     valor_multa_rescisoria_garantia_fgts?: Decimal
>     perc_verba_rescisoria_garantia?: Decimal
>   }
>   origination_fee_amount?: Decimal
> }
> rail_terms: {
>   principal_amount: Decimal
>   liberated_amount: Decimal
>   installment_amount: Decimal
>   installment_count: number
>   monthly_interest_rate: Decimal
>   annual_interest_rate: Decimal
>   cet_monthly: Decimal
>   cet_annual: Decimal
>   iof_amount: Decimal
>   accepted_at: RFC3339
>   guarantee?: {
>     tem_garantias: boolean
>     valor_saldo_disponivel_garantia_fgts?: Decimal
>     valor_multa_rescisoria_garantia_fgts?: Decimal
>     perc_verba_rescisoria_garantia?: Decimal
>   }
> }
> margin_snapshot: {
>   available_margin: Decimal
>   remuneracao_disponivel: Decimal
>   as_of: RFC3339
> }
> signature: {
>   binding_method: string
>   signed_at: RFC3339
>   provider_evidence_ref: string
>   ip: string
>   icp_brasil: boolean
>   analfabeto: boolean
> }
> artifacts: {
>   signed_ccb: {
>     digest_sha256: string
>     blob_ref: string
>   }
>   biometrics_documents_pack: {
>     digest_sha256: string
>     blob_ref: string
>   }
> }
> registration: {
>   averbado_at: RFC3339
>   response_code: string
>   attachment_hash_operacao: string
> }
> fund_ref?: string
> dados_cadastrais_digest_sha256?: string
> originador_ref?: string
> fundo_ref?: string
> preparation?: {
>   quote_id: UUID
>   credit_instrument_id: UUID
>   original_ccb_digest_sha256: string
> }
> }
> ```

> [accordion] consignado.disbursement.confirmed
>
> O cliente confirma que o trabalhador recebeu os recursos.
>
> **Assunto:** `numero_contrato`
>
> ```typescript theme={null}
> type ConsignadoDisbursementConfirmedV1 = {
> confirmation_id: UUID
> numero_contrato: string
> amount: Decimal
> paid_at: RFC3339
> payment_reference: string
> confirmed_at: RFC3339
> originador_ref?: string
> fundo_ref?: string
> }
> ```

> [accordion] consignado.contract\_correction.available / consignado.disbursement\_correction.available
>
> Um cliente substitui uma CCB assinada ou um pagamento já confirmado. O payload aponta para o recurso corrigido. Os consumidores o recuperam por M2M autenticado e verificam seu digest SHA-256. O `ce-resourcetype` do evento distingue o tipo de correção.
>
> **Assunto:** `numero_contrato`
>
> ```typescript theme={null}
> type ConsignadoCorrectionAvailableV1 = {
>   numero_contrato: string
>   source_authority: string
>   resource_uri: string
>   resource_digest_sha256: string
>   gateway_received_at: RFC3339
>   supersedes_event_id?: string
>   originador_ref?: string
>   fundo_ref?: string
> }
> ```

> [accordion] consignado.portabilidade.efetivada
>
> O Dataprev aceita a exclusão de portabilidade do lado de origem deste gateway. O contrato deixa a instituição, então a gestão da carteira downstream pode parar. Este fato não reporta o lado da instituição de destino e não carrega valor de liquidação.
>
> **Assunto:** `numero_contrato`
>
> ```typescript theme={null}
> type ConsignadoPortabilidadeEfetivadaV1 = {
>   fact_id: string
>   tenant_id: string
>   numero_contrato: string
>   status: "efetivada"
>   destination_institution: string
>   external_operation_ref: string
>   outcome_at: RFC3339
>   originador_ref?: string
>   fundo_ref?: string
> }
> ```

> [accordion] consignado.portabilidade.rejeitada
>
> O Dataprev rejeita a exclusão de portabilidade do lado de origem deste gateway. O contrato permanece em vigor.
>
> O gateway também publica este fato, com `reason_code` `GW-M005-NAO-EXECUTADO`, para uma exclusão que não recebeu resposta. Ele faz isso quando uma leitura do Dataprev feita uma hora após o prazo da exclusão ainda mostra o contrato ativo. Envie a exclusão de novo com uma nova chave.
>
> **Assunto:** `numero_contrato`
>
> ```typescript theme={null}
> type ConsignadoPortabilidadeRejeitadaV1 = {
>   fact_id: string
>   tenant_id: string
>   numero_contrato: string
>   status: "rejeitada"
>   reason_code: string
>   message: string
>   outcome_at: RFC3339
>   originador_ref?: string
>   fundo_ref?: string
> }
> ```

> [accordion] consignado.renegociacao.efetivada
>
> O Dataprev aceita uma renegociação por término de vínculo. O novo contrato, `numero_contrato`, substitui o contrato encerrado, `numero_contrato_encerrado`, no novo vínculo empregatício do trabalhador. `iniciada_por` é `cliente` para uma renegociação que você envia pela [operação de renegociação](https://docs.lerian.studio/pt/reference/rails/consignado/renegociar-consignado-contract.md). Ele é `gateway` para uma [renegociação automática](https://docs.lerian.studio/pt/rails/consignado/how-consignado-works.md#automatic-renegotiation), e o gateway criou `numero_contrato`. `matricula` e a inscrição do empregador descrevem o novo vínculo. Um campo que a origem não trouxe fica ausente.
>
> Em uma renegociação automática, `competencias_puladas` lista as competências do contrato encerrado do mês do desligamento até a anterior à competência atual. O novo contrato não as cobre. Ele fica ausente quando não há nenhuma.
>
> **Assunto:** `numero_contrato`
>
> ```typescript theme={null}
> type ConsignadoRenegociacaoEfetivadaV1 = {
>   numero_contrato: string
>   numero_contrato_encerrado: string
>   iniciada_por: "cliente" | "gateway"
>   valor_parcela?: Decimal
>   numero_parcelas?: number
>   taxa_mensal?: Decimal
>   taxa_anual?: Decimal
>   valor_emprestimo?: Decimal
>   valor_liberado?: Decimal
>   competencia_inicio_desconto?: YearMonth
>   data_primeiro_desconto?: RFC3339
>   data_fim_contrato?: RFC3339
>   matricula?: string
>   codigo_inscricao_empregador?: string
>   numero_inscricao_empregador?: string
>   hash_operacao?: string
>   competencias_puladas?: YearMonth[]
>   outcome_at: RFC3339
>   originador_ref?: string
>   fundo_ref?: string
> }
> ```

> [accordion] consignado.renegociacao.recusada
>
> Uma renegociação por término de vínculo é recusada. O contrato encerrado continua encerrado, e nenhum novo contrato existe. `numero_contrato_tentado` é o número do novo contrato que a renegociação pediu. `iniciada_por` indica quem começou a renegociação, como em `consignado.renegociacao.efetivada`. Quando `refused_by` é `dataprev`, `reason_code` contém o código do Dataprev, ou vários códigos unidos por vírgula.
>
> Quando `refused_by` é `gateway`, o gateway devolveu o contrato sem um envio, e `iniciada_por` é `gateway`. `reason_code` contém um [motivo de devolução](https://docs.lerian.studio/pt/rails/consignado/how-consignado-works.md#automatic-renegotiation). `numero_contrato_tentado` é o número que o gateway criou, e ele nunca chegou ao Dataprev. O gateway publica no máximo uma devolução para cada contrato encerrado.
>
> **Assunto:** `numero_contrato_encerrado`
>
> ```typescript theme={null}
> type ConsignadoRenegociacaoRecusadaV1 = {
>   numero_contrato_tentado: string
>   numero_contrato_encerrado: string
>   iniciada_por: "cliente" | "gateway"
>   refused_by: "dataprev" | "gateway"
>   reason_code: string
>   outcome_at: RFC3339
>   originador_ref?: string
>   fundo_ref?: string
> }
> ```

> [accordion] consignado.exclusao.confirmed
>
> A exclusão do contrato atinge um estado terminal de sucesso.
>
> **Assunto:** `numero_contrato`
>
> ```typescript theme={null}
> type ConsignadoExclusaoConfirmedV1 = {
> fact_id: UUID
> tenant_id: string
> request_ref: UUID
> numero_contrato: string
> motivo_exclusao: string
> status: "confirmed"
> provider_reference?: string
> outcome_at: RFC3339
> evidence_source: "exclude_response" | "m005_observation" | "operator_evidence"
> originador_ref?: string
> fundo_ref?: string
> }
> ```

> [accordion] consignado.exclusao.rejected
>
> A exclusão do contrato atinge um estado terminal de rejeição. A versão do esquema é `1.1.0`. Com `evidence_source` `exclude_response`, o Dataprev recusou a exclusão, e o contrato continua no registro. Com `evidence_source` `m005_observation`, uma leitura do Dataprev mostrou que o contrato já tinha saído do registro de outra forma, e `reason_code` começa com `contract_left_registry.`. Uma nova exclusão com o mesmo `motivo_exclusao` retorna a mesma rejeição.
>
> **Assunto:** `numero_contrato`
>
> ```typescript theme={null}
> type ConsignadoExclusaoRejectedV1 = {
> fact_id: UUID
> tenant_id: string
> request_ref: UUID
> numero_contrato: string
> motivo_exclusao: string
> status: "rejected"
> provider_reference?: string
> reason_code?: string
> message?: string
> outcome_at: RFC3339
> evidence_source: "exclude_response" | "m005_observation" | "operator_evidence"
> originador_ref?: string
> fundo_ref?: string
> }
> ```

> [accordion] consignado.reconciliation.received
>
> O gateway normaliza um registro de escrituração, repasse ou CSV do portal.
>
> `competencia` está presente em toda origem. Em um fato `dataprev_repasse`, ela é o mês do repasse esperado que o registro liquida ou, na falta dele, o mês do trilho. O registro mantém a própria `competencia` do trilho. O gateway retém um registro de repasse que não indica empregador ou mês até que um repasse esperado os forneça. Um registro de repasse que não indica mês e traz encargos de atraso ou verbas rescisórias fica retido e não é publicado até que a Lerian o resolva.
>
> **Assunto:** `object_ref`
>
> ```typescript theme={null}
> type ConsignadoReconciliationReceivedV1 = {
>   competencia: YearMonth
>   source_kind: "dataprev_escrituracao" | "dataprev_repasse" | "portal_csv"
>   object_ref: string
>   records?: RepasseRecord[] | EscrituracaoRecord[]
> }
>
> type RepasseRecord = {
>   id: string
>   numero_guia: string
>   numero_contrato: string
>   cpf?: string
>   matricula?: string
>   valor_parcela_paga: Decimal
>   codigo_trf: string
>   data_repasse_if: RFC3339
>   status_repasse: string
>   verbas_rescisorias: boolean
>   competencia?: YearMonth
>   data_hora_inclusao_dataprev?: RFC3339
>   valor_multa?: Decimal
>   valor_juros_de_mora?: Decimal
>   valor_atualizacao_monetaria?: Decimal
> }
>
> type EscrituracaoRecord = {
>   numero_contrato: string
>   cpf?: string
>   matricula?: string
>   valor_parcela: Decimal
>   analise: {
>     existe_trabalhador_escriturado: boolean
>     existe_numero_contrato_escriturado: boolean
>     vinculo_correto: boolean
>     instituicao_financeira_correta: boolean
>     valor_parcela_correta: boolean
>     dados_correspondentes: boolean
>   }
>   tipo_evento_esocial: {
>     codigo: number
>     descricao: string
>   }
> }
> ```

> [accordion] consignado.employment\_status.reported
>
> O gateway lê um registro de suspensão ou desligamento do vínculo empregatício.
>
> **Assunto:** `record_id`
>
> ```typescript theme={null}
> type ConsignadoEmploymentStatusReportedV1 = {
> report_ref: string
> record_id: string
> numero_contrato: string
> status: "suspended" | "terminated"
> effective_at: RFC3339
> reason_code?: string
> originador_ref?: string
> fundo_ref?: string
> }
> ```

> [accordion] consignado.afastamento.reported
>
> Um alerta de afastamento ou desligamento do trabalhador é reportado.
>
> **Assunto:** `SHA-256(payload)`
>
> ```typescript theme={null}
> type ConsignadoAfastamentoReportedV1 = {
> cpf: string
> matricula: string
> tipo_alerta_codigo: string
> codigo_motivo_afastamento?: string
> data_referencia: DateOnly
> data_afastamento?: DateOnly
> data_termino_afastamento?: DateOnly
> codigo_motivo_desligamento?: string
> data_desligamento?: DateOnly
> data_aviso_previo?: DateOnly
> data_fim_aviso_previo?: DateOnly
> }
> ```

> [accordion] consignado.throughput.changed
>
> O throughput efetivo de um tenant no Dataprev muda.
>
> **Assunto:** `tenant_id`
>
> ```typescript theme={null}
> type ConsignadoThroughputChangedV1 = {
> tenant_id: string
> sequence: number
> requests_per_second: number
> previous_requests_per_second?: number
> changed_at: RFC3339
> changed_by: string
> }
> ```

> [accordion] consignado.cessao.registered
>
> Um crédito ou contrato passa para um fundo. Dois produtores escrevem este fato. A operação de cessão identifica o crédito pelo `idempotency_key` do lance, com `cedido_by: bancarizador_command`. O fato do Lender `assignment_receivable.accepted` identifica o contrato por `numero_contrato`, com `cedido_by: lender_fact`, e também carrega o `idempotency_key` do lance para um contrato de leilão. O campo `cedido_at` é o instante da operação ou o `accepted_at` do Lender. A operação de cessão recusa um crédito com 409 `CESSAO_CREDIT_NOT_WITNESSED` até que sua averbação esteja confirmada.
>
> **Assunto:** `numero_contrato` quando presente, senão `idempotency_key`
>
> ```typescript theme={null}
> type ConsignadoCessaoRegisteredV1 = {
> tenant_id: string
> idempotency_key?: string
> numero_contrato?: string
> fundo_ref: string
> cedido_at: RFC3339
> cedido_by: "bancarizador_command" | "lender_fact"
> originador_ref?: string
> }
> ```

> [accordion] consignado.registro\_b3.registered
>
> O cliente informa o código do instrumento na B3 (Código IF) de um contrato com averbação confirmada. O gateway não contata a B3 e não confere o código com a CCB. Este fato usa nomes de propriedade em `camelCase`. O gateway o publica uma vez por contrato, com o mesmo `ce-id` em toda entrega.
>
> O campo `numeroCcb` é o número da CCB no cadastro armazenado, ou `numeroContrato` quando o cadastro não tem um. O campo `dataRegistro` é a data de registro na B3, quando o cliente a envia. O campo `registradoEm` é o instante em que o gateway armazenou o código. O campo `registradoPor` indica o subject de quem chamou, quando a identidade o carrega.
>
> Uma subscription restrita a um originador ou a um fundo não recebe este fato. Só uma subscription do tenant inteiro o recebe.
>
> **Assunto:** `numero_contrato`
>
> ```typescript theme={null}
> type ConsignadoRegistroB3RegisteredV1 = {
> tenantId: string
> numeroContrato: string
> numeroCcb: string
> codigoInstrumentoFinanceiro: string
> dataRegistro?: DateOnly
> registradoEm: RFC3339
> registradoPor?: string
> }
> ```

> [accordion] consignado.repasse.overdue
>
> Um repasse esperado ultrapassa seu prazo ou não tem prazo calculável.
>
> **Assunto:** `object_ref`
>
> ```typescript theme={null}
> type ConsignadoRepasseOverdueV1 = {
> object_ref: string
> cnpj?: string
> numero_contrato: string
> competencia: YearMonth
> reason: "repasse_missing" | "deadline_uncomputable"
> due_at?: RFC3339
> observed_at: RFC3339
> originador_ref?: string
> fundo_ref?: string
> }
> ```

> [accordion] consignado.repasse.resolved
>
> Uma movimentação resolve um repasse em atraso.
>
> **Assunto:** `object_ref`
>
> ```typescript theme={null}
> type ConsignadoRepasseResolvedV1 = {
> object_ref: string
> cnpj?: string
> numero_contrato: string
> competencia: YearMonth
> estimated_due_at?: RFC3339
> guia_paid_at?: RFC3339
> exact_due_at?: RFC3339
> repasse_paid_at?: RFC3339
> settled_at: RFC3339
> originador_ref?: string
> fundo_ref?: string
> }
> ```

> [accordion] consignado.repasse.unobserved
>
> O gateway não consegue estabelecer uma observação atual do trilho para as expectativas.
>
> **Assunto:** `object_ref`
>
> ```typescript theme={null}
> type ConsignadoRepasseUnobservedV1 = {
> object_ref: string
> last_observed_at?: RFC3339
> }
> ```

> [accordion] consignado.calendar.published
>
> Uma janela operacional do calendário de descontos é publicada.
>
> **Assunto:** `competencia_consulta`
>
> ```typescript theme={null}
> type ConsignadoCalendarPublishedV1 = {
> competencia_atual: YearMonth
> competencia_consulta: YearMonth
> data_inicio_competencia: DateOnly
> data_fim_competencia: DateOnly
> }
> ```

> [accordion] consignado.rail.paused
>
> Um job agendado do gateway recebe a recusa da virada de competência do Dataprev, e o gateway abre uma pausa para o tenant. Apenas deploys na Lerian Cloud emitem este fato. `hold_until` é o fim da primeira espera, não o fim da virada de competência.
>
> **Assunto:** `tenant/<tenant_id>`
>
> ```typescript theme={null}
> type ConsignadoRailPausedV1 = {
> tenant_id: string
> episode: number
> paused_at: RFC3339
> hold_until: RFC3339
> rail_codes: string
> armed_by_job: string
> }
> ```

> [accordion] consignado.rail.resumed
>
> A pausa do tenant termina. Apenas deploys na Lerian Cloud emitem este fato. `episode` tem o mesmo valor do fato de pausa que ele encerra.
>
> **Assunto:** `tenant/<tenant_id>`
>
> ```typescript theme={null}
> type ConsignadoRailResumedV1 = {
> tenant_id: string
> episode: number
> paused_at: RFC3339
> resumed_at: RFC3339
> paused_for_seconds: number
> }
> ```

## Comandos consumidos do Lender

Estes são comandos de entrada, não eventos emitidos pelo Consignado. Eles chegam em `lerian.streaming.lender.commands` com `ce-source: lender` e `ce-type: studio.lerian.lender.<resource>.<event>`.

A averbação e sua documentação não são comandos do Lender. Envie as duas por meio das operações HTTP autenticadas.

| Chave de definição | `ce-type` | Comportamento em runtime |
| - | - | - |
| `consignado.margin.requested` | `studio.lerian.lender.consignado_margin.requested` | Executa a leitura de margem do trabalhador no trilho. |
| `consignado.exclusao.requested` | `studio.lerian.lender.consignado_exclusao.requested` | Executa pelo mesmo serviço idempotente da operação HTTP autenticada quando o runtime de exclusão está habilitado; caso contrário, retorna um erro nomeado de indisponibilidade. O comando pode cancelar uma averbação que ainda aguarda sua documentação. Um comando para uma averbação cuja documentação está registrada ou em andamento cai na DLQ do consumidor. |

## Fatos consumidos do Lender

O gateway também atua sobre quatro fatos do Lender. Eles chegam em `lerian.streaming.lender` com `ce-source: lender`. O gateway ignora todos os outros fatos do Lender nesse tópico e todo fato de um tenant que ele não atende. Um fato que o gateway não consegue ler cai na DLQ do consumidor.

| Chave de despacho | `ce-type` | Comportamento em runtime |
| - | - | - |
| `assignment_receivable.accepted` | `studio.lerian.lender.assignment_receivable.accepted` | Cede o contrato de `receivable_ref` em `accepted_at` ao fundo de `assignment_fund_id` ou, na falta dele, ao fundo cadastrado no gateway com o CNPJ de `fund_tax_id`, e emite `consignado.cessao.registered`. Cede um contrato que o gateway confirmou por averbação ou importou com a contabilização. Também cede o novo contrato de um refinanciamento ou de uma renegociação que o gateway registrou como aceito. Um contrato já cedido a outro fundo ou um CNPJ que não indica nenhum fundo não muda nada. Um contrato que uma exclusão confirmada ou uma exclusão por portabilidade aceita tirou do registro também não muda nada. |
| `assignment_fund.registered` | `studio.lerian.lender.assignment_fund.registered` | Registra o id de fundo do Lender de `assignment_fund_id`, para que uma averbação possa indicar esse fundo em `fundo_ref`. Até este fato chegar, uma averbação que indica o fundo é recusada com 422 `FUNDO_NOT_REGISTERED`. Sem este fato, registre o fundo no gateway. |
| `assignment_fund.updated` | `studio.lerian.lender.assignment_fund.updated` | Igual a `assignment_fund.registered`. |
| `loan_product_version.created` | `studio.lerian.lender.loan_product_version.created` | Registra a faixa de taxa anual da versão de produto do Lender em `loan_product_version_id`. Uma averbação com o bloco de contabilização que nomeia essa versão responde 422 `RATE_OUTSIDE_PRODUCT_RANGE` quando `monthly_rate` vezes 12 fica fora dessa faixa. |

## Regras de entrega e compatibilidade

* Deduplique por `(ce-source, ce-id)` e torne os handlers idempotentes.
* `ce-id` é um UUID versão 7. Trate-o como opaco e ordene por `ce-time`. Alguns fatos derivam um `ce-id` estável da sua chave de negócio, então todo anúncio do mesmo fato o repete e o `ce-id` não carrega nenhum instante.
* Leia `ce-schemaversion` antes de decodificar. O header carrega a versão do esquema, e o tópico nunca carrega.
* Valores monetários e taxas são strings decimais. Os timestamps estão em UTC, no formato RFC 3339. Valores apenas de data usam `YYYY-MM-DD`, e competências usam `YYYYMM`.
* Chaves de comando de entrada desconhecidas ou sem suporte caem na DLQ do consumidor do Consignado.
* Um identificador de negócio obrigatório ausente impede a publicação ou a execução do comando. O Consignado nunca o sintetiza.


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