Manual Consignado Privado - Averbação de Novos Empréstimos: Regras de Negócio

Este manual documenta a colateralização da dívida de um consignado privado no momento da contratação: a reserva de margem na folha de pagamento do empregador (averbação), realizada junto à DATAPREV, e o ciclo de vida dessa tentativa — da criação da garantia até a confirmação de sucesso ou o esgotamento das retentativas em caso de falha.

Vínculo terminou depois de averbado?

Este manual cobre a averbação de um contrato novo. Para o que acontece quando o vínculo empregatício do trabalhador termina e a dívida precisa ser transferida para o novo emprego, veja Movimentação de Vínculos.

Quando usar

Use esta referência para desenhar a esteira de emissão de um consignado privado, entendendo:

• Como e quando a garantia (reservation) é efetivamente constituída após a contratação.
• O que fazer quando o parceiro precisa autorizar a averbação manualmente.
• Como interpretar e reagir aos motivos de falha retornados pela DATAPREV — assunto do foco desta seção, detalhado em Erros de Averbação.

A entidade reservation

Após a formalização de uma nova contratação de consignado privado, é criada a entidade reservation, responsável por:

• Acompanhar as tentativas de averbação do contrato junto à DATAPREV (o registro do desconto na folha de pagamento do empregador).
• Gerir a garantia após a averbação ser aceita — é a partir da averbação bem-sucedida que a garantia passa a estar de fato constituída (collateral_constituted: true), e não antes. Até esse momento, o que existe é apenas uma tentativa registrada, não uma garantia real.

Máquina de estados de um contrato novo

Autorização pendente ou fila de averbação

No fluxo ativo, o ambiente pode ser configurado para que a averbação seja criada em um status pendente de autorização (pending_requester_authorization) ou diretamente na fila de averbação (pending_reservation) — esta configuração deve ser alinhada com o time de operações. No fluxo de leilão, a averbação é sempre criada pendente de autorização.

O endpoint de autorização (identificando a operação pela external_key) e os detalhes de request/response estão em Autorização e Averbação.

Autorizando um revínculo?

A autorização de um revínculo (reaverbação em um novo vínculo empregatício) usa um endpoint próprio, identificado pela reservation_key — ver Movimentação de Vínculos — Averbação por Revínculo.

Consulta de averbação e comprovantes

Além dos webhooks, é possível consultar a qualquer momento os dados de uma averbação específica pela external_key da operação — inclusive os comprovantes de averbação e desaverbação da dívida, disponíveis no objeto protocols da resposta. Também existe uma consulta paginada, para acompanhar várias reservas de uma vez sem precisar conhecer a external_key de cada uma. Ambas estão documentadas em Consulta de Reservas.

Averbação: sucesso, falha e "teimosinha"

Uma tentativa de averbação pode ter sucesso ou falhar de acordo com a crítica devolvida pela DATAPREV. Esse retorno determina o que a QI Tech faz a seguir:

• Falha transitória (ex.: margem consignável momentaneamente insuficiente, ou taxa em conflito com uma proposta ativa do trabalhador no app CTPS) — a QI mantém a operação em retentativa automática ("teimosinha"), tentando novamente a averbação até que ela seja aceita ou até que as opções de desembolso se esgotem.
• Falha terminal (ex.: quantidade máxima de contratos por vínculo excedida, ou vínculo bloqueado pelo próprio trabalhador) — a operação é cancelada, pois não há expectativa de que uma nova tentativa tenha resultado diferente sem uma ação externa (o trabalhador desbloquear o vínculo, por exemplo).

A lista completa de motivos de falha, o webhook dedicado que os notifica de forma estruturada, e a classificação de cada motivo entre retentável e terminal estão detalhados em Erros de Averbação — o foco principal desta seção do manual.

Conteúdo desta seção

1. Autorização e Averbação — página técnica: endpoint de autorização por external_key e webhook de sucesso na averbação.
2. Erros de Averbação — foco nos possíveis erros: o webhook dedicado de falha, a lógica de retentativa ("teimosinha") vs. cancelamento, e a tabela de motivos retornados pela DATAPREV.
3. Consulta de Reservas — consulta por operação (com os comprovantes de averbação/desaverbação em protocols) e consulta paginada de reservas por filtros (documento, tipo e status).
4. Enumeradores — status e método de averbação da reserva.

Glossário

Termo	Significado
reservation	Entidade que acompanha as tentativas de averbação de um contrato na DATAPREV e a gestão da garantia (margem reservada) após a averbação.
Averbação	Reserva da margem consignável na folha de pagamento do empregador, garantindo o desconto das parcelas.
Desaverbação	Liberação da margem previamente reservada.
"Teimosinha"	Retentativa automática de averbação feita pela QI Tech quando a tentativa falha por um motivo não terminal.
private_payroll	collateral_type da garantia de folha de pagamento de funcionários de empresas privadas.