Manual Consignado Privado – Averbação e revínculo
1. Averbação nova contratação
Máquina de estados de um contrato novo
1.1 Autorização
Após a formalização de uma nova contratação de consignado privado, será criada a entidade reservation que é utilizada para acompanhar as tentativas de averbação do contrato na DATAPREV e a gestão da garantia após a averbação.
No fluxo ativo, o ambiente pode ser configurado para que a averbação seja criada em um status pendente de autorização ou pode ser criada na fila de averbação, 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.
Quando a averbação é criada com o status pending_requester_authorization, é enviado o webhook:
Webhook Body
{
"webhook_type": "laas.private_payroll.reservation_status_change",
"data": {
"reservation_status": "pending_requester_authorization"
},
"key": "<Debt Key>",
"event_datetime": "2025-04-09T20:00:20Z",
"status": "pending_requester_authorization"
}
Para autorizar a averbação, deve ser enviada a seguinte requisição:
Request
Response sucesso
Response Body
{
"reservation_key": "<Debt Key>",
"document_number": "12345678901",
"registration_number": "99999999999-A",
"employer_document_number": "12345678901234",
"external_key": "abc123def456",
"contract_number": "2024001234",
"inclusion_date": "2024-03-18",
"disbursement_date": "2024-03-20",
"contract_data": {
"amount": 5000.00,
"installments": 12,
"interest_rate": 0.018
},
"reservation_data": {
"installment_value": 500.00,
"margin_value": 450.00
},
"reservation_status": "authorized"
}
Response falha
Response Body
- Operação não encontrada
- Averbação ainda não está pronta para autorização
- Averbação já está autorizada
{
"title" : "Reservation not found",
"code" : "PRP000035",
"description" : "The reservation was not found",
"translation" : "A reserva não foi encontrada",
}
{
"title" : "Reservation is not ready for authorization",
"code" : "PRP000111",
"description" : "The reservation is not ready for authorization",
"translation" : "A reserva não está pronta para autorização"
}
{
"title" : "Reservation is not pending requester authorization",
"code" : "PRP000057",
"description" : "The reservation is not pending requester authorization",
"translation" : "A reserva não está pendente de autorização do requerente",
}
1.2 Averbação
Sucesso na averbação
Em caso de sucesso na averbação o parceiro receberá o seguinte webhook:
Webhook Body
{
"webhook": {
"key": "<UUID>",
"data": {
"collateral_data": {},
"collateral_type": "private_payroll",
"collateral_constituted": true
},
"event_time": "2025-07-10 02:15:01",
"webhook_type": "credit_operation.collateral"
}
}
Falha na averbação
Caso haja uma falha na averbação, será enviado um webhook com a crítica da DATAPREV. Os possíveis motivos de falha na averbação podem ser consultados na tabela Motivo de falha na averbação. 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 cancelada manualmente ou por esgotar as opções de desembolso.
Webhook Body
{
"key": "72926c65-35a5-4060-b5ec-af8661d8546a",
"data": {
"collateral_data": {
"status": "pending_reservation",
"last_response": {
"errors": [
{
"enumerator": "monthly_interest_rate_exceeds_active_proposal"
}
]
},
"last_response_event_datetime": "2025-10-10T19:45:39Z"
},
"collateral_type": "private_payroll",
"collateral_constituted": false
},
"event_time": "2025-10-10 00:07:21",
"webhook_type": "credit_operation.collateral"
}
2. Movimentação de vínculos
A DATAPREV fornece um serviço de atualização de vínculos empregatícios que é consultado diariamente pela QI Tech, neste serviço são informados os contratos que foram encerrados por término de vínculo e os novos vínculos empregatícios dos tomadores que possuem contratos ativos.
A partir das atualizações de desligamento, são disparados webhooks informando a mudança de status das averbações para o status "terminated":
Webhook Body
{
"status": "terminated",
"event_datetime": "2025-03-20T14:47:43Z",
"key": "<Debt Key>",
"webhook_type": "laas.private_payroll.reservation_status_change",
"data": {
"reservation_key": "<Reservation Key>",
"document_number": "12345678901",
"reservation_status": "terminated",
"requester_key": "123e4567-e89b-12d3-a456-426614174000",
"registration_number": "99999999999-A",
"employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
"admission_date": "2025-04-02",
"employer_document_number": "12345678901234",
"external_key": "123e4567-e89b-12d3-a456-426614174000",
"contract_number": "2024001234",
"inclusion_date": "2025-04-02",
"disbursement_date": "2025-04-05",
"reservation_type": "new_credit",
}
}
A partir das atualizações de novos vínculos, são disparados webhooks:
Webhook Body
{
"status": "active",
"event_datetime": "2025-03-20T14:47:43Z",
"key": "<Debt Key>",
"webhook_type": "laas.private_payroll.new_employment_relationship",
"data": {
"document_number": "71742311016",
"registration_number": "123456789ABCDEFR",
"employer_document_number": "02302554000179",
"status": "active",
"employment_relationship_data": {
"name": "LETYCIA AGUILAR DA SILVA",
"eligible": true,
"loan_count": 0,
"employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
"admission_date": "2025-04-02",
"total_due_amount": 1642.16,
"base_margin_amount": 911.67,
"political_exposition": "not_exposed",
"worker_category_code": 101,
"employer_document_type": "CNPJ",
"available_margin_amount": 319.08
}
}
}
3. Averbação revínculo
Máquina de estados de um revínculo
3.1 Autorização
Semelhante ao fluxo de contratação de um novo empréstimo, é possível que a integração seja configurada para que todos os revínculos sejam criados pendente de autorização. Caso seja configurada para revincular automaticamente, ainda assim o casos onde o novo vínculo é informado pela DATAPREV com margem parcial, as novas averbações serão criadas no status pendente de autorização.
Dependendo do status em que o revínculo foi criado, será enviado um webhook informando a criação da nova averbação e seu status (pending_requester_authorization ou pending_reservation):
Webhook Body
- Revínculo criado aguardando autorização
- Revínculo criado na fila para averbação
{
"status": "pending_requester_authorization",
"event_datetime": "2025-03-20T14:47:43Z",
"key": "<Debt Key>",
"webhook_type": "laas.private_payroll.renewed_reservation",
"data": {
"reservation_key": "<Reservation Key>",
"document_number": "12345678901",
"reservation_status": "pending_requester_authorization",
"requester_key": "123e4567-e89b-12d3-a456-426614174000",
"registration_number": "99999999999-A",
"employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
"admission_date": "2025-04-02",
"employer_document_number": "12345678901234",
"external_key": "123e4567-e89b-12d3-a456-426614174000",
"contract_number": "2024001234",
"inclusion_date": "2025-04-02",
"disbursement_date": "2025-04-05",
"reservation_type": "transferred",
}
}
{
"status": "pending_reservation",
"event_datetime": "2025-03-20T14:47:43Z",
"key": "<Debt Key>",
"webhook_type": "laas.private_payroll.renewed_reservation",
"data": {
"reservation_key": "<Reservation Key>",
"document_number": "12345678901",
"reservation_status": "pending_reservation",
"requester_key": "123e4567-e89b-12d3-a456-426614174000",
"registration_number": "99999999999-A",
"employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
"admission_date": "2025-04-02",
"employer_document_number": "12345678901234",
"external_key": "123e4567-e89b-12d3-a456-426614174000",
"contract_number": "2024001234",
"inclusion_date": "2025-04-02",
"disbursement_date": "2025-04-05",
"reservation_type": "transferred",
}
}
3.2 Atualização da margem
Para os casos onde o novo vínculo não tem margem consignável suficiente para averbar a parcela cheia do contrato, é obrigatório que seja realizada a autorização da averbação utilizando o mesmo endpoint de autorização da averbação de nova contratação.
Uma vez autorizado o revínculo com margem parcial, não é possível alterar o valor da averbação posteriormente. Os valores que não forem averbados deverão ser cobrados diretamente do tomador.
É possível atualizar o valor da nova averbação através de uma consulta de dados no novo vínculo, este mecanismo é importante pois é possível que a primeira margem do novo vínculo informada pela DATAPREV seja parcial dependendo do período de contribuição da primeira competência.
3.3 Revínculo
Sucesso
Quando a nova reserva é averbada com sucesso, são enviados dois webhooks informando a alteração de status da averbação original para "transferred" e a alteração de status da nova reserva para "reserved".
Webhook Body
{
"status": "transferred",
"event_datetime": "2025-03-20T14:47:43Z",
"key": "<Debt Key>",
"webhook_type": "laas.private_payroll.reservation_status_change",
"data": {
"reservation_key": "<Reservation Key>",
"document_number": "12345678901",
"requester_key": "123e4567-e89b-12d3-a456-426614174000",
"registration_number": "99999999999-A",
"employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
"admission_date": "2025-04-02",
"employer_document_number": "12345678901234",
"external_key": "123e4567-e89b-12d3-a456-426614174000",
"contract_number": "2024001234",
"inclusion_date": "2025-04-02",
"disbursement_date": "2025-04-05",
"reservation_type": "new_credit",
"reservation_status": "transferred",
}
}
Webhook Body
{
"status": "reserved",
"event_datetime": "2025-03-20T14:47:43Z",
"key": "<Debt Key>",
"webhook_type": "laas.private_payroll.reservation_status_change",
"data": {
"reservation_key": "<Reservation Key>",
"document_number": "12345678901",
"reservation_status": "reserved",
"requester_key": "123e4567-e89b-12d3-a456-426614174000",
"registration_number": "99999999999-A",
"employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
"admission_date": "2025-04-02",
"employer_document_number": "12345678901234",
"external_key": "123e4567-e89b-12d3-a456-426614174000",
"contract_number": "2024001234",
"inclusion_date": "2025-04-02",
"disbursement_date": "2025-04-05",
"reservation_type": "transferred",
}
}
Falha
Diferente da averbação de crédito novo, caso haja uma falha no revínculo por margem excedida, a averbação irá retornar ao status de pendente de autorização. Nestes casos é possível que a margem consignável disponível para o revínculo tenha flutuado, sendo necessário uma nova nova consulta de dados para reavaliar a reaverbação.
Webhook Body
{
"status": "pending_requester_authorization",
"event_datetime": "2025-03-20T14:47:43Z",
"key": "<Debt Key>",
"webhook_type": "laas.private_payroll.reservation_status_change",
"data": {
"reservation_key": "<Reservation Key>",
"document_number": "12345678901",
"reservation_status": "pending_requester_authorization",
"requester_key": "123e4567-e89b-12d3-a456-426614174000",
"registration_number": "99999999999-A",
"employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
"admission_date": "2025-04-02",
"employer_document_number": "12345678901234",
"external_key": "123e4567-e89b-12d3-a456-426614174000",
"contract_number": "2024001234",
"inclusion_date": "2025-04-02",
"disbursement_date": "2025-04-05",
"reservation_type": "transferred",
}
}
Anexos
Motivo 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 |
| 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 |