Manual Consignado Privado - Averbação de Novos Empréstimos: Erros de Averbação

Regras de negócio

Esta página detalha os possíveis erros retornados pela DATAPREV em uma tentativa de averbação, os webhooks que os notificam, e a lógica de retentativa automática ("teimosinha") vs. cancelamento. Para o fluxo de sucesso, veja Autorização e Averbação.

Como uma falha de averbação é notificada

Caso haja uma falha na averbação, o parceiro recebe o seguinte webhook, com os motivos da falha estruturados em uma lista — útil quando há mais de uma crítica retornada pela DATAPREV na mesma tentativa:

Dependendo do erro de averbação, a QI manterá a proposta em "teimosinha", fazendo novas tentativas de averbação até que a operação seja aceita, cancelada manualmente, ou até esgotar as opções de desembolso. A tabela completa de motivos, e se cada um é retentado ou cancela a operação, está em Motivos de falha na averbação.

Webhook dedicado de falha na averbação

Disparado também no revínculo

É disparado tanto para falhas de averbação de um contrato novo quanto para falhas de reaverbação por revínculo (ver Movimentação de Vínculos — Averbação por Revínculo).

webhook_type

laas.private_payroll.reservation_failure

Webhook Body

{
    "webhook_type": "laas.private_payroll.reservation_failure",
    "key": "<External Key>",
    "status": "pending_reservation",
    "event_datetime": "2025-10-10T19:45:39Z",
    "data": {
        "reservation_key": "<Reservation Key>",
        "reservation_status": "pending_reservation",
        "reservation_type": "new_credit",
        "reasons": [
            {
                "enumerator": "monthly_interest_rate_exceeds_active_proposal",
                "description": "There is an active proposal in the borrower's CTPS app sent by QI with a rate lower than the registration attempt",
                "translation": "Há uma proposta ativa no app da CTPS do tomador enviada pela QI com taxa inferior à da tentativa de averbação"
            }
        ]
    }
}

Detalhamento de campos

Campo	Descrição	Valores
reservation_key	Chave da reserva (entidade reservation)	UUID
reservation_status	Status atual da reserva após a falha	pending_reservation, canceled
reservation_type	Método de averbação que originou a tentativa	new_credit, refinancing, portability, transferred
reasons	Lista de motivos da falha retornados pela DATAPREV na tentativa — pode conter mais de um item	Ver Motivos de falha na averbação
reasons[].enumerator	Código do motivo	Ver Motivos de falha na averbação
reasons[].description	Descrição do motivo, em inglês	Texto
reasons[].translation	Descrição do motivo, em português	Texto

"Teimosinha" vs. cancelamento

Cada motivo de falha devolvido pela DATAPREV leva a QI a uma de duas ações:

• Teimosinha (retentativa automática) — para críticas transitórias, que podem deixar de existir sem nenhuma ação do parceiro ou do trabalhador (ex.: a margem consignável se libera na próxima competência, ou a proposta concorrente do app CTPS expira). A operação permanece em pending_reservation e a QI tenta novamente, até aceitar ou esgotar as opções de desembolso.
• Cancelamento da operação — para críticas terminais, que dependem de uma ação fora do controle da QI (o trabalhador desbloquear o vínculo pelo app CTPS, por exemplo) ou que já esgotam por definição o espaço de novas tentativas (limite de contratos por vínculo). A operação vai para canceled e não há novas tentativas.

Motivos de falha na averbação

Enumerador	Descrição	Ação QI
monthly_interest_rate_exceeds_active_proposal	Há uma proposta ativa no app da CTPS do tomador enviada pela QI com taxa inferior à da tentativa de averbação	Teimosinha
margin_exceeded	Margem consignável excedida	Teimosinha
competency_change	Processamento e atualização das informações do Crédito do Trabalhador para virada de competência (crítica transitória)	Teimosinha
allowed_number_of_contracts_exceeded	Quantidade máxima de contratos excedida	Cancelamento da operação
employment_relationship_blocked	Vínculo bloqueado pelo tomador (é possível desbloquear pelo app da CTPS)	Cancelamento da operação

Outros motivos

A DATAPREV pode retornar outras críticas de validação de campos (valores obrigatórios, formato de contrato, taxa de juros, quantidade de parcelas, etc.), listadas na íntegra nos manuais de comunicação da DATAPREV referenciados por este produto. Elas seguem a mesma lógica geral descrita acima.